Candle#

tradingstrategy.candle.Candle class.

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
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: PrimaryKey#

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

timestamp: UNIXTimestamp#

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: USDollarAmount#

OHLC core data

close: USDollarAmount#

OHLC core data

high: USDollarAmount#

OHLC core data

low: USDollarAmount#

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: USDollarAmount#

Volume data

sell_volume: USDollarAmount#

Volume data

avg: USDollarAmount#

Average trade size

start_block: BlockNumber#

The first blockchain block that includes trades that went into this candle.

end_block: BlockNumber#

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: USDollarAmount#

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
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
Return type

None