> ## 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

> Stablecoin holder balances at any past date, computed at query time.

One row per holder of one stablecoin deployment, computed at query time from the transfer history by `functions.calculate_latest_token_balances` and `functions.calculate_historical_eod_token_balances`. `balance` is the holder's amount in whole token units, and each call takes a chain, a token address and a token standard from [Registry](https://tokenterminal.com/docs/catalog/stablecoins/registry.md).

**Coming: a curated pair for stablecoins.** `functions.calculate_latest_asset_token_balances` and `functions.calculate_historical_eod_asset_token_balances` cover the tokenized asset registry, which every stablecoin here belongs to. They refuse rather than returning a number where a deployment cannot be modelled, so a figure they give back is one that has been checked. **In progress**: under test, not yet served. The generic pair above also accepts these tokens, and will answer for a rebasing stablecoin with a number that drifts below the chain.

Both signatures are identical and documented at [Tokens ▸ Balances](https://tokenterminal.com/docs/catalog/tokens/balances.md). What the curated pair covers, and which stablecoins it declines, is at [Assets ▸ Balance changes](https://tokenterminal.com/docs/catalog/assets/balance-changes.md).

## Columns

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

  <tbody>
    <tr>
      <td>`balance_date`</td>
      <td>`DATE`</td>
      <td>Day the balance moved. Returned by `calculate_historical_eod_token_balances`, which writes a row per day an account's balance changed.</td>
    </tr>

    <tr>
      <td>`account_address`</td>
      <td>`STRING`</td>
      <td>Account holding the balance. On Solana this is the token account; [`dimensions.accounts`](https://tokenterminal.com/docs/catalog/accounts/registry) resolves the wallet behind it.</td>
    </tr>

    <tr>
      <td>`balance`</td>
      <td>`BIGNUMERIC`</td>
      <td>End-of-day balance in whole token units, already scaled down by `decimals`. `calculate_latest_token_balances` returns the last one per account, positive balances only.</td>
    </tr>
  </tbody>
</table>

## Sample queries

**Current holders**

Each call adds up the whole balance-change history of one deployment; a daily holder count is cheaper read from `metrics_assets.holders_native_daily` on [Metrics](https://tokenterminal.com/docs/catalog/stablecoins/metrics.md). Addresses are lowercased on input, so a checksummed address pasted from an explorer resolves.

```sql theme={null}
select
    account_address,
    balance
from `functions.calculate_latest_token_balances`(
    'ethereum',
    '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    'erc20'
)
order by balance desc
limit 100
```

**Concentration on a date**

The historical function writes a row only on a day the balance moved. An account's balance on a given date is its most recent row at or before that date.

```sql theme={null}
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',
        '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
        'erc20'
    )
    where balance_date <= date '2026-06-30'
),

holders as (
    select
        balance,
        rank() over (order by balance desc) as balance_rank
    from balances_on_date
    where recency = 1
      and balance > 0
)

select
    count(*) as holders,
    sum(balance) as supply,
    sum(case when balance_rank <= 10 then balance end) / sum(balance) as top_10_share
from holders
```


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