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 by governments and global 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.

It is considered a rich source of financial data with excellent availability. As an example, daily OHLC pricing data is available for major forex pairs from the start of 2005, with data granularity ranging from 5 seconds to monthly. For the total list of over 120 covered instruments please refer to the Available Instruments section below.

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

Registering with OANDA

The OANDA fxTrade API, as distinct to other OANDA data sources, is based upon its retail and professional trading offering of the same name. As such, access to the API requires an fxTrade account with OANDA and agreement to their API terms of use.

Registering for a ‘demo’ or ‘practice’ account is entirely free at the time of writing and provides full access to the API. 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 saved in your system credential store 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 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. If both ‘from’ and ‘to’ are specified, ‘count’ is ignored, 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’

Note: if both from and to are specified and the request would result in over 5000 periods being returned, the function automatically prompts the user to confirm if multiple requests should be submitted. Unless the user response is “n” or “no”, the data will proceed to be downloaded with rate limiting in place as per API best practices, and merged together into a single dataframe.

library(ichimoku)
oanda("USD_JPY", count = 3, from = "2010-11-01", price = "B")

#>                  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()

`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. As this is a raw feed, please note that the returned times are in UTC.

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 an updating real-time Ichimoku 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 set the refresh rate of the chart in seconds, with a minimum of 1
... additional parameters passed onto ichimoku() for calculating the ichimoku cloud or autoplot() to set chart parameters
periods [default c(9L, 26L, 52L)] a vector defining the length of periods used for the cloud. This parameter should not normally be modified as using other values would be invalid in the context of traditional Ichimoku analysis

The arguments ‘from’ and ‘to’ are 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 also that the periods displayed on the chart will be fewer than the ‘count’ specified. This is by design to ensure a full cloud is always displayed (i.e. there are no missing values for certain cloud lines at the start of the data). If using the default cloud periods, the first 77 datapoints will be excluded from the chart. Please take this into account when setting the ‘count’ parameter.

`oanda_studio()`

Create an interactive session in an R Shiny app for working with real-time Ichimoku cloud charts. Provides a live analysis environment where parameters may be set interactively as required. The cursor infotip provides ready access to the data directly from the chart.

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

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

... additional arguments passed to ichimoku() for calculating the ichimoku cloud, autoplot() to set chart parameters, or 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

Caching Implementation

The package retrieves the following once only during a single R session (the first time they are used) and caches the variables for further use throughout the session:

OANDA fxTrade API key
OANDA fxTrade account associated with an fxTrade API key
OANDA list of available instruments

If for any reason these become invalid or outdated, please restart your R session to enable these variables to be refreshed.

References

‘OANDA’ and ‘fxTrade’ are trademarks owned by OANDA Corporation, an entity unaffiliated with the ichimoku package.

OANDA fxTrade API developer website: https://developer.oanda.com/.

Gao, C. (2021), ichimoku: Visualization and Tools for Ichimoku Kinko Hyo Strategies. R package version 1.0.0, https://CRAN.R-project.org/package=ichimoku.