ERC20s

Note

functions that require multiple RPC calls will attempt to do so concurrently for maximum efficiency

Examples

In [1]:

from ctc import evm

In [2]:

erc20 = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'

erc20s = [
    '0x956f47f50a910163d8bf957cf5846d573e7f87ca',
    '0x5f98805a4e8be255a32880fdec7f6728c6568ba0',
    '0x6b175474e89094c44da98b954eedeac495271d0f',
]

Get ERC20 metadata¶

In [3]:

name = await evm.async_get_erc20_name(erc20)
symbol = await evm.async_get_erc20_symbol(erc20)
decimals = await evm.async_get_erc20_decimals(erc20)

print('name:', name)
print('symbol:', symbol)
print('decimals:', decimals)

name: Fei USD
symbol: FEI
decimals: 18

Get ERC20s metadata¶

In [4]:

names = await evm.async_get_erc20s_names(erc20s)
symbols = await evm.async_get_erc20s_symbols(erc20s)
decimals = await evm.async_get_erc20s_decimals(erc20s)

print('names:', names)
print('symbols:', symbols)
print('decimals:', decimals)

names: ['Fei USD', 'LUSD Stablecoin', 'Dai Stablecoin']
symbols: ['FEI', 'LUSD', 'DAI']
decimals: [18, 18, 18]

Get ERC20 state¶

In [5]:

total_supply = await evm.async_get_erc20_total_supply(erc20)
address_balance = await evm.async_get_erc20_balance_of(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
)

print('total_supply:', total_supply)
print('address_balance:', address_balance)

total_supply: 559506382.6688191
address_balance: 82013460.60914315

Get raw un-normalized ERC20 state¶

In [6]:

raw_total_supply = await evm.async_get_erc20_total_supply(
    erc20,
    normalize=False,
)
raw_address_balance = await evm.async_get_erc20_balance_of(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    normalize=False,
)

print('raw_total_supply:', raw_total_supply)
print('raw_address_balance:', raw_address_balance)

raw_total_supply: 559506382668819036430800521
raw_address_balance: 82013460609143161348292841

Normalize raw un-normalized ERC20 values¶

In [7]:

normalized_total_supply = await evm.async_normalize_erc20_quantity(
    raw_total_supply,
    erc20,
)
normalized_values = await evm.async_normalize_erc20_quantities(
    [raw_total_supply, raw_address_balance],
    erc20,
)

print('normalized_total_supply:', normalized_total_supply)
print('normalized_values:', normalized_values)

normalized_total_supply: 559506382.6688191
normalized_values: [559506382.6688191, 82013460.60914317]

Get historical ERC20 state from a specific block¶

In [8]:

total_supply = await evm.async_get_erc20_total_supply(
    erc20,
    block=14000000,
)
address_balance = await evm.async_get_erc20_balance_of(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    block=14000000,
)

print('total_supply:', total_supply)
print('address_balance:', address_balance)

total_supply: 751748886.6295298
address_balance: 126538335.35590503

Get historical ERC20 state across multiple blocks¶

In [9]:

blocks = [14000000, 14100000, 14200000]

total_supplies = await evm.async_get_erc20_total_supply_by_block(
    erc20,
    blocks=blocks,
)
address_balances = await evm.async_get_erc20_balance_of_by_block(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    blocks=blocks,
)

print('total_supplies:', total_supplies)
print('address_balances:', address_balances)

total_supplies: [751748886.62953, 528229617.5828952, 550695508.5094506]
address_balances: [126538335.35590503, 110223666.2844692, 122075790.9010594]

Get state of multiple ERC20s¶

In [10]:

total_supplies = await evm.async_get_erc20s_total_supplies(erc20s)
address_balances = await evm.async_get_erc20s_balance_of(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20s,
)

print('total_supplies:', total_supplies)
print('address_balances:', address_balances)

total_supplies: [559506382.6688191, 486343744.2968917, 8667121220.280003]
address_balances: [82013460.60914317, 0.0, 0.0]

Get ERC20 balance of multiple addresses¶

In [11]:

addresses = [
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    '0x9928e4046d7c6513326ccea028cd3e7a91c7590a',
    '0x2a188f9eb761f70ecea083ba6c2a40145078dfc2',
]

addresses_balances = await evm.async_get_erc20_balance_of_addresses(
    addresses,
    erc20,
)

print('addresses_balances:', addresses_balances)

addresses_balances: [82013460.60914317, 81847315.3602611, 50080265.77634068]

Get ERC20 transfers¶

In [12]:

transfers = await evm.async_get_erc20_transfers(erc20, verbose=False)

transfers

Out[12]:

			address	transaction_hash	block_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__amount
block_number	transaction_index	log_index
12168368	61	29	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x3bce142af146fec596340d67569a44688690955a065f...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195.326042
		32	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x3bce142af146fec596340d67569a44688690955a065f...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904.36974
		34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x3bce142af146fec596340d67569a44688690955a065f...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904.36974
		42	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x3bce142af146fec596340d67569a44688690955a065f...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0.0
		46	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x3bce142af146fec596340d67569a44688690955a065f...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500.0
...	...	...	...	...	...	...	...	...	...	...	...
14658112	29	70	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x6380ed1ff7267489f6e0c3d911f5fb7b5eb5ed800505...	0x30aa8e2534a5871dd4b55b97c209a9b037ee9ac23121...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x81e289cdb4c163eda38a85d98e6e3e18106b0577	0x4188fbd7adc72853e3275f1c3503e170994888d7	214110.904466
		74	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x6380ed1ff7267489f6e0c3d911f5fb7b5eb5ed800505...	0x30aa8e2534a5871dd4b55b97c209a9b037ee9ac23121...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x4188fbd7adc72853e3275f1c3503e170994888d7	0xd8553552f8868c1ef160eedf031cf0bcf9686945	214110.904466
14658180	312	472	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5fbedf40dc8736edaa2dff2f0efecc67968e664e6961...	0x9b0d83344416e39e705b3b1bc94ad599282ce113739d...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	0xbc99c4bd93c24db1bf553f2c7f9348be639fe5b6	100.0
14658188	27	75	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xd583165618e774fddd86ad295213d08b1555bba9baee...	0xfb587295db467998b8f66b97d4ca02d5478654586fb2...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xbc99c4bd93c24db1bf553f2c7f9348be639fe5b6	0x4188fbd7adc72853e3275f1c3503e170994888d7	100.0
		79	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xd583165618e774fddd86ad295213d08b1555bba9baee...	0xfb587295db467998b8f66b97d4ca02d5478654586fb2...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x4188fbd7adc72853e3275f1c3503e170994888d7	0xd8553552f8868c1ef160eedf031cf0bcf9686945	100.0

230803 rows × 9 columns

Get ERC20 holdings from transfers¶

In [13]:

transfers = await evm.async_get_erc20_transfers(
    erc20,
    normalize=False,
    verbose=False,
)
holders = await evm.async_get_erc20_holdings_from_transfers(transfers)

holders

Out[13]:

address
0x06cb22615ba53e60d67bf6c341a0fd5e718e1655      82013460609143161348292841
0x9928e4046d7c6513326ccea028cd3e7a91c7590a      81847315360261096266963204
0x2a188f9eb761f70ecea083ba6c2a40145078dfc2      50080265776340681042249402
0xdf50fbde8180c8785842c8e316ebe06f542d3443      46065744752632102671172954
0xbc9c084a12678ef5b516561df902fdc426d95483      39071315320916302703293699
                                                          ...             
0x5e8c6d1b31c681f0759e86f186c085b1e00195bc                               0
0x5e8f0803d03dfbf397bf732c3232f6bebd2e0c0d                               0
0x5e945fe1851a2bfc86d618e200708d6209bb9bb6                               0
0x5e986b9794cba744d06299e214217ae5f926b244                               0
0x0000000000000000000000000000000000000000    -559506382668819036430800521
Name: balance, Length: 19605, dtype: object

Reference

async ctc.evm.async_get_erc20_balance_of(address, token, block=None, normalize=True, provider=None, **rpc_kwargs)

Parameters

• address (<class 'str'>) –

• token (<class 'str'>) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• normalize (<class 'bool'>) –

• provider (Union[str, PartialProvider, Provider, NoneType]) –

• rpc_kwargs (Any) –

Return type

Union[int, float]

async ctc.evm.async_get_erc20_balance_of_addresses(addresses, token, block=None, normalize=True, provider=None, **rpc_kwargs)

async ctc.evm.async_get_erc20_balance_of_by_block(address, token, blocks, normalize=True, provider=None, empty_token=0, **rpc_kwargs)

async ctc.evm.async_get_erc20_decimals(token, block=None, **rpc_kwargs)

get decimals of an erc20

Parameters

• token (<class 'str'>) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• rpc_kwargs (Any) –

Return type

<class ‘int’>

async ctc.evm.async_get_erc20_holdings_from_transfers(transfers, block=None, dtype=None, normalize=False)

Parameters

• transfers (Any) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• dtype (Union[Type[int], Type[float], NoneType]) –

• normalize (<class 'bool'>) –

Return type

Any

async ctc.evm.async_get_erc20_name(token, block=None, **rpc_kwargs)

get name of an erc20

Parameters

• token (<class 'str'>) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• rpc_kwargs (Any) –

Return type

<class ‘str’>

async ctc.evm.async_get_erc20_symbol(token, block=None, **rpc_kwargs)

get symbol of an erc20

Parameters

• token (<class 'str'>) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• rpc_kwargs (Any) –

Return type

<class ‘str’>

async ctc.evm.async_get_erc20_total_supply(token, block=None, normalize=True, provider=None, **rpc_kwargs)

Parameters

• token (<class 'str'>) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• normalize (<class 'bool'>) –

• provider (Union[str, PartialProvider, Provider, NoneType]) –

• rpc_kwargs (Any) –

Return type

Union[int, float]

async ctc.evm.async_get_erc20_total_supply_by_block(token, blocks, normalize=True, provider=None, **rpc_kwargs)

async ctc.evm.async_get_erc20_transfers(token_address, start_block=None, end_block=None, normalize=True, convert_from_str=True, **event_kwargs)

Parameters

• token_address (<class 'str'>) –

• start_block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• end_block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

• normalize (<class 'bool'>) –

• convert_from_str (<class 'bool'>) –

• event_kwargs (Any) –

Return type

Any

async ctc.evm.async_get_erc20s_balance_of(address, tokens, block=None, normalize=True, provider=None, **rpc_kwargs)

async ctc.evm.async_get_erc20s_decimals(tokens, block=None, **rpc_kwargs)

get decimals of multiple erc20s

async ctc.evm.async_get_erc20s_names(tokens, block=None, **rpc_kwargs)

get name of multiple erc20s

async ctc.evm.async_get_erc20s_symbols(tokens, block=None, **rpc_kwargs)

get symbol of multiple erc20s

async ctc.evm.async_get_erc20s_total_supplies(tokens, block=None, normalize=True, provider=None, **rpc_kwargs)

async ctc.evm.async_normalize_erc20_quantities(quantities, token=None, provider=None, decimals=None, block=None)

Parameters

• quantities (Sequence[SupportsInt] | Series) –

• token (ERC20Address | None) –

• provider (ProviderSpec) –

• decimals (Optional[SupportsInt]) –

• block (Optional[BlockNumberReference]) –

Return type

list[float]

async ctc.evm.async_normalize_erc20_quantity(quantity, token=None, provider=None, decimals=None, block=None)

convert raw erc20 quantity by adjusting radix by (10 ** decimals)

Parameters

• quantity (<class 'SupportsFloat'>) –

• token (Union[str, NoneType]) –

• provider (Union[str, PartialProvider, Provider, NoneType]) –

• decimals (Union[SupportsInt, NoneType]) –

• block (Union[SupportsRound, str, int, Literal['latest'], Literal['earliest'], Literal['pending'], NoneType]) –

Return type

<class ‘float’>