TradingPairIdentifier#

API documentation for tradeexecutor.state.identifier.TradingPairIdentifier Python class in Trading Strategy framework.

class TradingPairIdentifier[source]#

Bases: object

Uniquely identify one trading pair across all tradeable blockchain assets.

This is pass-by-copy (as opposite to pass-by-reference) trading pair identifier we use across the persistent state. Because we copy a lot of information about asset, not just its id, this makes data reads and diagnosing problems simpler.

  • Tokens are converted from machine readable token0 - token1 pair to more human-friendly base and quote token pair. See conversion.

  • This class is a data class that is a copy-by-value in the persistent state: We copy both machine-readable information (smart contract addresses) and human readable information (symbols), as both are important to store for the persistent use - we do not expect to be able to lookup the information again with smart contract addresses in the future, as API access is expensive and blockchains may permanently be abandon.

  • This class is preferred to be used as immutable, but sometimes it is handy to manually override :py:attr`fee` for different backtesting scenarios

  • This identifier is also used for lending protocols. In this case base is aToken like aUSDC. and quote is USDC.

__init__(base, quote, pool_address, exchange_address, internal_id=None, internal_exchange_id=None, info_url=None, fee=None, reverse_token_order=None, kind=TradingPairKind.spot_market_hold, underlying_spot_pair=None, exchange_name=None, other_data=<factory>)#
Parameters:
Return type:

None

Methods

__init__(base, quote, pool_address, ...[, ...])

from_dict(kvs, *[, infer_missing])

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

get_collateral_factor()

Same as liquidation threshold.

get_human_description([describe_type])

Get short ticker human description for this pair.

get_identifier()

We use the smart contract pool address to uniquely identify trading positions.

get_lending_protocol()

Is this pair on a particular lending protocol.

get_liquidation_threshold()

What's the liqudation threshold for this leveraged pair

get_max_leverage_at_open([side])

Return the max leverage we can set for this position at open.

get_pricing_pair()

Get the the trading pair that determines the price for the asset.

get_tags()

Get tags asssociated with the base asset of this trading pair.

get_ticker()

Return base token symbol - quote token symbol human readable ticket.

has_complete_info()

Check if the pair has good information.

has_reverse_token_order()

Has Uniswap smart contract a flipped token order.

is_credit_supply()

is_leverage()

is_long()

Leveraged long, not spot.

is_short()

Leveraged short.

is_spot()

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

to_dict([encode_json])

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

Attributes

base

Base token in this trading pair

quote

Quote token in this trading pair

pool_address

Smart contract address of the pool contract.

exchange_address

Exchange address.

internal_id

How this asset is referred in the internal database

internal_exchange_id

What is the internal exchange id of this trading pair.

info_url

Info page URL for this trading pair e.g.

fee

Trading fee for this pair.

reverse_token_order

The underlying token0/token1 for Uniswap pair is flipped compared to base token/quote token.

kind

What kind of position this is

underlying_spot_pair

Underlying spot trading pair

exchange_name

Exchange name where this pair trades on.

other_data

User storeable properties.

chain_id

Return raw chain id.

base: AssetIdentifier#

Base token in this trading pair

E.g. WETH.

In leveraged positions this is borrowed asset with AssetIdentifier.underlying set.

quote: AssetIdentifier#

Quote token in this trading pair

E.g. USDC

In leveraged positions and credit supply positions, this is borrowed asset with AssetIdentifier.underlying set.

pool_address: str#

Smart contract address of the pool contract.

  • Uniswap v2 pair contract address

  • Uniswap v3 pool contract address

Set to asset address for Aave pools.

exchange_address: str#

Exchange address. Identifies a decentralised exchange. Uniswap v2 likes are identified by their factor address.

internal_id: Optional[int]#

How this asset is referred in the internal database

Internal ids are not stable over the long duration. Internal ids are not also stable across different oracles. Always use (chain_id, pool_address) pair for persistent lookups.

For synthetic pairs, like leveraged pairs on lending protocols, the internal id is the same as the underlying spot pair id. TODO: Confirm this, or missing?

internal_exchange_id: Optional[int]#

What is the internal exchange id of this trading pair.

info_url: Optional[str]#

Info page URL for this trading pair e.g. with the price charts

fee: Optional[float]#

Trading fee for this pair.

Liquidity provider fee expressed as the percent of the trade.

E.g. 0.0030 for 0.30% fee.

Should be filled for all Uniswap v2 and Uniswap v3 pairs. If the smaller Uni v2 forks do not have good data, 0.0030% is assumed.

reverse_token_order: Optional[bool]#

The underlying token0/token1 for Uniswap pair is flipped compared to base token/quote token.

Use has_reverse_token_order() to access - might not be set. This is set when TradingPairIdentifier is constructed.

kind: TradingPairKind#

What kind of position this is

underlying_spot_pair: Optional[TradingPairIdentifier]#

Underlying spot trading pair

This is used e.g. by alpha models to track the underlying pairs when doing leveraged positions.

exchange_name: Optional[str]#

Exchange name where this pair trades on.

May or may not be filled.

other_data: Optional[dict]#

User storeable properties.

You can add any of your own metadata on the assets here.

Be wary of the life cycle of the instances. The life time of the class instances tied to the trading universe that is recreated for every strategy cycle.

property chain_id: int#

Return raw chain id.

Get one from the base token, beacuse both tokens are on the same chain.

See also tradingstrategy.chain.ChainId

get_identifier()[source]#

We use the smart contract pool address to uniquely identify trading positions.

Ethereum address is lowercased, not checksummed.

Return type:

str

get_ticker()[source]#

Return base token symbol - quote token symbol human readable ticket.

Example: WETH-USDC, ``

See also get_human_description().

Return type:

str

get_lending_protocol()[source]#

Is this pair on a particular lending protocol.

Return type:

tradingstrategy.lending.LendingProtocolType | None

get_human_description(describe_type=False)[source]#

Get short ticker human description for this pair.

Parameters:

describe_type – Handle spot, short and such pairs.

Return type:

str

See get_ticker().

has_complete_info()[source]#

Check if the pair has good information.

Because of the open-ended nature a lot of irrelevant broken data can be found on blockchains.

Both base and quote token must have

  • Symbol

  • Decimals

This check is mainly useful to filter out crap tokens from the trading decisions.

Return type:

bool

has_reverse_token_order()[source]#

Has Uniswap smart contract a flipped token order.

  • Is token0 base token or token0 is the quote token

See eth_defi.uniswap_v3.price.get_onchain_price()

Return type:

bool

get_max_leverage_at_open(side='short')[source]#

Return the max leverage we can set for this position at open.

E.g. for AAVE WETH short this is 0.8 because we can supply 1000 USDC to get 800 USDC loan. This gives us the health factor of 1.13 on open.

Max Leverage in pair: l=1/(1-cfBuy); cfBuy = collateralFacor of Buy Asset

Parameters:

side (Literal['long', 'short']) – Order side: long or short

Return type:

float

is_short()[source]#

Leveraged short.

Return type:

bool

is_long()[source]#

Leveraged long, not spot.

Return type:

bool

get_liquidation_threshold()[source]#

What’s the liqudation threshold for this leveraged pair

Return type:

float

get_collateral_factor()[source]#

Same as liquidation threshold.

Alias for get_liquidation_threshold()

Return type:

float

get_pricing_pair()[source]#

Get the the trading pair that determines the price for the asset.

  • For spot pairs this is the trading pair itself

  • For pairs that may lack price feed data like USDC/USD pairs used in credit supply, return None

Returns:

The trading pair we can use to query underlying asset price.

Return None if the trading pair does not have price information.

Return type:

Optional[TradingPairIdentifier]

get_tags()[source]#

Get tags asssociated with the base asset of this trading pair.

Return type:

set[str]

__init__(base, quote, pool_address, exchange_address, internal_id=None, internal_exchange_id=None, info_url=None, fee=None, reverse_token_order=None, kind=TradingPairKind.spot_market_hold, underlying_spot_pair=None, exchange_name=None, other_data=<factory>)#
Parameters:
Return type:

None