Get started with Oanda data

This tutorial describes the steps to set up a new AWTS environment with the dataoanda module for Oanda market data, and then how to use it to download and stream instrument/price data.

The dataoanda module provides reliable, high-performance access to Oanda market data, including:

• automatic API rate limit handling
• automatic reconnect/retry
• no more 5000-candle response size limits
• full streaming support (Oanda's API does not support streaming)
• simulate order fills

You will need

• Compatible hardware (see Installation)
• An Oanda account and API key. You can obtain an API key from https://developer.oanda.com/rest-live-v20/introduction/
• About five minutes

The steps describe here are almost identical for any other data vendor - just with different credentials/secrets depending on the vendor's API authentication processes.

Create a configuration

First, sign in to https://account.alphaweighted.com and go to the Configurator. You should see a screen like the below, for creating a new Configuration:

Use this to create a Configuration. You can create an empty one, or pick from the list of presets/templates for quicker setup.

Add the Oanda module

Switch to the Modules tab, select the 'Oanda market data' module from the list and hit 'Add module'.

Check the 'Paper account' box if you intend to use a paper/demo account. This is important because Oanda's API endpoints are different for paper accounts vs live accounts.

You cannot enter API keys here; do this after downloading the configuration.

Don't forget to Save changes!

Get installation instructions

After saving, switch to the Install tab. AWTS automatically generates configuration files based on everything you chose on the previous screens.

For a Docker Compose install (recommended), AWTS generates two files; the docker-compose.yml itself and a basic shell script (install.sh) which contains commands and instructions for how to set up.

A license key is shown in the screenshot. Yours will be shown to you. Each key is unique to your account and to the Configuration you created. Keep it confidential. More about licensing.... The license key is included automatically in docker-compose.yml so you don't need to do anything manually to manage it.

Note: You can edit the docker-compose.yml file after downloading. Just be careful to reapply any changes if you edit the configuration online and re-download in future.

Local setup

Follow the instructions given in the online page above to download docker-compose.yml and update the secrets files with your Oanda account ID and API key.

❯ ls -l
.rw-r--r--   20 userme 22 Dec 10:28 dataoanda_account.txt
.rw-r--r--   66 userme 22 Dec 10:28 dataoanda_apikey.txt
.rw-r--r-- 1.4k userme 22 Dec 10:28 docker-compose.yml

Start your environment

Start your environment by running docker-compose up. Docker images for your configured modules will be downloaded automatically and the services should start up successfully.

❯ docker-compose up
[+] Running 2/0
 ✔ Network tut_01_dataoanda_awts_default  Created
 ✔ Container dataoanda                    Created
Attaching to dataoanda
dataoanda  | {"time":"2023-12-22T12:31:17.633738814Z","level":"INFO","msg":"[Verifying license...] "}
dataoanda  | {"time":"2023-12-22T12:31:17.834634147Z","level":"INFO","msg":"[License applied successfully] "}
dataoanda  | {"time":"2023-12-22T12:31:18.080729992Z","level":"INFO","msg":"123 instruments found on Oanda account"}
dataoanda  | {"time":"2023-12-22T12:31:18.080857861Z","level":"INFO","msg":"Oanda streamPrices connecting..."}
dataoanda  | {"time":"2023-12-22T12:31:18.090427753Z","level":"INFO","msg":"[Listening on :36000 TLS= none] "}

Use Docker's -d option (docker-compose up -d) to bring AWTS up in the background as a continuously running service which will start automatically on boot and restart automatically if killed.

Test with the CLI tool

Your AWTS environment is now reachable at localhost:36000.

Install the CLI tool

The CLI tool is a simple and versatile way to interact with an AWTS environment. See the Installation instructions or just grab the latest release from GitHub at https://github.com/alphaweighted/cli/releases.

Download the .tar.gz for your platform and extract it to get the awts binary. You can run it with no parameters to get help and list available commands:

❯ awts
AWTS CLI interface - Command line tool for interacting with AWTS environments

Usage:
  cli [command]

Available Commands:
  admin       Administrative outputs, including license status/details
  book        Interact with books (see subcommands)
  candles     A shorthand for 'data candles', retrieve candles for an instrument
  chart       Push a chart to a dash widget
  completion  Generate the autocompletion script for the specified shell
  config      Dump config info
  dash        Interact with dashboards
  data        Interact with market data (candles, streaming, price)
// snip...

Find an instrument

We chose a data module earlier, so we will use the data commands to interact - run awts data to see available data commands.

First lets search for SPX:

❯ awts --mux=localhost:36000 data search SPX
+------------------+------------+
| SYMBOL           | NAME       |
+------------------+------------+
| OANDA:SPX500_USD | US SPX 500 |
+------------------+------------+

We see one matching instrument, with symbol OANDA:SPX500_USD. Symbols in AWTS, by default, follow the form PREFIX:TICKER[:DERIVATIVE] where the PREFIX part denotes the data module providing the data. see Symbology for more information about how AWTS handles symbols.

Note: Adding --mux=XXX every time gets tiresome. Set the environment variable AW_MUX to the same value; the CLI tool accepts environment variables in this pattern for any command-line argument. Then you don't have to specify it every time.

Get the current price

As data sources can represent all sorts of time series data - not just asset prices - the term value is used. Use the CLI command awts data value <symbol> to retrieve current value/price data:

❯ awts --mux=localhost:36000 data value OANDA:SPX500_USD
+-----------------------+----------------------+
| At                    | 2023-12-22T10:49:32Z |
| Value last updated at | 2023-12-22T10:49:32Z |
| Value                 | 4751                 |
| Bid                   | 4750.8               |
| Ask                   | 4751.2               |
+-----------------------+----------------------+

Export candle data

View or export candle data with the awts data candles <symbol> command.

You must specify resolution in the form H1, D, M5, etc.

Use --from and --to dates to time bound the export. Dates must be specified in ISO format and can be just dates or date+time (i.e. yyyy-mm-dd or yyyy-mm-ddThh:mm:ss).

By default the output is printed formatted to the console as shown below. You can use --format=csv and pipe the output to a CSV file to produce export files for offline processing elsewhere.

❯ awts data candles OANDA:NAS100_USD --resolution=M15 --from=2023-12-01T00:00:00
                Timestamp         Vol         O         H         L         C      Vwap    Spread
     2023-12-01T00:00:00Z          35  15931.40  15932.80  15926.80  15931.80  15930.70      1.90
     2023-12-01T00:15:00Z          18  15930.80  15931.80  15928.60  15930.40  15930.40      1.90
     2023-12-01T00:30:00Z          20  15929.20  15929.60  15925.60  15927.80  15928.05      1.90
     2023-12-01T00:45:00Z          29  15926.80  15928.40  15924.20  15927.60  15926.75      1.90
     2023-12-01T01:00:00Z          42  15926.80  15929.80  15922.40  15922.60  15925.40      1.90
...snip...

Note that VWAP and spread are included. Spread is included because the Oanda API provides both bid and ask prices. Other data modules may have zero spread if this data is not available.

Oanda do not provide VWAP, but VWAP is an integral part of AWTS so it is included in all data sources, and approximated where the upstream broker/vendors does not provide VWAP (and/or tick data). See the VWAP documentation for more details. Inspecting an instrument (awts data instrument <symbol>) will include specifics about how VWAP is calculated for each instrument.

Access with Python

AWTS services can be accessed with any popular language, see the API documentation for details. Here's a brief example of how to access the data APIs directly with Python.

Install

First, use pip to install the API client code - these packages are auto-generated from the API specs:

# install gRPC libraries
pip install grpcio
# install AWTS client libraries
pip install --extra-index-url=https://buf.build/gen/python alphaweighted-awts-protocolbuffers-python
pip install --extra-index-url=https://buf.build/gen/python alphaweighted-awts-grpc-python

Connect

Set up a connection to the server.

import awts.data.v1.data_pb2 as awtsdata
from awts.data.v1.data_pb2_grpc import DataServiceStub

import grpc

channel = grpc.insecure_channel('localhost:36000')
stub = DataServiceStub(channel)

Get current value/price for the SPX CFD

Make a simple request to the Value() method in the data service, and print the last value. Note that all numeric values are passed as decimals (not floats) for full precision:

req = awtsdata.ValueRequest()
req.ref = "OANDA:SPX500_USD"

resp = stub.Value(req)
print(resp.last.value)

Get candles

Here we set up a fuller request to retrieve candle data from Oanda, and print the timestamp and closing price for each:

import time
from datetime import datetime
from google.protobuf.timestamp_pb2 import Timestamp

now = datetime.utcnow()

# start from 10 days ago
fromTimestamp = Timestamp()
fromTimestamp.seconds = int(time.mktime(now.timetuple())) - 86400*10
fromTimestamp.nanos = now.microsecond * 1000

# up to now
toTimestamp = Timestamp()
toTimestamp.seconds = int(time.mktime(now.timetuple()))
toTimestamp.nanos = now.microsecond * 1000

# set up the request
req = awtsdata.CandlesRequest()
req.ref = "OANDA:SPX500_USD"
req.resolution = 3600
getattr(req, 'from').CopyFrom(fromTimestamp)
getattr(req, 'to').CopyFrom(toTimestamp)
req.pad = False

# make the request
resp = stub.Candles(req)

# print the timestamp and close price for each candle
for x in resp.candles:
    ts = datetime.fromtimestamp(x.time)
    print(ts, "close =", x.c)

Profit!

That's it - you now have a high performance, interactive, live streaming interface to Oanda market data. Time to build some strategies!

Further reading:

• [Streaming market data]({{% ref "/docs/quickstart/streaming-market-data" %}})
• The dataoanda module
• How AWTS handles data