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:

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