PandasPairUniverse#

tradingstrategy.pair.PandasPairUniverse Python class in Trading Strategy framework.

class PandasPairUniverse[source]#

Bases: object

A pair universe implementation that is created from Pandas dataset.

This is a helper class, as pandas.DataFrame is somewhat more difficult to interact with. This class will read the raw data frame and convert it to DEXPair objects with a lookup index. Because the DEXPair conversion is expensive for 10,000s of Python objects, it is recommended that you filter the raw pandas.DataFrame by using filtering functions in tradingstrategy.pair first, before initializing PandasPairUniverse.

About the usage:

Single trading pairs can be looked up using PandasPairUniverse.get_pair_by_smart_contract() and PandasPairUniverse.get_pair_by_id()
Multiple pairs can be looked up by directly reading PandasPairUniverse.df Pandas dataframe

Example how to use:

# Get dataset from the server as Apache Pyarrow table
columnar_pair_table = client.fetch_pair_universe()

# Convert Pyarrow -> Pandas -> in-memory DEXPair index
pair_universe = PandasPairUniverse(columnar_pair_table.to_pandas())

# Lookup SUSHI-WETH trading pair from DEXPair index
# https://tradingstrategy.ai/trading-view/ethereum/sushi/sushi-eth
pair: DEXPair = pair_universe.get_pair_by_smart_contract("0x795065dcc9f64b5614c407a6efdc400da6221fb0")

If the pair index is too slow to build, or you want to keep it lean, you can disable the indexing with build_index. In this case, some of the methods won’t work:

# Get dataset from the server as Apache Pyarrow table
columnar_pair_table = client.fetch_pair_universe()

# Convert Pyarrow -> Pandas -> in-memory DEXPair index
pair_universe = PandasPairUniverse(columnar_pair_table.to_pandas(), build_index=False)

__init__(df, build_index=True, exchange_universe=None)[source]#

Parameters:

df (DataFrame) – The source DataFrame that contains all DEXPair entries
build_index – Build quick lookup index for pairs
exchange_universe (Optional[ExchangeUniverse]) –
Optional exchange universe needed for human-readable pair lookup.

We cannot properly resolve pairs unless we can map exchange names to their ids. Currently optional, only needed by get_pair().

Methods

`__init__`(df[, build_index, exchange_universe])	param df:
`build_index`()	Create pair_id -> data mapping.
`create_limited_pair_universe`(df, exchange, pairs)	Create a trading pair universe that contains only few trading pairs.
`create_parquet_load_filter`([count_limit])	Returns a Parquet loading filter that contains pairs in this universe.
`create_single_pair_universe`(df, exchange, ...)	Create a trading pair universe that contains only a single trading pair.
`get_all_pair_ids`()	Get all pair ids in the data frame.
`get_all_tokens`()	Get all base and quote tokens in trading pairs.
`get_by_symbols`(base_token_symbol, ...)	For strategies that trade only a few trading pairs, get the only pair in the universe.
`get_count`()	How many trading pairs there are.
`get_one_pair_from_pandas_universe`(...[, ...])	Get a trading pair by its ticker symbols.
`get_pair`(chain_id, exchange_slug, ...[, ...])	Get a pair by its description.
`get_pair_by_human_description`(...)	Get pair by its human readable description.
`get_pair_by_id`(pair_id)	Look up pair information and return its data.
`get_pair_by_smart_contract`(address)	Resolve a trading pair by its pool smart contract address.
`get_pair_ids_by_exchange`(exchange_id)	Get all pair ids on a specific exchange.
`get_single`()	For strategies that trade only a single trading pair, get the only pair in the universe.
`get_token`(address)	Get a token that is part of any trade pair.
`iterate_pairs`()	Iterate over all pairs in this universe.

Attributes

`pair_map`	pair_id -> raw dict data mappings
`dex_pair_obj_cache`	pair_id -> constructed DEXPair cache

__init__(df, build_index=True, exchange_universe=None)[source]#

Parameters:

df (DataFrame) – The source DataFrame that contains all DEXPair entries
build_index – Build quick lookup index for pairs
exchange_universe (Optional[ExchangeUniverse]) –
Optional exchange universe needed for human-readable pair lookup.

We cannot properly resolve pairs unless we can map exchange names to their ids. Currently optional, only needed by get_pair().

pair_map: Dict[int, dict]#

pair_id -> raw dict data mappings

Constructed in one pass from Pandas DataFrame.

Don’t access directly, use iterate_pairs().

dex_pair_obj_cache: Dict[int, DEXPair]#

pair_id -> constructed DEXPair cache

Don’t access directly, use iterate_pairs().

iterate_pairs()[source]#

Iterate over all pairs in this universe.

Return type:: Iterable[DEXPair]

build_index()[source]#

Create pair_id -> data mapping.

Allows fast lookup of individual pairs.

Warning

This function assumes the universe contains data for only one blockchain. The same address can exist across multiple EVM chains. The created smart contract address index does not index chain id and thus is invalid.

get_all_pair_ids()[source]#

Get all pair ids in the data frame.

Return type:: Collection[int]

get_pair_ids_by_exchange(exchange_id)[source]#

Get all pair ids on a specific exchange.

Returns:: Raw slide of DataFrame
Parameters:: exchange_id (int) –
Return type:: DataFrame

get_count()[source]#

How many trading pairs there are.

Return type:: int

get_pair_by_id(pair_id)[source]#

Look up pair information and return its data.

Uses a cached path. Constructing DEXPair objects is a bit slow, so this is a preferred method if you need to access multiple pairs in a hot loop.

Returns:

Nicely presented DEXPair.

If we do not have an entry for pair_id, return None.

Parameters:

pair_id (int) –

Return type:

Optional[DEXPair]

get_pair_by_smart_contract(address)[source]#

Resolve a trading pair by its pool smart contract address.

Warning

This function assumes the universe contains data for only one blockchain. The same address can exist across multiple EVM chains.

Parameters:: address (str) – Ethereum smart contract address of the Uniswap pair contract
Return type:: Optional[DEXPair]

get_token(address)[source]#

Get a token that is part of any trade pair.

Get a token details for a token that is base or quotetoken of any trading pair.

..note

TODO: Not a final implementation subject to chage.

Returns:: Tuple (name, symbol, address, decimals) or None if not found.
Parameters:: address (str) –
Return type:: Optional[Token]

get_all_tokens()[source]#

Get all base and quote tokens in trading pairs.

Warning

This method is useful for only test/limited pair count universes. It is very slow and mainly purported for debugging and diagnostics.

Return type:: Set[Token]

get_single()[source]#

For strategies that trade only a single trading pair, get the only pair in the universe.

Raises:: AssertionError – If our pair universe does not have an exact single pair
Return type:: DEXPair

get_by_symbols(base_token_symbol, quote_token_symbol)[source]#

For strategies that trade only a few trading pairs, get the only pair in the universe.

Warning

Currently, this method is only safe for prefiltered universe. There are no safety checks if the returned trading pair is legit. In the case of multiple matching pairs, a random pair is returned.g

Parameters:

base_token_symbol (str) –
quote_token_symbol (str) –

Return type:

Optional[DEXPair]

get_one_pair_from_pandas_universe(exchange_id, base_token, quote_token, pick_by_highest_vol=False)[source]#

Get a trading pair by its ticker symbols.

Note that this method works only very simple universes, as any given pair is poised to have multiple tokens and multiple trading pairs on different exchanges.

Example:

# Get PancakeSwap exchange,
# for the full exchange list see https://tradingstrategy.ai/trading-view/exchanges
pancake = exchange_universe.get_by_chain_and_slug(ChainId.bsc, "pancakeswap-v2")

# Because there can be multiple trading pairs with same tickers,
# we pick the genuine among the scams based on its trading volume
wbnb_busd_pair = pair_universe.get_one_pair_from_pandas_universe(
    pancake.exchange_id,
    "WBNB",
    "BUSD",
    pick_by_highest_vol=True,
    )

print("WBNB address is", wbnb_busd_pair.base_token_address)
print("BUSD address is", wbnb_busd_pair.quote_token_address)
print("WBNB-BUSD pair contract address is", wbnb_busd_pair.address)

Parameters:

pick_by_highest_vol – If multiple trading pairs with the same symbols are found, pick one with the highest volume. This is because often malicious trading pairs are create to attract novice users.
exchange_id (int) –
base_token (str) –
quote_token (str) –

Raises:

DuplicatePair – If the universe contains more than single entry for the pair.

Returns:

None if there is no match

Return type:

Optional[DEXPair]

get_pair(chain_id, exchange_slug, base_token, quote_token, fee_tier=None)[source]#

Get a pair by its description.

The simplest way to access pairs in the pair universe.

To use this method, we must include exchange_universe in the __init__() as otherwise we do not have required look up tables.

Returns:

The trading pair on the exchange.

Highest volume trading pair if multiple matches.

Raises:

NoPairFound – In the case input data cannot be resolved.

Parameters:

chain_id (ChainId) –
exchange_slug (str) –
base_token (str) –
quote_token (str) –
fee_tier (Optional[float]) –

Return type:

DEXPair

get_pair_by_human_description(exchange_universe, desc)[source]#

Get pair by its human readable description.

Look up a trading pair by chain, exchange, base, quote token tuple.

See HumanReadableTradingPairDescription for more information.

Example:

# Get BNB-BUSD pair on PancakeSwap v2
desc = (ChainId.bsc, "pancakeswap-v2", "WBNB", "BUSD")
bnb_busd = pair_universe.get_pair_by_human_description(exchange_universe, desc)
assert bnb_busd.base_token_symbol == "WBNB"
assert bnb_busd.quote_token_symbol == "BUSD"
assert bnb_busd.buy_volume_30d > 1_000_000

Parameters:

exchange_universe (ExchangeUniverse) – The current database used to decode exchanges.
desc (Union[Tuple[ChainId, str, str, str, float], Tuple[ChainId, str, str, str]]) –

Returns:

The trading pair on the exchange.

Highest volume trading pair if multiple matches.

Raises:

NoPairFound – In the case input data cannot be resolved.

Return type:

DEXPair

create_parquet_load_filter(count_limit=10000)[source]#

Returns a Parquet loading filter that contains pairs in this universe.

When candle or liquidity file is read to the memory, only read pairs that are within this pair universe. This severely reduces the memory usage and speed ups loading.

See tradingstrategy.reader.read_parquet().

Parameters:: count_limit – Sanity check assert limit how many pairs we can cram into the filter.
Returns:: Filter to be passed to read_table
Return type:: List[Tuple]

static create_single_pair_universe(df, exchange, base_token_symbol, quote_token_symbol, pick_by_highest_vol=True)[source]#

Create a trading pair universe that contains only a single trading pair.

This is useful for trading strategies that to technical analysis trading on a single trading pair like BTC-USD.

Parameters:

df (DataFrame) – Unfiltered DataFrame for all pairs
exchange (Exchange) – Exchange instance on the pair is trading
base_token_symbol (str) – Base token symbol of the trading pair
quote_token_symbol (str) – Quote token symbol of the trading pair
pick_by_highest_vol – In the case of multiple match per token symbol, or scam tokens, pick one with the highest trade volume

Raises:

DuplicatePair – Multiple pairs matching the criteria
NoPairFound – No pairs matching the criteria

Return type:

PandasPairUniverse

static create_limited_pair_universe(df, exchange, pairs, pick_by_highest_vol=True)[source]#

Create a trading pair universe that contains only few trading pairs.

This is useful for trading strategies that to technical analysis trading on a few trading pairs, or single pair three-way trades like Cake-WBNB-BUSD.

Parameters:

df (DataFrame) – Unfiltered DataFrame for all pairs
exchange (Exchange) – Exchange instance on the pair is trading
pairs (List[Tuple[str, str]]) – List of trading pairs as ticket tuples. E.g. [ (“WBNB, “BUSD”), (“Cake”, “WBNB”) ]
pick_by_highest_vol – In the case of multiple match per token symbol, or scam tokens, pick one with the highest trade volume

Raises:

DuplicatePair – Multiple pairs matching the criteria
NoPairFound – No pairs matching the criteria

Return type:

PandasPairUniverse