> ## Documentation Index
> Fetch the complete documentation index at: https://tokenterminal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To query the Token Terminal data catalog, read https://tokenterminal.com/docs/catalog/agents-manual.md first. It is the whole catalog as one page: table naming grammar, key columns, partition and cluster rules, units, additivity, and the tables that are documented but not served yet.
> Never query a catalog table on a time bound alone. Also filter its cluster key, which you read from INFORMATION_SCHEMA.COLUMNS; an empty result means the object is a view, whose pruning contract is on its page. Compute is billed to the caller's own Google Cloud project.

# Balances

> Who holds a tokenized asset now, and what each holding is worth.

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

<table>
  <thead>
    <tr>
      <th width="200">Column</th>
      <th width="130">Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>`timestamp`</td><td>TIMESTAMP</td><td>Day the balance is as of: the latest day for the chain.</td></tr>
    <tr><td>`chain_id`</td><td>STRING</td><td>Chain the deployment sits on.</td></tr>
    <tr><td>`asset_id`</td><td>STRING</td><td>Asset the deployment belongs to; joins `dimensions.assets`.</td></tr>
    <tr><td>`token_id`</td><td>STRING</td><td>Key of the deployment, formatted `{token_address}-{chain_id}`.</td></tr>
    <tr><td>`token_address`</td><td>STRING</td><td>Contract address of the deployment. Cluster key with `chain_id`: filter both together to read one deployment.</td></tr>
    <tr><td>`account_address`</td><td>STRING</td><td>The chain's native holding account: a wallet on EVM chains, a token account on Solana.</td></tr>
    <tr><td>`account_owner`</td><td>STRING</td><td>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.</td></tr>
    <tr><td>`balance`</td><td>BIGNUMERIC</td><td>End-of-day balance in whole token units.</td></tr>
    <tr><td>`balance_usd`</td><td>FLOAT64</td><td>`balance` in USD at that day's price; null where the deployment has no price that day.</td></tr>
  </tbody>
</table>

## Sample queries

**Largest holders of one deployment**

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`.

```sql theme={null}
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
```

**One asset across its chains**

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

```sql theme={null}
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
```

**Holdings by asset type**

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

```sql theme={null}
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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.