TokenDetails

Documentation for eth_defi.token.TokenDetails Python class.

class TokenDetails[source]

ERC-20 token Python presentation.

  • A helper class to work with ERC-20 tokens.

  • Read on-chain data, deal with token value decimal conversions.

  • Any field can be None for non-well-formed tokens.

Example how to get USDC details on Polygon:

usdc = fetch_erc20_details(web3, "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174")  # USDC on Polygon
formatted = f"Token {usdc.name} ({usdc.symbol}) at {usdc.address} on chain {usdc.chain_id}"
assert formatted == "Token USD Coin (PoS) (USDC) at 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 on chain 137"

Attributes summary

address

The address of this token.

chain_id

The EVM chain id where this token lives.

decimals

Number of decimals

name

Token name e.g.

symbol

Token symbol e.g.

total_supply

Token supply as raw units

contract

The underlying ERC-20 contract proxy class instance

Methods summary

__init__(contract[, name, symbol, ...])

convert_to_decimals(raw_amount)

Convert raw token units to decimals.

convert_to_raw(decimal_amount)

Convert decimalised token amount to raw uint256.

fetch_balance_of(address[, block_identifier])

Get an address token balance.

generate_cache_key(chain_id, address)

Generate a cache key for this token.
contract: web3.contract.contract.Contract

The underlying ERC-20 contract proxy class instance

name: Optional[str] = None

Token name e.g. USD Circle

symbol: Optional[str] = None

Token symbol e.g. USDC

total_supply: Optional[int] = None

Token supply as raw units

decimals: Optional[int] = None

Number of decimals

property chain_id: int

The EVM chain id where this token lives.

property address: eth_typing.evm.HexAddress

The address of this token.

convert_to_decimals(raw_amount)[source]

Convert raw token units to decimals.

Example:

details = fetch_erc20_details(web3, token_address)
# Convert 1 wei units to edcimals
assert details.convert_to_decimals(1) == Decimal("0.0000000000000001")
Parameters

raw_amount (int) –

Return type

decimal.Decimal

convert_to_raw(decimal_amount)[source]

Convert decimalised token amount to raw uint256.

Example:

details = fetch_erc20_details(web3, token_address)
# Convert 1.0 USDC to raw unit with 6 decimals
assert details.convert_to_raw(1) == 1_000_000
Parameters

decimal_amount (decimal.Decimal) –

Return type

int

fetch_balance_of(address, block_identifier='latest')[source]

Get an address token balance.

Parameters

  • block_identifier – A specific block to query if doing archive node historical queries

  • address (Union[eth_typing.evm.HexAddress, str]) –

Returns

Converted to decimal using convert_to_decimal()

Return type

decimal.Decimal

static generate_cache_key(chain_id, address)[source]

Generate a cache key for this token.

  • Cached by (chain, address) tuple

  • Validate the inputs before generating the key

Parameters

  • chain_id (int) –

  • address (str) –

Return type

int

__init__(contract, name=None, symbol=None, total_supply=None, decimals=None)
Parameters
Return type

None