Balances - Token Terminal Docs

One row per account holding a tokenized asset deployment, as of the latest day for that chain. balance is the holding in whole token units, over the same circulating holders as the circulating market cap.

Columns

Column	Type	Description
`timestamp`	TIMESTAMP	Day the balance is as of: the latest day for the chain.
`chain_id`	STRING	Chain the deployment sits on.
`asset_id`	STRING	Asset the deployment belongs to; joins `dimensions.assets`.
`token_id`	STRING	Key of the deployment, formatted `{token_address}-{chain_id}`.
`token_address`	STRING	Contract address of the deployment. Cluster key with `chain_id`: filter both together to read one deployment.
`account_address`	STRING	The chain’s native holding account: a wallet on EVM chains, a token account on Solana.
`account_owner`	STRING	The holder. Equal to `account_address` where the chain does not distinguish them, and the wallet behind the token account where it does. Group by this for a cap table.
`balance`	BIGNUMERIC	End-of-day balance in whole token units.
`balance_usd`	FLOAT64	`balance` in USD at that day’s price; null where the deployment has no price that day.

Sample queries

Largest holders of one deployment
One asset across its chains
Holdings by asset type

The filter on chain_id and token_address reads one deployment’s rows and nothing else. A Solana wallet holds through several token accounts, so the query sums per account_owner.

select
    balances.account_owner,
    sum(balances.balance) as balance,
    sum(balances.balance_usd) as balance_usd
from `facts_asset_tokens.balances_latest` as balances
where balances.chain_id = 'ethereum'
  and balances.token_address = '0x7712c34205737192402172409a8f7ccef8aa2aec'
group by balances.account_owner
order by balance desc
limit 25

asset_id groups every deployment of one asset. Each chain’s rows are as of that chain’s own timestamp.

select
    balances.chain_id,
    max(balances.timestamp) as as_of,
    count(distinct balances.account_owner) as holders,
    sum(balances.balance) as balance,
    sum(balances.balance_usd) as balance_usd
from `facts_asset_tokens.balances_latest` as balances
where balances.asset_id = 'buidl'
group by balances.chain_id
order by balance_usd desc

asset_id joins dimensions.assets, which has the asset type and issuer. balance_usd is null on unpriced holdings, and the sum skips them.

select
    assets.asset_type,
    count(distinct balances.asset_id) as asset_count,
    sum(balances.balance_usd) as balance_usd
from `facts_asset_tokens.balances_latest` as balances
inner join `dimensions.assets` as assets
    on assets.asset_id = balances.asset_id
group by assets.asset_type
order by balance_usd desc