Liquidity

Liquidity data feed manipulation.

For more information about liquidity in automatic market making pools see AMM and XY liquidity model.

exception tradingstrategy.liquidity.LiquidityDataUnavailable

We tried to look up liquidity info for a trading pair, but count not find a sample.

class tradingstrategy.liquidity.XYLiquidity

Data structure that presents liquidity status in bonding curve pool.

This data structure is for naive x*y=k AMM pool. Liquidity is not the part of the normal technical analysis, so the dataset server has separate datasets for it.

Liquidity is expressed as US dollar value of the quote token of the pool. For example if the pool is 50 $FOO in reserve0 and 50 $USDC in reserve1, the liquidity of the pool would be expressed as 50 USD.

Liquidity events, like candles, have open, high, low and close values, depending on which time of the candle they were sampled.

pair_id: tradingstrategy.types.PrimaryKey

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

timestamp: tradingstrategy.types.UNIXTimestamp

Open timestamp for this time bucket.

exchange_rate: float

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

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: tradingstrategy.types.USDollarAmount

Liquidity absolute values in the pool in different time points. Note - for minute candles - if the candle contains only one event (mint, burn, sync) the open liquidity value is the value AFTER this event. The dataset server does not track the closing value of the previous liquidity event. This applies for minute candles only.

close: tradingstrategy.types.USDollarAmount

Liquidity absolute values in the pool in different time points

high: tradingstrategy.types.USDollarAmount

Liquidity absolute values in the pool in different time points

low: tradingstrategy.types.USDollarAmount

Liquidity absolute values in the pool in different time points

adds: int

Number of liquidity supplied events for pool

removes: int

Number of liquidity removed events for the pool

syncs: int

Number of total events affecting liquidity during the time window. This is adds, removes AND swaps AND sync().

add_volume: tradingstrategy.types.USDollarAmount

How much new liquidity was removed, in the terms of the quote token converted to US dollar

start_block: tradingstrategy.types.BlockNumber

Blockchain tracking information

end_block: tradingstrategy.types.BlockNumber

Blockchain tracking information

classmethod to_pyarrow_schema(small_candles=False) → pyarrow.lib.Schema

Construct schema for writing Parquet filess for these candles.

Parameters

small_candles – Use even smaller word sizes for frequent (1m) candles.

classmethod to_dataframe() → pandas.core.frame.DataFrame

Return emptry Pandas dataframe presenting liquidity sample.

__init__(pair_id: tradingstrategy.types.PrimaryKey, timestamp: tradingstrategy.types.UNIXTimestamp, exchange_rate: float, open: tradingstrategy.types.USDollarAmount, close: tradingstrategy.types.USDollarAmount, high: tradingstrategy.types.USDollarAmount, low: tradingstrategy.types.USDollarAmount, adds: int, removes: int, syncs: int, add_volume: tradingstrategy.types.USDollarAmount, start_block: tradingstrategy.types.BlockNumber, end_block: tradingstrategy.types.BlockNumber) → None

class tradingstrategy.liquidity.LiquidityResult

Server-reply for live queried liquidity data.

liquidity_events: List[tradingstrategy.liquidity.XYLiquidity]

A bunch of candles. Candles are unordered and subject to client side sorting. Multiple pairs and chains may be present in candles.

sort_by_timestamp()

In-place sorting of candles by their timestamp.

__init__(liquidity_events: List[tradingstrategy.liquidity.XYLiquidity]) → None

class tradingstrategy.liquidity.GroupedLiquidityUniverse

A universe where each trading pair has its own liquidity data feed.

This is helper class to create foundation for multi pair strategies.

For the data logistics purposes, all candles are lumped together in single columnar data blobs. However, it rarely makes sense to execute operations over different trading pairs. :py:class`GroupedLiquidityUniverse` creates trading pair id -> liquidity sample data grouping out from raw liquidity sample.

get_liquidity_samples_by_pair(pair_id: tradingstrategy.types.PrimaryKey) → Optional[pandas.core.frame.DataFrame]

Get samples for a single pair.

If the pair does not exist return None.

get_closest_liquidity(pair_id: tradingstrategy.types.PrimaryKey, when: pandas._libs.tslibs.timestamps.Timestamp, kind='open', look_back_time_frames=5) → tradingstrategy.types.USDollarAmount

Get the available liuqidity for a trading pair at a specific timepoint or some candles before the timepoint.

The liquidity is defined as one-sided as in XY liquidity model.

Parameters

• pair_id – Traing pair id

• when – Timestamp to query

• kind – One of liquidity samples: “open”, “close”, “low”, “high”

• look_back_timeframes – If there is no liquidity sample available at the exact timepoint, look to the past to the get the nearest sample

Returns

We always return

Raises

LiquidityDataUnavailable – There was no liquidity sample available

static create_empty() → tradingstrategy.liquidity.GroupedLiquidityUniverse

Create a liquidity universe without any data.