ERC20s
Note
functions that require multiple RPC calls will attempt to do so concurrently for maximum efficiency
Examples
from ctc import evm
erc20 = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'
erc20s = [
'0x956f47f50a910163d8bf957cf5846d573e7f87ca',
'0x5f98805a4e8be255a32880fdec7f6728c6568ba0',
'0x6b175474e89094c44da98b954eedeac495271d0f',
]
Get ERC20 metadata¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
transfers = await evm.async_get_erc20_transfers(erc20, verbose=False)
transfers
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¶
transfers = await evm.async_get_erc20_transfers(
erc20,
normalize=False,
verbose=False,
)
holders = await evm.async_get_erc20_holdings_from_transfers(transfers)
holders
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’>