oanda-candles 0.1.0

Oanda forex candle API built on top of oandapyV20

oanda-candles

Client to make getting Oanda candle data easy.

Quick Example

import os
from oanda_candles import CandleClient, Pair, Gran

token = os.getenv("OANDA_TOKEN")

# Initialize Client with token, real as False for practice account.
client = CandleClient(token, real=False)

# Initialize collector for Euro/US Dollar 4 hour candles.
collector = client.get_collector(Pair.EUR_USD, Gran.H4)

# Print the opening and closing bid price of the most recent 100 candles.
candles = collector.grab(100)
for candle in candles:
    print(f"{candle.time.get_pretty()}: Open bid: {candle.bid.o} Close bid: {candle.bid.c}")

# Get list of 300 candles from 8000 candles back
special_300 = collector.grab_offset(8000, 300)

Public Classes in this Package

Class	Description
Candle	Data about one candle containing a start time and three Ohlc objects for the bid, mid, and ask prices
CandleClient	Collection of one CandleCollector for each combination of pair and gran
CandleCollector	For grabbing candles for a specific pair and gran
CandleMeister	Provides a single CandleCollector so one does not have to pass it around between modules
Gran	Candle granularity (duration), one of the spefic values allowed by Oanda's API such as Gran.H6 for six hour
Ohlc	Contains open, high, low, and closing prices as attrs o, h, l, and c
Pair	One of 28 forex currency pairs. Can be specified like Pair.EUR_USD or Pair("eurusd")
TimeInt	Integer subclass representing time since Jan 1, 1970 in UTC, candles have this as their time attribute

Some Features

1. Candle data is cached automatically so calling grab or grab_offset for same candles do not require another server requests.
2. However, when candles are grabbed, the cache is updated to include the most recent candles provided at least three seconds have passed since the last time they were updated.
3. The Candle objects returned have the bid, mid, and ask prices and have times expressed as UTC epoch integers.
4. Candles are aligned to reasonable offset defaults (month candles start at start of month in UTC).
5. Candle alignment is preset to always start days and month candles on the start of the day and month UTC.

Some Limitations.

1. Requires secret Oanda Access token to initialize client.
2. Only candle granularity levels supported by Oanda's V20 RestfulAPI are available.
3. Only forex pairs (instruments) supported by the forex-types package are supported (The 28 pair combinations for the 8 major currencies).
4. Not all the options of Oanda's V20 candle endpoint are available. Rather reasonable values are already preset. (considering the very odd defaults and the confusing way the options work, this is kind of a feature type limitation, still in a future version these likely should be made configurable for any masachists that want to mess with them).

Steps followed by grab and grab_offset methods

When either the grab or grab_offset methods are called on a particular CandleCollector object, it:

1. Makes sure candle cache is up to date with latest candles by querying Oanda if its been longer than 3 seconds since this was last done.
2. If the candles in the cache do not go back far enough to provide the number requested get older candles from Oanda until it does.
3. Return the requested candles, while keeping the cached list for the next grab calls.

CAVEAT:

This is still a beta type package--although between 0.0.10 and 0.1.0 it became somewhat less beta-ish.

Version history.

new in version 0.1.0:

1. Reliance on opandaV20 package was dropped in favor of using requests package directly.
2. Everything was refactored into smaller simpler less "exploratory" code.
3. Updating TimeInt package to 0.0.9 which is entirely UTC, without any accidental local times popping in.
4. Month candles are aligned right at start of month UTC. And day candles at start of day and so forth.
5. CandleSequence class which had no real utility compared to highe level grab classes were refactored out.
6. Only tested refactoring by hand, unittests have to be rewritten (since they were full of funky time alignment that we no longer have.)

new in version 0.0.10:

1. Updated time-int dependency from 0.0.6 to 0.0.7.

new in version 0.0.9:

1. CandleMeister and CandleClient now have a method to get the collector they use for a specific pair and granularity.
2. Updated some dependencies to latest versions.

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.

About Oanda Access Tokens

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.