data.erc20s

Fetches ERC20 datasets and returns them as polars.Dataframe.

Using ERC20Data you can:

1. Get the timeseries of the wallet balances

2. Get all transfers for the wallet

3. Get top volumes breakdown by the wallet

4. etc.

Examples

from datetime import datetime
from web3cat.data import ERC20Data

dates = [datetime(2021, 6, 1), datetime(2021, 7, 1), datetime(2021, 8, 1), datetime(2021, 9, 1)]
addresses = ["0x5d3a536E4D6DbD6114cc1Ead35777bAB948E3643", "0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7"]
erc20_data = ERC20Data("Dai", addresses, min(dates), max(dates))

# All erc20 transfers for addresses
erc20_data.transfers

# All erc20 mints and burns
erc20_data.emission

# All token volumes by address
erc20_data.volume

# Historical total supply
erc20_data.total_supply(dates)

# Historical balances for addresses
erc20_data.balances(addresses, dates)

class web3cat.data.erc20s.ERC20Data(token: str, address_filter: Optional[List[str]], start: int | datetime.datetime, end: int | datetime.datetime, **kwargs)

Bases: DataCore

Datasets for ERC20 token.

Parameters:

• token – Token name or address

• address_filter – Limit token transfer data only to these addresses. All transfers for mainstream tokens is a big chunk of data. This optimization makes fetches faster. This filter doesn’t apply to mints, burns, and total_supply.

• start – Starting timepoint

• end – Ending timepoint

property contract: Contract

A web3.contract.Contract for this token

property meta: ERC20Meta

Metadata for tokens (like name, symbol and decimals)

property address_filter: List[str]

Address filter for this data (transfers only for these addreses)

property transfers: DataFrame

Dataframe with transfers for addresses specified by the address_filter.

Schema

Field	Type	Description
timestamp	numpy.int64	Timestamp of the transfer event
date	datetime.datetime	Date for the timestamp
block_number	numpy.int64	Block number for this transfer
transaction_hash	str	Transaction hash for this transfer
log_index	numpy.int64	Log index inside the transaction for this transfer
from	str	The address from which erc20 token was sent
to	str	The address to which erc20 token was sent
value	numpy.float64	Transfer value

property emission: DataFrame

All mints and burns.

Schema

Field	Type	Description
timestamp	numpy.int64	Timestamp of the transfer event
date	datetime.datetime	Date for the timestamp
block_number	numpy.int64	Block number for this mint / burn
transaction_hash	str	Transaction hash for this mint / burn
log_index	numpy.int64	Log index inside the transaction for this mint / burn
from	str	If non-zero: the burn address
to	str	If non-zero: the mint address
value	numpy.float64	Transfer value

property volume: DataFrame

Dataframe with transfer volumes and balance changes by address.

Schema

Name	Type	Description
address	str	Address
volume	numpy.float64	Volume for the period
change	numpy.float64	Change for the period (aka net volume)

total_supply(timepoints: List[int | datetime.datetime])

Dataframe with total supply of the token

Schema

Field	Type	Description
timestamp	numpy.int64	Timestamp of total supply snapshot
date	datetime.datetime	Date for the timestamp
block_number	numpy.int64	Block number for this total supply snapshot
total_supply	numpy.float64	Total supply in natural tokens (e.g. eth for weth, not wei)

balances(addresses: List[str], timepoints: List[int | datetime.datetime]) → DataFrame

Dataframe with balances for addresses over time.

Parameters:

• addresses – The list of addresses

• timepoints – A list of timepoints

Returns a Dataframe with fields

Field	Type	Description
timestamp	numpy.int64	Timestamp for the snapshot of the balance
date	datetime.datetime	Date for the timestamp
block_number	int	Number of the block
address	str	Ethereum Address
balance	numpy.float64	Balance of an address at the time