ichimoku: The OANDA fxTrade API

About OANDA fxTrade

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

OANDA is a primary source of foreign exchange data used by corporations and governments around the world. The API can be used for retrieving historical and live streaming price data for major currencies, metals, commodities, government bonds and stock indices.

As an example of the financial data that is available: OHLC pricing data can be obtained for major forex pairs from the start of 2005 with 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.

Setting your OANDA API Key

If the ‘keyring’ package is installed, 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.

Separate keys can be set for practice and live accounts; please choose the correct account type when prompted.

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

Using a Live Account

If you are using an access token for a live (real money) account, you will want to call oanda_switch() at the beginning of each session; this switches the default server from the practice server to the live server. Settings will only persist until the end of the session.

library(ichimoku)

oanda_switch()
#> Default OANDA server switched to 'live'

Note: this package only contains functions for retrieving available instruments and price data. It does not contain code to implement any trading capability whatsoever. Please be aware however, that a personal access token can be used (outside of this package) for all operations on your account including placing orders and trades, and appropriate precautions should be taken when using your live account token.

The OANDA Functions

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

Functions may be called interactively without any arguments, e.g. oanda_stream() or oanda_view(), in which case you will be further prompted to enter required arguments; as opposed to when specifying such arguments normally, these should be entered unquoted i.e. without any surrounding ““.

For all functions, the ‘instrument’ argument is case-insensitive and the delimiter can be either ’_’ or ‘-’, such that both oanda("USD_JPY") and oanda("usd-jpy") would be acceptable.

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:

Note: if both from and to are specified and the request would result in over 5000 periods being returned, the function 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, and merged together into a single dataframe. The function is safe for use in non-interactive settings as in such cases the download will proceed automatically without prompting.

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’.

Important implementation notes:

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:

The arguments ‘from’ and ‘to’ are excluded as they are not relevant in this context.

# For a live Palladium price chart:
oanda_chart("XPD_USD")

In RStudio, please switch to the plots plane to view the chart if not already in focus.

Note that the periods displayed on the chart will be fewer than the ‘count’ specified - using default cloud periods, the first 77 datapoints will be excluded. This is by design to ensure a full cloud is displayed (i.e. there are no missing values for any cloud lines at the start of the data). Please take this into account when setting the ‘count’ parameter.

On exit from the function, the ichimoku object underlying the chart will be returned (invisibly). This allows the data to be saved simply by assigning to an object.

# To access the data, simply assign the return value to an object:
cloud <- oanda_chart("XPD_USD")

oanda_studio()

Create an interactive R Shiny session 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, oanda_studio() may be called without specifying any arguments. Otherwise, parameters may be set beforehand in the same way as oanda_chart().

oanda_studio()

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

Downloading Data

The ichimoku object underlying the live cloud chart can be saved by selecting the Data Archive button.

This button uses archive() to save the ichimoku object to disk. The filename will be of the form: instrument_granularity_price.rda, e.g. SUGAR_USD_D_A.rda. If confirmed, the file is saved to the browser’s default download location. Note that files with the same name are not overwritten but instead the filename is made unique.

To read back the file, use archive():

# Supply the quoted file path / name, for example:
cloud <- archive("~/Downloads/SUGAR_USD_D_A.rda")

# Or alternatively, choose the saved file interactively using a system dialog:
cloud <- archive()

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.

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

oanda_stream("UK10YB_GBP")
#> Streaming data... Press 'Esc' to return
#> type:PRICE  time:2021-10-01T16:59:51.377314414Z  
#> bids: price:126.500  liquidity:10000   asks: price:126.540  liquidity:10000  
#> closeoutBid:126.500  closeoutAsk:126.540  status:non-tradeable  tradeable:false  instrument:UK10YB_GBP

The stream output contains injected ANSI escape codes for formatting the console output, 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:

oanda_quote()

A convenience function that outputs to the console the latest one-line price quote for an instrument.

The output format is as follows: instrument, timestamp, daily open, high, low and last prices, daily percentage change (from the open), and the pricing component (M for mid, B for bid, A for ask).

oanda_quote("USD_JPY")
#> USD_JPY 2021-10-05 16:29:44 open: 110.931  high: 111.564  low: 110.871  last: 111.398  %chg: 0.421 M

oanda_view()

Prints a snapshot overview of the selected market, showing the relative performance of all constituents.

The available markets are : ‘allfx’ for all available currencies, ‘bonds’ for government bonds, ‘commodities’ for commodities, ‘fx’ for major currency pairs, ‘metals’ for metals and ‘stocks’ for global stock markets. As partial matching is enabled, it is possible to type just the first letter e.g. ‘c’ for commodities.

The first retrieved timestamp and the pricing component are printed, followed by the dataframe showing similar data to oanda_quote() for all instruments in the selected market. The data is ordered by the daily percentage change, from the most positive to the most negative.

oanda_view()
Enter market [a]llfx [b]onds [c]ommodities [f]x [m]etals [s]tocks: c
#> Retrieving commodities [.........]
#> 2021-10-13 23:42:58 / M
#>               open    high     low    last    %chg
#> TWIX_USD     654.0   658.4   644.6   657.6  0.5505
#> WTICO_USD   80.614  80.819  80.589  80.779  0.2047
#> XCU_USD    4.47846 4.49068 4.47821 4.48719  0.1949
#> BCO_USD     83.871  83.879  83.858  83.873  0.0024
#> SOYBN_USD   12.113  12.237  11.966  12.091 -0.1816
#> NATGAS_USD   5.644   5.649   5.616   5.630 -0.2481
#> SUGAR_USD  0.19468 0.19530 0.19230 0.19242 -1.1609
#> WHEAT_USD    7.280   7.304   7.054   7.104 -2.4176
#> CORN_USD     5.454   5.466   5.274   5.322 -2.4202

oanda_positions()

Provides a summary of the aggregate positions held by OANDA fxTrade clients at each price level.

The data is returned as a dataframe, with parameters saved as attributes which can be viewed with look(). A chart showing the percentage long and short positions at each price level is output to the graphical device.

Please note that this feature has been implemented by OANDA only for certain major currency pairs and should be considered experimental.

Available Instruments

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

The list below serves as a reference only and may differ from those actually available for your account type and/or country/region.

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

Note: the above table is saved as internal package data and used as a fallback if the API call fails. In such a case, a warning is issued once per session as subsequent calls will return the cached list.

Caching Implementation

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

If for any reason these become invalid or outdated, please re-load the package (or restart your R session) to enable these variables to be refreshed.

Calling oanda_switch() will also clear all cached variables.

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.2.4, https://CRAN.R-project.org/package=ichimoku.