Skip to main content
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.
The 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: 
SELECT 
    day,
    token_symbol,
    token_address,
    SUM(balance) as balance,
    SUM(balance_usd) as balance_usd
FROM "query_4419528(blockchain = 'base', filter='address = 0x729170d38dd5449604f35f349fdfcc9ad08257cd', native_token='ETH')"
WHERE day >= timestamp '2025-01-01'
GROUP BY 1, 2, 3
Example Query: https://dune.com/queries/5133694

​
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 the tokens_<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.
These dependencies on transfer and NFT event tables introduce a delay to balance updates, contingent on the latency inherent in the Spellbook’s processing. If an address has not been involved in any of the above activities, its balance will not be updated. This might be the case for non-standard ERC20 contracts that do not emit the 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

The tokens_<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.
⌘I