IMPORTANT: These tables are currently very unperformant. The ONLY efficient way to query them is by using the query template pattern shown below. Do NOT query these tables directly - you will experience timeouts and poor performance.
tokens_<chain>.balances_daily
and tokens_<chain>.balances
tables contain token balances across all addresses on EVM-compatible networks. This dataset encompasses:
- Native currency balances (such as ETH, MATIC)
- ERC-20 token balances
- ERC-721 (NFT) balances
- ERC-1155 token balances
How to Query These Tables Efficiently
The ONLY performant way to query these tables is through the query template pattern:Template Parameters
- blockchain: The EVM chain to query (e.g., ‘base’, ‘ethereum’, ‘arbitrum’, ‘optimism’)
- filter: Filter condition for addresses (e.g.,
'address = 0x...'
) - native_token: The native token symbol for the chain (e.g., ‘ETH’, ‘MATIC’)
Network Coverage
Balances are available for the following EVM-compatible networks:- Arbitrum
- Avalanche C-Chain
- Base
- Ethereum
- Kaia
- Linea
- Optimism
- Polygon
- Scroll
- Worldchain
Balance Calculation Methodology
Our approach to storing balances involves querying the blockchain for the balance of each address at the end of the day. The balance is then stored in thetokens_<chain>.balances
table, which is updated daily. For the balance to be queried, the address must have appeared in any of the following tables:
- For native currencies: Transactions and traces
to
/from
addresses, Ethereum-specific withdrawals, and block mining/validator activities. - For ERC20: Analysis is based on token transfer events detailed in the tokens_ethereum_base_transfers. The address balance is updated based on the
to
/from
addresses in the transfer events. If the token is a non-standard ERC20 token, the balance might not be updated until we detect a standard ERC20 transfer event. Known issues currently include ERC4626 tokens and rebasing tokens like stETH or $ampleforth. We are working on improving the range of balance changes that we detect. - For ERC721 and ERC1155: Inspection of NFT transfer activities via the nft_ethereum_transfers, focusing on the
to
/from
addresses.
Transfer
event, or for addresses that have not been involved in any transactions or NFT transfers. If there is a specific token that does not emit the Transfer
event, but has a different event for token transfers, please let us know and we will see if we can include it in our balance calculations.
Granular Balances
Thetokens_<chain>.balances
table provides a more granular view of token balances, containing granular balance changes for each address and token combination per block. This table is updated in near real-time and is used to calculate the daily balances.
The tokens_<chain>.balances
table adds a new row every time a balance changes but does not carry the balance forward for every block. Instead, it only creates a new row for a balance change of an address and token combination.
Direct querying is possible for the
tokens_<chain>.balances
table when querying a limited time range and small number of addresses. For broader queries, use the query template pattern shown above.