DEXPair#

API documentation for tradingstrategy.pair.DEXPair Python class in Trading Strategy framework.

class DEXPair[source]#

Bases: object

Trading pair information for a single pair.

Presents a single trading pair on decentralised exchanges.

DEX trading pairs can be uniquely identified by

  • Internal id.

  • (Chain id, address) tuple - the same address can exist on multiple chains.

  • (Chain slug, exchange slug, pair slug) tuple.

  • Token names and symbols are not unique - anyone can create any number of trading pair tickers and token symbols. Do not rely on token symbols for anything.

About data:

  • There is a different between token0 and token1 and base_token and quote_token conventions - the former are raw DEX (Uniswap) data while the latter are preprocessed by the server to make the data more understandable. Base token is the token you are trading and the quote token is the token you consider “money” for the trading. E.g. in WETH-USDC, USDC is the quote token. In SUSHI-WETH, WETH is the quote token.

  • Optional fields may be available if the candle server 1) detected the pair popular enough 2) managed to fetch the third party service information related to the token

When you download a trading pair dataset from the server, not all trading pairs are available. For more information about trading pair availability see trading pair tracking.

The class provides some JSON helpers to make it more usable with JSON based APIs.

This data class is serializable via dataclasses-json methods. Example:

info_as_string = pair.to_json()

You can also do __json__() convention data export:

info_as_dict = pair.__json__()

Note

Currently all flags are disabled and will be removed in the future. The historical dataset does not contain any filtering flags, because the data has to be filtered prior to download, to keep the download dump in a reasonasble size. The current data set of 800k trading pairs produce 100 MB dataset of which most of the pairs are useless. The server prefilters trading pairs and thus you cannot access historical data of pairs that have been prefiltered.

__init__(pair_id, chain_id, exchange_id, address, token0_address, token1_address, token0_symbol, token1_symbol, dex_type=None, base_token_symbol=None, quote_token_symbol=None, token0_decimals=None, token1_decimals=None, exchange_slug=None, exchange_address=None, pair_slug=None, first_swap_at_block_number=None, last_swap_at_block_number=None, first_swap_at=None, last_swap_at=None, flag_inactive=None, flag_blacklisted_manually=None, flag_unsupported_quote_token=None, flag_unknown_exchange=None, fee=None, buy_count_all_time=None, sell_count_all_time=None, buy_volume_all_time=None, sell_volume_all_time=None, buy_count_30d=None, sell_count_30d=None, buy_volume_30d=None, sell_volume_30d=None, buy_tax=None, transfer_tax=None, sell_tax=None, exchange_name=None)#
Parameters:
Return type:

None

Methods

__init__(pair_id, chain_id, exchange_id, ...)

convert_to_dataframe(pairs)

Convert Python DEXPair objects back to the Pandas dataframe presentation.

convert_to_pyarrow_table(pairs[, check_schema])

Convert a list of DEXPair instances to a Pyarrow table.

create_from_row(row)

Convert a DataFrame for to a DEXPair instance.

from_dict(kvs, *[, infer_missing])

from_json(s, *[, parse_float, parse_int, ...])

get_base_token()

Return token class presentation of base token in this trading pair.

get_friendly_name(exchange_universe)

Get a very human readable name for this trading pair.

get_link()

Get the trading pair link page on TradingStrategy.ai

get_quote_token()

Return token class presentation of quote token in this trading pair.

get_ticker()

Return trading 'ticker'

get_trading_pair_page_url()

Get information page for this trading pair.

is_tradeable([liquidity_threshold, ...])

Can this pair be traded.

schema(*[, infer_missing, only, exclude, ...])

to_dict([encode_json])

to_human_description()

Get human description for this pair.

to_json(*[, skipkeys, ensure_ascii, ...])

to_pyarrow_schema()

Construct schema for reading writing Parquet filss for pair information.

Attributes

pair_id

Internal primary key for any trading pair

chain_id

The chain id on which chain this pair is trading.

exchange_id

The exchange where this token trades

address

Smart contract address for the pair.

token0_address

Token pair contract address on-chain.

token1_address

Token pair contract address on-chain Lowercase, non-checksummed.

token0_symbol

Token0 as in raw Uniswap data.

token1_symbol

Token1 as in raw Uniswap data ERC-20 contracst are not guaranteed to have this data.

dex_type

What kind of exchange this pair is on

base_token_symbol

Naturalised base and quote token.

quote_token_symbol

Naturalised base and quote token.

token0_decimals

Number of decimals to convert between human amount and Ethereum fixed int raw amount.

token1_decimals

Number of decimals to convert between human amount and Ethereum fixed int raw amount Note - this information might be missing from ERC-20 smart contracts.

exchange_slug

Denormalised web page and API look up information

exchange_address

Exchange factory address.

pair_slug

Denormalised web page and API look up information

first_swap_at_block_number

Block number of the first Uniswap Swap event

last_swap_at_block_number

Block number of the last Uniswap Swap event

first_swap_at

Timestamp of the first Uniswap Swap event

last_swap_at

Timestamp of the first Uniswap Swap event

flag_inactive

Pair has been flagged inactive, because it has not traded at least once during the last 30 days.

flag_blacklisted_manually

Pair is blacklisted by operators.

flag_unsupported_quote_token

Quote token is one of USD, ETH, BTC, MATIC or similar popular token variants.

flag_unknown_exchange

Pair is listed on an exchange we do not if it is good or not TODO - inactive, remove.

fee

Swap fee in basis points if known

buy_count_all_time

Risk assessment summary data

sell_count_all_time

Risk assessment summary data

buy_volume_all_time

Risk assessment summary data

sell_volume_all_time

Risk assessment summary data

buy_count_30d

Risk assessment summary data

sell_count_30d

Risk assessment summary data

buy_volume_30d

Risk assessment summary data

sell_volume_30d

Risk assessment summary data

buy_tax

Buy token tax for this trading pair.

transfer_tax

Transfer token tax for this trading pair.

sell_tax

Sell tax for this trading pair.

exchange_name

Exchange name.

base_token_address

Get smart contract address for the base token.

base_token_decimals

Get token decimal count for the base token.

fee_tier

Return the trading pair fee as 0...1.

quote_token_address

Get smart contract address for the quote token

quote_token_decimals

Get token decimal count for the quote token

volume_30d

Denormalise trading volume last 30 days.

pair_id: int#

Internal primary key for any trading pair

chain_id: ChainId#

The chain id on which chain this pair is trading. 1 for Ethereum.

exchange_id: int#

The exchange where this token trades

address: str#

Smart contract address for the pair. In the case of Uniswap this is the pair (pool) address.

token0_address: str#

Token pair contract address on-chain. Lowercase, non-checksummed.

token1_address: str#

Token pair contract address on-chain Lowercase, non-checksummed.

token0_symbol: Optional[str]#

Token0 as in raw Uniswap data. ERC-20 contracst are not guaranteed to have this data.

token1_symbol: Optional[str]#

Token1 as in raw Uniswap data ERC-20 contracst are not guaranteed to have this data.

dex_type: Optional[ExchangeType]#

What kind of exchange this pair is on

base_token_symbol: Optional[str]#

Naturalised base and quote token. Uniswap may present the pair in USDC-WETH or WETH-USDC order based on the token address order. However we humans always want the quote token to be USD, or ETH or BTC. For the reverse token orders, the candle serve swaps the token order so that the quote token is the more natural token of the pair (in the above case USD)

quote_token_symbol: Optional[str]#

Naturalised base and quote token. Uniswap may present the pair in USDC-WETH or WETH-USDC order based on the token address order. However we humans always want the quote token to be USD, or ETH or BTC. For the reverse token orders, the candle serve swaps the token order so that the quote token is the more natural token of the pair (in the above case USD)

token0_decimals: Optional[int]#

Number of decimals to convert between human amount and Ethereum fixed int raw amount. Note - this information might be missing from ERC-20 smart contracts. If the information is missing the token is not tradeable in practice.

token1_decimals: Optional[int]#

Number of decimals to convert between human amount and Ethereum fixed int raw amount Note - this information might be missing from ERC-20 smart contracts. If the information is missing the token is not tradeable in practice.

exchange_slug: Optional[str]#

Denormalised web page and API look up information

exchange_address: Optional[str]#

Exchange factory address. Denormalised here, so we do not need an additional lookup.

pair_slug: Optional[str]#

Denormalised web page and API look up information

first_swap_at_block_number: Optional[int]#

Block number of the first Uniswap Swap event

last_swap_at_block_number: Optional[int]#

Block number of the last Uniswap Swap event

first_swap_at: Optional[int]#

Timestamp of the first Uniswap Swap event

last_swap_at: Optional[int]#

Timestamp of the first Uniswap Swap event

flag_inactive: Optional[bool]#

Pair has been flagged inactive, because it has not traded at least once during the last 30 days. TODO - inactive, remove.

flag_blacklisted_manually: Optional[bool]#

Pair is blacklisted by operators. Current there is no blacklist process so this is always false. TODO - inactive, remove.

flag_unsupported_quote_token: Optional[bool]#

Quote token is one of USD, ETH, BTC, MATIC or similar popular token variants. Because all candle data is outputted in the USD, if we have a quote token for which we do not have an USD conversation rate reference price source, we cannot create candles for the pair. TODO - inactive, remove.

flag_unknown_exchange: Optional[bool]#

Pair is listed on an exchange we do not if it is good or not TODO - inactive, remove.

fee: Optional[int]#

Swap fee in basis points if known

buy_count_all_time: Optional[int]#

Risk assessment summary data

sell_count_all_time: Optional[int]#

Risk assessment summary data

buy_volume_all_time: Optional[float]#

Risk assessment summary data

sell_volume_all_time: Optional[float]#

Risk assessment summary data

buy_count_30d: Optional[int]#

Risk assessment summary data

sell_count_30d: Optional[int]#

Risk assessment summary data

buy_volume_30d: Optional[float]#

Risk assessment summary data

sell_volume_30d: Optional[float]#

Risk assessment summary data

buy_tax: Optional[float]#

Buy token tax for this trading pair. See Token tax and deflationary tokens for details.

transfer_tax: Optional[float]#

Transfer token tax for this trading pair. See Token tax and deflationary tokens for details.

sell_tax: Optional[float]#

Sell tax for this trading pair. See Token tax and deflationary tokens for details.

exchange_name: Optional[str]#

Exchange name.

Not part of the datasets. Added during the instance construction.

property fee_tier: Optional[float]#

Return the trading pair fee as 0…1.

This is a synthetic properly based on fee data column.

Returns:

None if the fee information is not availble. (Should not happen on real data, but may happen in unit tests.)

property volume_30d: float#

Denormalise trading volume last 30 days.

  • Not an accurate figure, as this is based on rough 30 days batch job

  • Good enough for undertanding a trading pair is tradeable

property base_token_address: str#

Get smart contract address for the base token.

Returns:

Lowercase, non-checksummed.

property quote_token_address: str#

Get smart contract address for the quote token

Returns:

Token address in checksummed case

property base_token_decimals: Optional[int]#

Get token decimal count for the base token.

property quote_token_decimals: Optional[int]#

Get token decimal count for the quote token

is_tradeable(liquidity_threshold=None, volume_threshold_30d=100000.0)[source]#

Can this pair be traded.

Note

Liquidity threshold is TBD.

Parameters:
  • liquidity_threshold – How much the trading pair pool needs to have liquidity to be tradeable.

  • volume_threshold_30d

    How much montly volume the pair needs to have to be tradeable.

    Only used if liquidity data is missing.

Return type:

bool

get_ticker()[source]#

Return trading ‘ticker’

Return type:

str

get_friendly_name(exchange_universe)[source]#

Get a very human readable name for this trading pair.

We need to translate the exchange id to someething human readable, and for this we need to have the access to the exchange universe.

Parameters:

exchange_universe (ExchangeUniverse) –

Return type:

str

get_trading_pair_page_url()[source]#

Get information page for this trading pair.

Returns:

URL of the trading pair page or None if page/data not available.

Return type:

Optional[str]

classmethod to_pyarrow_schema()[source]#

Construct schema for reading writing Parquet filss for pair information.

Return type:

Schema

classmethod convert_to_pyarrow_table(pairs, check_schema=False)[source]#

Convert a list of DEXPair instances to a Pyarrow table.

Used to prepare a data export on a server.

Parameters:
  • pairs (List[DEXPair]) – The list wil be consumed in the process

  • check_schema – Run additional checks on the data. Slow. Use only in tests. May be give happier error messages instead of “OverflowError” what pyarrow spits out.

Return type:

Table

classmethod convert_to_dataframe(pairs)[source]#

Convert Python DEXPair objects back to the Pandas dataframe presentation.

As this is super-inefficient, do not use for large amount of data.

Parameters:

pairs (List[DEXPair]) –

Return type:

DataFrame

classmethod create_from_row(row)[source]#

Convert a DataFrame for to a DEXPair instance.

Allow using of helper methods on the pair data. It is recommend you avoid this if you do not need row-like data.

Parameters:

row (Series) –

Return type:

DEXPair

to_human_description()[source]#

Get human description for this pair.

Return type:

Union[Tuple[ChainId, str | None, str, str, float], Tuple[ChainId, str | None, str, str]]

get_base_token()[source]#

Return token class presentation of base token in this trading pair.

Return type:

Token

get_quote_token()[source]#

Return token class presentation of quote token in this trading pair.

Return type:

Token

Get the trading pair link page on TradingStrategy.ai

Return type:

str

__init__(pair_id, chain_id, exchange_id, address, token0_address, token1_address, token0_symbol, token1_symbol, dex_type=None, base_token_symbol=None, quote_token_symbol=None, token0_decimals=None, token1_decimals=None, exchange_slug=None, exchange_address=None, pair_slug=None, first_swap_at_block_number=None, last_swap_at_block_number=None, first_swap_at=None, last_swap_at=None, flag_inactive=None, flag_blacklisted_manually=None, flag_unsupported_quote_token=None, flag_unknown_exchange=None, fee=None, buy_count_all_time=None, sell_count_all_time=None, buy_volume_all_time=None, sell_volume_all_time=None, buy_count_30d=None, sell_count_30d=None, buy_volume_30d=None, sell_volume_30d=None, buy_tax=None, transfer_tax=None, sell_tax=None, exchange_name=None)#
Parameters:
Return type:

None