PandasPairUniverse#

tradingstrategy.pair.PandasPairUniverse class.

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)[source]#

Parameters

df (DataFrame) – The source DataFrame that contains all DEXPair entries
build_index – Build quick lookup index for pairs

Methods

`__init__`(df[, build_index])	param df The source DataFrame that contains all DEXPair entries
`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_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_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_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 -> DEXPair mappings Don't access directly, use iterate_pairs().

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

Parameters

df (DataFrame) – The source DataFrame that contains all DEXPair entries
build_index – Build quick lookup index for pairs

pair_map: Dict[int, dict]#: pair_id -> DEXPair mappings 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_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.

Returns: Nicely presented DEXPair.
Parameters: pair_id (PrimaryKey) –
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 (PrimaryKey) –
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]

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