Balances

Balances are not stored anywhere. Two functions in the functions dataset compute them at query time from Balance changes, adding up every change recorded for one token. Each takes a chain, a token address and a token standard.

Functions

Latest
Historical

functions.calculate_latest_token_balances returns everyone holding the token right now: the last end-of-day balance per account, positive balances only. An account that sent everything away falls out rather than appearing at zero.

Parameter	Type	Description
`p_chain_id`	`STRING`	Chain the token is deployed on, for example `ethereum`.
`p_token_address`	`STRING`	Contract address of the token.
`p_token_type`	`STRING`	Token standard, such as `erc20`.

Return column	Type	Description
`account_address`	`STRING`	Account holding a positive balance.
`balance`	`BIGNUMERIC`	Latest end-of-day balance in token units.

The order of the two steps matters. The function takes each account’s most recent row first, then drops the accounts sitting at zero. In the other order, an account that has since sent everything away comes back showing its last positive balance.

functions.calculate_historical_eod_token_balances returns each holder’s end-of-day balance, one row per day the balance moved. There is no row for a day when nothing moved: an account that moved tokens on Monday and again on Friday has two rows and nothing in between, and its balance on Wednesday is whatever the Monday row says. Reading a balance for a given date means taking the most recent row at or before that date.

Parameter	Type	Description
`p_chain_id`	`STRING`	Chain the token is deployed on, for example `ethereum`.
`p_token_address`	`STRING`	Contract address of the token.
`p_token_type`	`STRING`	Token standard, such as `erc20`.

Return column	Type	Description
`balance_date`	`DATE`	Day the balance moved.
`account_address`	`STRING`	Account holding the balance.
`balance`	`BIGNUMERIC`	End-of-day balance in token units, scaled down by `decimals`.

Sample queries

Each call adds up the entire balance-change history of one token. For a daily supply or holder-count series, the daily asset tables carry both for curated assets.

Current holders
Holders on a date

List the current holders of one token.

select
    account_address,
    balance
from `functions.calculate_latest_token_balances`(
    'ethereum',
    '0xdac17f958d2ee523a2206206994597c13d831ec7',
    'erc20'
)
order by balance desc
limit 100

List the holders of one token on a past date. The most recent row at or before the date is the balance on that date, and accounts at zero are dropped after that row is picked.

with balances_on_date as (
    select
        account_address,
        balance,
        row_number() over (partition by account_address order by balance_date desc) as recency
    from `functions.calculate_historical_eod_token_balances`(
        'ethereum',
        '0xdac17f958d2ee523a2206206994597c13d831ec7',
        'erc20'
    )
    where balance_date <= date '2026-06-30'
)

select
    account_address,
    balance
from balances_on_date
where recency = 1
  and balance > 0
order by balance desc
limit 100

Notes

Address matching follows the chain’s own rules. EVM addresses are case-insensitive: they are stored lowercase and both functions lowercase their inputs, so a checksummed address copied from an explorer resolves. Solana addresses are base58 and case-sensitive: they are stored and matched verbatim. Balances are added up in exact whole-number arithmetic and scaled by the token’s decimals, so a drained account reads exactly zero and is not counted as a holder.

Overview

Core entities

Market verticals

Chain verticals

Functions

Sample queries

Notes

​Functions

​Sample queries

​Notes

Functions

Sample queries

Notes