Balances

Holder balances are computed at query time from Transfers: every movement splits into its debit and its credit leg, and the legs add up per account. Each function takes a chain, a token address and a token standard, and reads that token’s whole movement history.

Functions

Latest
Historical

functions.calculate_latest_token_balances returns the current holders of one token: each account’s most recent end-of-day balance, kept where it is positive. Picking the most recent row first and applying the positive filter second is what makes the result the holder set today.

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. An `erc20` address is lowercased for you, so a checksummed address copied from an explorer resolves; every other standard is matched as the chain writes it, `spl` and `trc20` being base58.
`p_token_type`	`STRING`	Token standard: `erc20`, `spl` or `trc20`.

Return column	Type	Description
`account_address`	`STRING`	Account holding a positive balance: a wallet on the log-shaped chains, an SPL token account on Solana.
`balance`	`BIGNUMERIC`	Latest end-of-day balance in token units. Added up in exact whole-number arithmetic and scaled by the token’s `decimals`, so a drained account reads exactly zero and leaves the holder set.

functions.calculate_historical_eod_token_balances returns each holder’s end-of-day balance, one row per day the balance moved. A balance on any date is the most recent row at or before that date, so an account that moved tokens on Monday and again on Friday reads its Monday balance until Friday’s row replaces it.

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. An `erc20` address is lowercased for you, so a checksummed address copied from an explorer resolves; every other standard is matched as the chain writes it, `spl` and `trc20` being base58.
`p_token_type`	`STRING`	Token standard: `erc20`, `spl` or `trc20`.

Return column	Type	Description
`balance_date`	`DATE`	Day the balance moved.
`account_address`	`STRING`	Account holding the balance: a wallet on the log-shaped chains, an SPL token account on Solana.
`balance`	`BIGNUMERIC`	End-of-day balance in token units. Added up in exact whole-number arithmetic and scaled by the token’s `decimals`, so a drained account reads exactly zero.

Sample queries

Current holders
Holders on a date
Holder concentration

Each call adds up the token’s whole movement history, so a one-off holder set costs a full scan. Assets ▸ Metrics holds a daily supply and holder-count series for curated assets.

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

The most recent row at or before the date is the balance on that date, so row_number() picks it per account. Accounts at zero are filtered 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

The holder set is every address holding the token on that date, so a share of supply is worked out over the whole set. dimensions.accounts names the addresses somebody has attributed, so pools and receipt-token contracts read as themselves.

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',
        '0x6c3ea9036406852006290770bedfcaba0e23a0e8',
        'erc20'
    )
    where balance_date <= date '2026-06-30'
),

holders as (
    select
        account_address,
        balance,
        row_number() over (order by balance desc) as holder_rank,
        sum(balance) over () as supply_held,
        count(*) over () as holders
    from balances_on_date
    where recency = 1
      and balance > 0
)

select
    holders.holder_rank,
    holders.account_address,
    accounts.contract_name,
    projects.name as project,
    holders.balance,
    holders.balance / holders.supply_held as share_of_supply,
    holders.holders as holders_on_date
from holders
left join `dimensions.accounts` as accounts
    on accounts.account_id = concat(holders.account_address, '-ethereum')
left join `dimensions.projects` as projects
    on projects.project_id = accounts.project_id
where holders.holder_rank <= 20
order by holders.holder_rank

Overview

Popular datasets

Market verticals

Chain ecosystems

Core entities

Functions

Sample queries

​Functions

​Sample queries

Functions

Sample queries