oanda-candles 0.0.8

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.8:

1. Added CandleClient to manage multiple CandleCollector objects from one object.
2. Plus a CandleMeister that wraps a single CandleClient for easy global access
3. Fixed a bug that was causing too many requests when they were not needed.
4. Had idea for tail method as a variant on grab method, where it returns only the newest candle information since the last call to eitehr grab or tail. Made a place holder for it, but not implementing it yet.
5. Still behind on unit tests, but still was able to do sand-box testing with market open. --which is how I found and fixed bug above. This package is still far from prime time ready.

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.

Using CandleMeister

The CandleMeister is a single globally available class that manages one CandleCollector for each pair/granularity combination. While the CandleClient is the same idea but as an object where you can have more than one...in those cases where you may want more than one...which I can't think of.

To use the CandleMeister to grab any candles, you must make sure it that it is initialized with the Oanda token. For example if the env var OANDA_TOKEN has your token do the following right at the startup of your application before you create your widgets:

import os
from oanda_candles import CandleMeister

token = os.getenv("OANDA_TOKEN")
CandleMeister.init_meister(token)

Then you can you can grab candles from any module you like (provided you don't do it at import time) like so:

from oanda_candles import CandleMeister, Pair, Gran

...
def some_func(*args, **kwargs):
    ...
    euro_weekly_candles = CandleMeister.grab(Pair.EUR_USD, Gran.W, 100)
    ...

Note that if the CandleMeister.grab method was used outside of the function in this example, then it would probably end up called as your modules were imported before your were able to initialize the CandleMeister with the token. It is thus recommended you keep such calls inside callback methods and not try to make them at import time.

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)