Candle#

tradingstrategy.candle.Candle Python class in Trading Strategy framework.

class Candle[source]#

Bases: object

Data structure presenting one OHLCV trading candle.

Based on the open-high-low-close-volume concept.

Trading Strategy candles come with additional information available on the top of core OHLCV, as chain analysis has deeper visibility than one would get on traditional exchanges. For example for enhanced attributes see Candle.buys (buy count) or Candle.start_block (blockchain starting block number of the candle).

We also separate “buys” and “sells”. Although this separation might not be meaningful on order-book based exchanges, we define “buy” as a DEX swap where quote token (USD, ETH) was swapped into more exotic token (AAVE, SUSHI, etc.)

__init__(pair_id, timestamp, exchange_rate, open, close, high, low, buys, sells, buy_volume, sell_volume, avg, start_block, end_block)#

Parameters:

pair_id (int) –
timestamp (int) –
exchange_rate (float) –
open (float) –
close (float) –
high (float) –
low (float) –
buys (int) –
sells (int) –
buy_volume (float) –
sell_volume (float) –
avg (float) –
start_block (int) –
end_block (int) –

Return type:

None

Methods

`__init__`(pair_id, timestamp, exchange_rate, ...)
`from_dict`(kvs, *[, infer_missing])
`from_json`(s, *[, parse_float, parse_int, ...])
`generate_synthetic_sample`(pair_id, ...)	Generate a candle dataframe.
`schema`(*[, infer_missing, only, exclude, ...])
`to_dataframe`()	Return emptry Pandas dataframe presenting candle data.
`to_dict`([encode_json])
`to_json`(*[, skipkeys, ensure_ascii, ...])
`to_pyarrow_schema`([small_candles])	Construct schema for writing Parquet filess for these candles.
`to_qstrader_dataframe`()	Return emptry Pandas dataframe presenting candle data for QStrader.

Attributes

`DATAFRAME_FIELDS`	Schema definition for :py:class:`pd.DataFrame:
`trades`	Amount of all trades during the candle period.
`volume`	Total volume during the candle period.
`pair_id`	Primary key to identity the trading pair Use pair universe to map this to chain id and a smart contract address
`timestamp`	Open timestamp for this candle.
`exchange_rate`	USD exchange rate of the quote token used to convert to dollar amounts in this candle.
`open`	OHLC core data
`close`	OHLC core data
`high`	OHLC core data
`low`	OHLC core data
`buys`	Number of buys happened during the candle period
`sells`	Number of sells happened during the candle period
`buy_volume`	Volume data
`sell_volume`	Volume data
`avg`	Average trade size
`start_block`	The first blockchain block that includes trades that went into this candle.
`end_block`	The last blockchain block that includes trades that went into this candle.

pair_id: int#: Primary key to identity the trading pair Use pair universe to map this to chain id and a smart contract address

timestamp: int#: Open timestamp for this candle. Note that the close timestamp you need to supply yourself based on the context.

exchange_rate: float#

USD exchange rate of the quote token used to convert to dollar amounts in this candle.

Note that currently any USD stablecoin (USDC, DAI) is assumed to be 1:1 and the candle server cannot handle exchange rate difference among stablecoins.

The rate is taken at the beginning of the 1 minute time bucket. For other time buckets, the exchange rate is the simple average for the duration of the bucket.

open: float#: OHLC core data

close: float#: OHLC core data

high: float#: OHLC core data

low: float#: OHLC core data

buys: int#: Number of buys happened during the candle period

sells: int#: Number of sells happened during the candle period

buy_volume: float#: Volume data

sell_volume: float#: Volume data

avg: float#: Average trade size

start_block: int#: The first blockchain block that includes trades that went into this candle.

end_block: int#: The last blockchain block that includes trades that went into this candle.

DATAFRAME_FIELDS = {'avg': 'float', 'buy_volume': 'float', 'buys': 'float', 'close': 'float', 'end_block': 'int', 'exchange_rate': 'float', 'high': 'float', 'low': 'float', 'open': 'float', 'pair_id': 'int', 'sell_volume': 'float', 'sells': 'float', 'start_block': 'int', 'timestamp': 'datetime64[s]'}#

Schema definition for :py:class:`pd.DataFrame:

Defines Pandas datatypes for columns in our candle data format. Useful e.g. when we are manipulating JSON/hand-written data.

property trades: int#: Amount of all trades during the candle period.

property volume: float#

Total volume during the candle period.

Unline in traditional CEX trading, we can separate buy volume and sell volume from each other, becauase liquidity provider is a special role.

classmethod to_dataframe()[source]#

Return emptry Pandas dataframe presenting candle data.

Return type:: DataFrame

classmethod to_qstrader_dataframe()[source]#

Return emptry Pandas dataframe presenting candle data for QStrader.

TODO: Fix QSTrader to use “standard” column names.

Return type:: DataFrame

classmethod to_pyarrow_schema(small_candles=False)[source]#

Construct schema for writing Parquet filess for these candles.

Parameters:: small_candles – Use even smaller word sizes for frequent (1m) candles.
Return type:: Schema

static generate_synthetic_sample(pair_id, timestamp, price)[source]#

Generate a candle dataframe.

Used in testing when manually fiddled data is needed.

All open/close/high/low set to the same price. Exchange rate is 1.0. Other data set to zero.

Returns:

One dict of filled candle data

Parameters:

pair_id (int) –
timestamp (Timestamp) –
price (float) –

Return type:

dict

__init__(pair_id, timestamp, exchange_rate, open, close, high, low, buys, sells, buy_volume, sell_volume, avg, start_block, end_block)#

Parameters:

pair_id (int) –
timestamp (int) –
exchange_rate (float) –
open (float) –
close (float) –
high (float) –
low (float) –
buys (int) –
sells (int) –
buy_volume (float) –
sell_volume (float) –
avg (float) –
start_block (int) –
end_block (int) –

Return type:

None