ichimoku: The OANDA fxTrade API

About OANDA fxTrade

ichimoku contains an interface to the OANDA fxTrade API, creating a binding for the R language.

OANDA is an authoritative source of foreign exchange data used globally by governments and corporations alike. The API can be used for retrieving historical and live streaming price data for major currencies, metals, commodities, government bonds and stock indices.

This is considered a rich source of financial data with excellent availability, for instance daily OHLC pricing data for major forex pairs going back to the start of 2005, and data granularity ranging from 5 seconds to monthly.

Please note that ‘OANDA’ and ‘fxTrade’ are trademarks owned by OANDA Corporation, an entity which is entirely unaffiliated with the ichimoku package.

Registering with OANDA

The OANDA fxTrade API, as distinct to other OANDA data sources such as its rates for business, is based upon their retail and professional trading offering. As such, access to the API requires an fxTrade account with OANDA and agreement to their API terms of use. Any account type is sufficient, including a ‘demo’ or ‘practice’ account, which at the time of writing is entirely free to sign up and use without limit.

For registering an account, the following URL may be used: https://www.oanda.com/forex-trading/.

After successful registration, a link can be found on your OANDA fxTrade account profile page ‘Manage API Access’ (My Account -> My Services -> Manage API Access). From there, a personal access token to use with the OANDA API can be generated, as well as revoked. This access token will enable all the OANDA functions in this package.

Note: this package only contains functions for retrieving available instruments and price data. It does not contain any code which implements any trading capability whatsoever. Hence using your access token with this package should be safe even for live accounts. However, the access token can be used (outside of this package) for all operations on your account including placing orders and trades. It is recommended therefore, for maximum security, that you sign up for a demo/practice account and use the access token for that account even if you hold an existing live account with OANDA.

Setting your OANDA API Key

If the ‘keyring’ package is available on your machine, the OANDA API key (personal access token) can be set once and stored in your system keyring by using oanda_set_key(). This will enable it to be retrieved automatically for all subsequent sessions.

If an access token is revoked and re-generated, please remember to set the API key again through the oanda_set_key() function.

The OANDA Functions

All of the OANDA functions in the package are prefixed by ‘oanda’ for clarity and ease of use.

`oanda()`

Retrieve historical pricing data from the OANDA fxTrade API.

The arguments to the function are phrased identically to that of the API itself where relevant:

instrument a string containing the base currency and quote currency delimited by a ’_’ (for example “USD_JPY”). Use the oanda_instruments() function to return a list of all valid instruments.
granularity [default “D”] the granularity of the price data to fetch, one of “M”, “W”, “D”, “H12”, “H8”, “H6”, “H4”, “H3”, “H2”, “H1”, “M30”, “M15”, “M10”, “M5”, “M4”, “M2”, “M1”, “S30”, “S15”, “S10”, “S5”.
count (optional) the number of periods to return. The API supports a maximum of 5000 for each individual request, and defaults to 500 if not specified. ‘count’ should not be specified if both ‘from’ and ‘to’ arguments are provided, as the time range combined with ‘granularity’ will determine the number of periods to return.
from (optional) the start of the time range for which to fetch price data, for example “2020-02-01”.
to (optional) the end of the time range for which to fetch price data, for example “2020-06-30”.
price [default “M”] the pricing component, one of “M” (midpoint), “B” (bid) or “A” (ask).
server [default “practice”] select either the “practice” or “live” server depending on the account type held with OANDA.
apikey (optional) string containing the OANDA fxTrade API key (personal access token). This argument is designed for specifying a function that returns such a string rather than the string itself, which could be potentially unsecure. This allows other packages that provide secure storage of secrets to be used if preferred over ‘keyring’.

library(ichimoku)
oanda("USD_JPY", count = 3, from = "2010-11-01", price = "B", apikey = NULL)
#>                  time   open   high    low  close volume complete
#> 1 2010-11-01 21:00:00 80.275 81.504 80.225 80.501  22291     TRUE
#> 2 2010-11-02 21:00:00 80.504 80.956 80.460 80.617  13795     TRUE
#> 3 2010-11-03 21:00:00 80.632 81.585 80.594 81.069  22204     TRUE

The returned object is a dataframe with the following columns: ‘time’, ‘open’, ‘high’, ‘low’, ‘close’, ‘volume’ and ‘complete’.

volume should normally be disregarded as this reflects the trading volume registered by OANDA and may not be reflective of the broader market.
complete indicates whether the data period is complete or not. If TRUE, the values are historical and not subject to change. If FALSE, the period is ongoing and the values reflect the current snapshot and the final values may or may not differ.

Important implementation notes:

Incorporates automatic adjustment of the timestamps to end of period, as is customary for financial data. This means that, for example, today’s pricing data (incomplete trading period) will have today’s date as would be expected. In contrast, the raw data from the API has a timestamp of the start of the period.
The API data sometimes includes data for non-trading days with very low volumes. This is more common for older data and less so with more recent data. These may represent OTC trades that occurred over the OANDA platform, but nevertheless do not reflect market rates. These are automatically excluded from the data returned as they would otherwise produce spurious results if used with ichimoku().

For diagnostic purposes only, the parameter .validate = FALSE may be set to view the original data retrieved from the API without the automatic validation adjustments above. This parameter should not otherwise be set.

`oanda_stream()`

Connect to the OANDA fxTrade streaming API and stream a list of prices generated by OANDA.

Requires a single argument, the ‘instrument’ to stream data for (please refer to oanda() above).

The ‘server’ and ‘apikey’ arguments are also available if required.

The streamed data is formatted for legibility, including the use of colour blocks in the console, but otherwise represents the raw data feed without omission.

The following should be noted from the streaming API documentation:

Get a stream of Account Prices starting from when the request is made.
This pricing stream does not include every single price created for the Account, but instead will provide at most 4 prices per second (every 250 milliseconds) for each instrument being requested.
If more than one price is created for an instrument during the 250 millisecond window, only the price in effect at the end of the window is sent.
This means that during periods of rapid price movement, subscribers to this stream will not be sent every price.
Pricing windows for different connections to the price stream are not all aligned in the same way (i.e. they are not all aligned to the top of the second). This means that during periods of rapid price movement, different subscribers may observe different prices depending on their alignment.

`oanda_chart()`

Create a live updating Ichimoku Kinko Hyo (cloud chart). The refresh rate can be set for the chart to be updated down to every second. A plot of the ichimoku chart for the price data requested is output to the graphical device at each refresh interval.

The arguments are identical to oanda() above with the addition of ‘refresh’ as the third argument to set the refresh rate of the chart in seconds, with a minimum of 1. ‘from’ and ‘to’ are also excluded as they are not relevant in this context.

If focus is not initially on the plot pane (in RStudio), please switch to it to view the chart.

Note that returned times are represented in UTC.

`oanda_studio()`

Create an interactive session in an R Shiny app for working with dynamically-generated Ichimoku Kinko Hyo (cloud charts).

As all parameters may be set interactively in-app, the function can be launched as oanda_studio() without specifying any arguments. Otherwise, parameters may be set beforehand in the same way as oanda_chart().

The use of this function provides a live analysis environment where parameters may be set interactively as required. The infotip provides ready access to the underlying data in a convenient manner.

The following additional parameters can be used to customise the behaviour of the Shiny app:

... additional parameters passed along to the ‘options’ argument of shiny::shinyApp().
launch.browser [default TRUE] If TRUE, the system’s default web browser will be launched automatically after the app is started. The value of this argument can also be a function to call with the application’s URL. To use the default Shiny viewer in RStudio, please specify getOption("shiny.launch.browser").

Available Instruments

The list of financial instruments below serves as a reference only and may not be exhaustive and/or differ from those available for your account type or country/region.

The list of financial instruments available for your account may be retrieved by oanda_instruments(). The available instruments are also automatically populated as an input in oanda_studio().

#>           name.....type.....displayName
#> 1    AU200_AUD      CFD   Australia 200
#> 2      AUD_CAD CURRENCY         AUD/CAD
#> 3      AUD_CHF CURRENCY         AUD/CHF
#> 4      AUD_HKD CURRENCY         AUD/HKD
#> 5      AUD_JPY CURRENCY         AUD/JPY
#> 6      AUD_NZD CURRENCY         AUD/NZD
#> 7      AUD_SGD CURRENCY         AUD/SGD
#> 8      AUD_USD CURRENCY         AUD/USD
#> 9      BCO_USD      CFD Brent Crude Oil
#> 10     CAD_CHF CURRENCY         CAD/CHF
#> 11     CAD_HKD CURRENCY         CAD/HKD
#> 12     CAD_JPY CURRENCY         CAD/JPY
#> 13     CAD_SGD CURRENCY         CAD/SGD
#> 14     CHF_HKD CURRENCY         CHF/HKD
#> 15     CHF_JPY CURRENCY         CHF/JPY
#> 16     CHF_ZAR CURRENCY         CHF/ZAR
#> 17    CN50_USD      CFD       China A50
#> 18    CORN_USD      CFD            Corn
#> 19  DE10YB_EUR      CFD            Bund
#> 20    DE30_EUR      CFD      Germany 30
#> 21    EU50_EUR      CFD       Europe 50
#> 22     EUR_AUD CURRENCY         EUR/AUD
#> 23     EUR_CAD CURRENCY         EUR/CAD
#> 24     EUR_CHF CURRENCY         EUR/CHF
#> 25     EUR_CZK CURRENCY         EUR/CZK
#> 26     EUR_DKK CURRENCY         EUR/DKK
#> 27     EUR_GBP CURRENCY         EUR/GBP
#> 28     EUR_HKD CURRENCY         EUR/HKD
#> 29     EUR_HUF CURRENCY         EUR/HUF
#> 30     EUR_JPY CURRENCY         EUR/JPY
#> 31     EUR_NOK CURRENCY         EUR/NOK
#> 32     EUR_NZD CURRENCY         EUR/NZD
#> 33     EUR_PLN CURRENCY         EUR/PLN
#> 34     EUR_SEK CURRENCY         EUR/SEK
#> 35     EUR_SGD CURRENCY         EUR/SGD
#> 36     EUR_TRY CURRENCY         EUR/TRY
#> 37     EUR_USD CURRENCY         EUR/USD
#> 38     EUR_ZAR CURRENCY         EUR/ZAR
#> 39    FR40_EUR      CFD       France 40
#> 40     GBP_AUD CURRENCY         GBP/AUD
#> 41     GBP_CAD CURRENCY         GBP/CAD
#> 42     GBP_CHF CURRENCY         GBP/CHF
#> 43     GBP_HKD CURRENCY         GBP/HKD
#> 44     GBP_JPY CURRENCY         GBP/JPY
#> 45     GBP_NZD CURRENCY         GBP/NZD
#> 46     GBP_PLN CURRENCY         GBP/PLN
#> 47     GBP_SGD CURRENCY         GBP/SGD
#> 48     GBP_USD CURRENCY         GBP/USD
#> 49     GBP_ZAR CURRENCY         GBP/ZAR
#> 50    HK33_HKD      CFD    Hong Kong 33
#> 51     HKD_JPY CURRENCY         HKD/JPY
#> 52    IN50_USD      CFD        India 50
#> 53   JP225_USD      CFD       Japan 225
#> 54  NAS100_USD      CFD      US Nas 100
#> 55  NATGAS_USD      CFD     Natural Gas
#> 56    NL25_EUR      CFD  Netherlands 25
#> 57     NZD_CAD CURRENCY         NZD/CAD
#> 58     NZD_CHF CURRENCY         NZD/CHF
#> 59     NZD_HKD CURRENCY         NZD/HKD
#> 60     NZD_JPY CURRENCY         NZD/JPY
#> 61     NZD_SGD CURRENCY         NZD/SGD
#> 62     NZD_USD CURRENCY         NZD/USD
#> 63    SG30_SGD      CFD    Singapore 30
#> 64     SGD_CHF CURRENCY         SGD/CHF
#> 65     SGD_JPY CURRENCY         SGD/JPY
#> 66   SOYBN_USD      CFD        Soybeans
#> 67  SPX500_USD      CFD      US SPX 500
#> 68   SUGAR_USD      CFD           Sugar
#> 69     TRY_JPY CURRENCY         TRY/JPY
#> 70    TWIX_USD      CFD    Taiwan Index
#> 71   UK100_GBP      CFD          UK 100
#> 72  UK10YB_GBP      CFD     UK 10Y Gilt
#> 73  US2000_USD      CFD    US Russ 2000
#> 74    US30_USD      CFD   US Wall St 30
#> 75  USB02Y_USD      CFD    US 2Y T-Note
#> 76  USB05Y_USD      CFD    US 5Y T-Note
#> 77  USB10Y_USD      CFD   US 10Y T-Note
#> 78  USB30Y_USD      CFD       US T-Bond
#> 79     USD_CAD CURRENCY         USD/CAD
#> 80     USD_CHF CURRENCY         USD/CHF
#> 81     USD_CNH CURRENCY         USD/CNH
#> 82     USD_CZK CURRENCY         USD/CZK
#> 83     USD_DKK CURRENCY         USD/DKK
#> 84     USD_HKD CURRENCY         USD/HKD
#> 85     USD_HUF CURRENCY         USD/HUF
#> 86     USD_INR CURRENCY         USD/INR
#> 87     USD_JPY CURRENCY         USD/JPY
#> 88     USD_MXN CURRENCY         USD/MXN
#> 89     USD_NOK CURRENCY         USD/NOK
#> 90     USD_PLN CURRENCY         USD/PLN
#> 91     USD_SEK CURRENCY         USD/SEK
#> 92     USD_SGD CURRENCY         USD/SGD
#> 93     USD_THB CURRENCY         USD/THB
#> 94     USD_TRY CURRENCY         USD/TRY
#> 95     USD_ZAR CURRENCY         USD/ZAR
#> 96   WHEAT_USD      CFD           Wheat
#> 97   WTICO_USD      CFD  West Texas Oil
#> 98     XAG_AUD    METAL      Silver/AUD
#> 99     XAG_CAD    METAL      Silver/CAD
#> 100    XAG_CHF    METAL      Silver/CHF
#> 101    XAG_EUR    METAL      Silver/EUR
#> 102    XAG_GBP    METAL      Silver/GBP
#> 103    XAG_HKD    METAL      Silver/HKD
#> 104    XAG_JPY    METAL      Silver/JPY
#> 105    XAG_NZD    METAL      Silver/NZD
#> 106    XAG_SGD    METAL      Silver/SGD
#> 107    XAG_USD    METAL          Silver
#> 108    XAU_AUD    METAL        Gold/AUD
#> 109    XAU_CAD    METAL        Gold/CAD
#> 110    XAU_CHF    METAL        Gold/CHF
#> 111    XAU_EUR    METAL        Gold/EUR
#> 112    XAU_GBP    METAL        Gold/GBP
#> 113    XAU_HKD    METAL        Gold/HKD
#> 114    XAU_JPY    METAL        Gold/JPY
#> 115    XAU_NZD    METAL        Gold/NZD
#> 116    XAU_SGD    METAL        Gold/SGD
#> 117    XAU_USD    METAL            Gold
#> 118    XAU_XAG    METAL     Gold/Silver
#> 119    XCU_USD      CFD          Copper
#> 120    XPD_USD    METAL       Palladium
#> 121    XPT_USD    METAL        Platinum
#> 122    ZAR_JPY CURRENCY         ZAR/JPY

Further Resources

Package website: https://shikokuchuo.net/ichimoku/

The most recent version of the package may be found at https://github.com/shikokuchuo/ichimoku/