ERC20s

Note

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

Examples

Note

These examples are crafted as a Jupyter notebook. You can download the original notebook file here.

Also note that inside Jupyter notebooks, await can be used freely outside of asyncio.run().

erc20s

In [1]:

import ctc

In [2]:

erc20 = '0x956f47f50a910163d8bf957cf5846d573e7f87ca'

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

Get ERC20 metadata¶

In [3]:

name = await ctc.async_get_erc20_name(erc20)
symbol = await ctc.async_get_erc20_symbol(erc20)
decimals = await ctc.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 ctc.async_get_erc20s_names(erc20s)
symbols = await ctc.async_get_erc20s_symbols(erc20s)
decimals = await ctc.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 ctc.async_get_erc20_total_supply(erc20)
address_balance = await ctc.async_get_erc20_balance(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
)

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

total_supply: 60925882.852203734
address_balance: 782894.7941072898

Get raw un-normalized ERC20 state¶

In [6]:

raw_total_supply = await ctc.async_get_erc20_total_supply(
    erc20,
    normalize=False,
)
raw_address_balance = await ctc.async_get_erc20_balance(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20,
    normalize=False,
)

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

raw_total_supply: 60925882852203735163742362
raw_address_balance: 782894794107289757933400

Normalize raw un-normalized ERC20 values¶

In [7]:

normalized_total_supply = await ctc.async_normalize_erc20_quantity(
    raw_total_supply,
    erc20,
)
normalized_values = await ctc.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: 60925882.852203734
normalized_values: [60925882.852203734, 782894.7941072898]

Get historical ERC20 state from a specific block¶

In [8]:

total_supply = await ctc.async_get_erc20_total_supply(
    erc20,
    block=14000000,
)
address_balance = await ctc.async_get_erc20_balance(
    '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 ctc.async_get_erc20_total_supply_by_block(
    erc20,
    blocks=blocks,
)
address_balances = await ctc.async_get_erc20_balance_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 ctc.async_get_erc20s_total_supplies(erc20s)
address_balances = await ctc.async_get_erc20s_balances(
    '0x06cb22615ba53e60d67bf6c341a0fd5e718e1655',
    erc20s,
)

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

total_supplies: [60925882.852203734, 169451076.90321591, 6470667884.040302]
address_balances: [782894.7941072898, 0.0, 0.0]

Get ERC20 balance of multiple addresses¶

In [11]:

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

addresses_balances = await ctc.async_get_erc20_balances_of_addresses(
    addresses,
    erc20,
)

print('addresses_balances:', addresses_balances)

addresses_balances: [782894.7941072898, 13430875.390003089, 0.0]

Get ERC20 transfers¶

In [12]:

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

transfers

Out[12]:

			address	block_hash	transaction_hash	contract_address	event_name	event_hash	arg__from	arg__to	arg__amount
block_number	transaction_index	log_index
12168368	61	29	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	1302613195.326042
		32	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	1315770904.36974
		34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x94b0a3d511b6ecdb17ebf877278ab030acb0a878	1315770904.36974
		42	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9b0c6299d08fe823f2c0598d97a1141507e4ad86	0x0000000000000000000000000000000000000000	0.0
		46	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x3bce142af146fec596340d67569a44688690955a065f...	0xc9851f374701f76024c1f44f7166e0ef8a9945675046...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x0000000000000000000000000000000000000000	0xbffb152b9392e38cddc275d818a3db7fe364596b	500.0
...	...	...	...	...	...	...	...	...	...	...	...
15613010	41	309	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0xaae39c6fe7493accb4638bf7c56ae46c8bce5fa0fa3d...	0xd5a6c5231f6f1a8b67ae6a5399ea1d827b0ad3edecd5...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xf2f400c138f9fb900576263af0bc7fcde2b1b8a8	0xba12222222228d8ba445958a75a0704d566bf2c8	185.469717
15613063	96	263	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x18107b4cd7d0f7271fa0a7acff48b39d50c0b765e06a...	0x0a249e10c1e5e74a08cb1f34313eeccc8d0208c4de08...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	82.440313
15613067	47	148	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5687eabcf6df0d3f400f8b56616b3a37391b927a8113...	0x992111315f732cb36397113171f30b12ab177cea53c1...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9928e4046d7c6513326ccea028cd3e7a91c7590a	0x9435f1085584764b081177944033d4ed2cfd23ee	118.178479
15613072	119	257	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x5b390756df46a718f25302f6d0ce716bff2b862fe486...	0xd379f7a306705039563bb0f3673303a55688b9857305...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0x9435f1085584764b081177944033d4ed2cfd23ee	0xdf50fbde8180c8785842c8e316ebe06f542d3443	200.618792
15613170	3	34	0x956f47f50a910163d8bf957cf5846d573e7f87ca	0x0d8b43d3739d7d28d4ff9cbf08454a6e609979dbdead...	0xca4556984e83346d371ef525e4df96746354fe322908...	0x956f47f50a910163d8bf957cf5846d573e7f87ca	Transfer	0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4...	0xba12222222228d8ba445958a75a0704d566bf2c8	0xdf50fbde8180c8785842c8e316ebe06f542d3443	847.083255

276957 rows × 9 columns

Get ERC20 balances from transfers¶

In [13]:

transfers = await ctc.async_get_erc20_transfers(
    erc20,
    normalize=False,
    verbose=False,
)
holders = await ctc.async_get_erc20_balances_from_transfers(transfers)

holders

Out[13]:

address
0x3a24fea1509e1baeb2d2a7c819a191aa441825ea     23649097120164751841622097
0x9928e4046d7c6513326ccea028cd3e7a91c7590a     13430875390003088310235460
0xc69ddcd4dfef25d8a793241834d4cc4b3668ead6      3367911210892676408060632
0xfafc562265a49975e8b20707eac966473795cf90      2634540334855403348554034
0xfea132a3b7b70089f3d58f04ec1d1c2f321ef660      2224435487972802282933177
                                                         ...             
0x5d2bea390f2a02734d4d4a427409be221c8a2f79                              0
0x5d1e8591452763486966752263c8298421f42fdd                              0
0x5d1aa8941d5bb8751000dec8a73cf3d293d221ff                              0
0x5d17b355538a9ea9b45a0018e11b36947fc16376                              0
0x0000000000000000000000000000000000000000    -60925882852203735163742362
Name: balance, Length: 21013, dtype: object

Reference

async ctc.evm.async_get_erc20_balance(wallet, token, *, block=None, normalize=True, provider=None, **rpc_kwargs): get ERC20 balance

async ctc.evm.async_get_erc20_balances_of_addresses(wallets, token, *, block=None, normalize=True, provider=None, **rpc_kwargs): get ERC20 balance of multiple addresses

async ctc.evm.async_get_erc20_balance_by_block(wallet, token, *, blocks, normalize=True, provider=None, empty_token=0, **rpc_kwargs): get historical ERC20 balance over multiple blocks

async ctc.evm.async_get_erc20_decimals(token, *, block=None, use_db=True, provider=None, **rpc_kwargs): get decimals of an erc20

async ctc.evm.async_get_erc20_balances_from_transfers(transfers, *, block=None, dtype=None, normalize=False): compute ERC20 balance of each wallet using Transfer events

async ctc.evm.async_get_erc20_name(token, *, block=None, use_db=True, provider=None, **rpc_kwargs): get name of an erc20

async ctc.evm.async_get_erc20_symbol(token, *, block=None, use_db=True, provider=None, **rpc_kwargs): get symbol of an erc20

async ctc.evm.async_get_erc20_total_supply(token, *, block=None, normalize=True, provider=None, **rpc_kwargs): get total supply of ERC20

async ctc.evm.async_get_erc20_total_supply_by_block(token, blocks, *, normalize=True, provider=None, **rpc_kwargs): get historical total supply of ERC20 across multiple blocks

async ctc.evm.async_get_erc20_transfers(token, *, start_block=None, end_block=None, start_time=None, end_time=None, include_timestamps=False, normalize=True, convert_from_str=True, verbose=False, provider=None, **event_kwargs): get transfer events of ERC20 token

async ctc.evm.async_get_erc20s_balances(wallet, tokens, *, block=None, normalize=True, provider=None, **rpc_kwargs): get ERC20 balance of wallet for multiple tokens

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): get total supplies of ERC20s

async ctc.evm.async_normalize_erc20_quantities(quantities, token=None, *, provider=None, decimals=None, block=None): normalize ERC20 quantites by adjusting radix by (10 ** decimals)

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)