oanda-candles 0.0.7

Oanda forex candle API built on top of oandapyV20

oanda-candles

Oanda forex candle API built on top of oandapyV20

CAVEAT:

This is still in rapid initial development and features might change drastically.

new in version 0.0.7:

1. The CandleSequence has been cleaned up and plans to add merging have been abandoned.
2. The Candle class no longer has __lt__ overloaded and __eq__ is now based on all the values being equal rather than just the candle time.
3. A new CandleCollector class is added which is like a higher level CandleSequence specifically designed for chart applications that always want a specific number of latest candles.
4. No unit testing has been added for these changes, they have only been sand-boxed, so they may not work as advertised. Also the market was closed when I sand-boxed CandleCollector, so some of its heursitics have not even been sand-box tested yet.

Oanda Access Token

Using this package requires an access token to a user's Oanda brokerage account. This module only uses the token to request candle data, but such tokens can be used to make trades on the account. It is recommended that access tokens from a demo as opposed to a live accounts be used.

Demo account tokens can be generated by a signed in user here:

https://www.oanda.com/demo-account/tpa/personal_token

Warning: Oanda sometimes takes their API down for maintenance. This seems to mostly occur shortly after the market closes at the end of the trading week (at 5pm New York time). During the maintenance you may get a 401 http response that looks like your token is not valid even if it is.

Quick Example

Supposing that token is in the env var OANDA_TOKEN, one could print the opening bid price of the latest 100 trading hours for the Aussie like this:

import os
from oanda_candles import Pair, Gran, CandleCollector

token = os.getenv("OANDA_TOKEN")

collector = CandleCollector(token, Pair.AUD_USD, Gran.H1)
candles = collector.grab(100)

for candle in candles:
    print(candle.bid.o)

Note the CandleCollector remembers the candles it downloads and also keeps track of how fresh they are and has some heuristics about when it should download updates to them, such that you can spam run its grab(count) method in an event loop without worrying about spamming the Oanda API.

Summary of Basic Usage

1. A CandleCollector object is initialized with a token, forex pair, and granularity.
2. To get a list of the latest count Candle objects at any given time run the grab(count) method of collector.
3. The grab(count) method is safe to spam call in an event loop without slowing down to poll as the collector handles throttling and caching.
4. Each Candle has three Ohlc objects, one for Bid, Mid, and Ask prices, and a time attribute with the start of the candle time.
5. The Ohlc objects have open, high, low, and close Price objects

Understanding Request Ranges.

Note: This section is semi-deprecated by the CandleCollector which is new in 0.0.7, in the sense that in most use cases in a candle application it seems to me the CandleCollector is just a better way to go than the lower level CandleRequester.

The CandleRequester.request() has start, end, and count optional parameters used to specify how many candles and from when.

parameter	valid types	valid range	default
start	TimeInt, datetime, None	epoch to now	--
end	TimeInt, datetime, None	epoch to now	now
count	int, None	1 to 5000	500

It does not make sense to set all three of these parameters, but you can specify any single one of them, or any two of them, or none of them. The behavior for when they are set or unset is shown in this table:

start	end	count	behavior
--	--	--	Get latest 500 candles
--	--	set	Get latest count candles
--	set	--	Get last 500 candles up until the end time
--	set	set	Get last count candles up until the end time
set	--	--	Get the first 500 candles from start time
set	--	set	Get the first count candles from start time
set	set	--	Get candles from start to end times
set	set	set	ValueError (there might be a different count in the range)