Oanda forex candle API built on top of oandapyV20
Project description
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.10:
- Updated time-int dependency from 0.0.6 to 0.0.7.
new in version 0.0.9:
- CandleMeister and CandleClient now have a method to get the collector they use for a specific pair and granularity.
- Updated some dependencies to latest versions.
new in version 0.0.8:
- Added CandleClient to manage multiple CandleCollector objects from one object.
- Plus a CandleMeister that wraps a single CandleClient for easy global access
- Fixed a bug that was causing too many requests when they were not needed.
- Had idea for
tail
method as a variant ongrab
method, where it returns only the newest candle information since the last call to eitehrgrab
ortail
. Made a place holder for it, but not implementing it yet. - 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:
- The
CandleSequence
has been cleaned up and plans to add merging have been abandoned. - 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. - A new
CandleCollector
class is added which is like a higher levelCandleSequence
specifically designed for chart applications that always want a specific number of latest candles. - 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
- A
CandleCollector
object is initialized with a token, forex pair, and granularity. - To get a list of the latest
count
Candle
objects at any given time run thegrab(count)
method of collector. - 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. - Each
Candle
has threeOhlc
objects, one for Bid, Mid, and Ask prices, and atime
attribute with the start of the candle time. - The
Ohlc
objects have open, high, low, and closePrice
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) |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for oanda_candles-0.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c37dd6389da4f73b41ac8752dbc190801f2ce216112778b93a2a72e359792010 |
|
MD5 | 0b86be379ed6e69504300acc81e5edd9 |
|
BLAKE2b-256 | 67222928a03b27c0793d0a6def48b03fbc1be87a46c9ccdf200cd4bd2ecf721f |