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

# Tokens

> BOB token transfers, holder balances and daily prices.

Four surfaces cover token activity on BOB.

* [`facts_tokens.transfers`](https://tokenterminal.com/docs/catalog/tokens/transfers): one row per token transfer.
* [`functions.calculate_latest_token_balances`](https://tokenterminal.com/docs/catalog/tokens/balances) and its historical sibling: holder balances at any date, computed at query time.
* [`metrics_tokens.price_daily`](https://tokenterminal.com/docs/catalog/tokens/metrics): one USD price per token per day.

The token list is everything we see onchain, which reaches far past the tokens anyone would want: a ranking of the busiest tokens returns contracts whose symbols imitate well-known ones. Nothing has gone wrong when those appear. Joining `dimensions.asset_tokens` keeps the tokens tied to a named asset with a named issuer; [Assets](https://tokenterminal.com/docs/catalog/chain-verticals/evm/bob/assets.md) covers that layer.

Every column and both function signatures are documented at [Tokens](https://tokenterminal.com/docs/catalog/tokens/index.md).

## Sample queries

> [!WARNING]
>
> `facts_tokens.transfers` is large and split by month. Bound `partition_key` and filter `chain_id` on every query, or you read the whole table and the whole table is billed to you.

**Daily activity**

**Count the transfers and the accounts behind them on one day.** A distinct-account count holds for the window it was asked for, and summing several days counts anyone active on more than one of them twice; [Assets ▸ Senders](https://tokenterminal.com/docs/catalog/assets/senders.md) covers the longer windows.

```sql theme={null}
select
    count(*) as transfers,
    count(distinct from_address) as senders,
    count(distinct to_address) as recipients
from `facts_tokens.transfers`
where partition_key >= timestamp('2026-08-01')
  and partition_key < timestamp('2026-09-01')
  and block_timestamp >= timestamp('2026-08-20')
  and block_timestamp < timestamp('2026-08-21')
  and chain_id = 'bob'
  and token_type = 'erc20'
```

**Busiest tokens**

**Rank the busiest BOB tokens on one day.** Joining `dimensions.tokens` on `token_id` adds the symbol and name of each contract.

```sql theme={null}
select
    tokens.symbol,
    transfers.token_address,
    count(*) as transfer_count,
    count(distinct transfers.from_address) as senders
from `facts_tokens.transfers` as transfers
join `dimensions.tokens` as tokens
    using (token_id)
where transfers.partition_key >= timestamp('2026-08-01')
  and transfers.partition_key < timestamp('2026-09-01')
  and transfers.block_timestamp >= timestamp('2026-08-20')
  and transfers.block_timestamp < timestamp('2026-08-21')
  and transfers.chain_id = 'bob'
group by tokens.symbol, transfers.token_address
order by transfer_count desc
limit 20
```

**Net balance moves**

**Find the accounts that gained and lost the most of one token on one day.** Each movement is unnested into its two legs -- the sender debited, the receiver credited -- and summing them per account nets the day; dividing by `10^decimals` converts to token amounts. The token is named by `token_address` and `chain_id`, and those two hold the read to one token's blocks.

```sql theme={null}
select
    leg.account_address,
    sum(leg.balance_change_raw) / pow(10, tokens.decimals) as net_change
from `facts_tokens.transfers` as movements
cross join unnest([
    struct(movements.from_address as account_address,
           -cast(movements.amount_raw as bignumeric) as balance_change_raw),
    struct(movements.to_address as account_address,
            cast(movements.amount_raw as bignumeric) as balance_change_raw)
]) as leg
join `dimensions.tokens` as tokens
    on tokens.token_id = movements.token_id
where movements.partition_key >= timestamp('2026-08-01')
  and movements.partition_key < timestamp('2026-09-01')
  and movements.block_timestamp >= timestamp('2026-08-20')
  and movements.block_timestamp < timestamp('2026-08-21')
  and movements.chain_id = 'bob'
  and movements.token_address = '0x03c7054bcb39f7b2e5b2c7acb37583e32d70cfa3'
  and leg.account_address is not null
group by leg.account_address, tokens.decimals
order by net_change desc
limit 20
```

**Current holders**

**List the largest current holders of one BOB token.** The returned `balance` is already converted out of raw units. Each call adds up the token's whole movement history, so a one-off holder set costs a full scan; [Assets ▸ Metrics](https://tokenterminal.com/docs/catalog/assets/metrics.md) holds a daily supply and holder-count series for curated assets.

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

**Balance history**

**Trace one account's balance in one token over time.** The function returns a row only on the days the balance moved; the balance on any other date is the latest row at or before it. The function replays the same history, so it costs a full scan of the token as well.

```sql theme={null}
select
    balance_date,
    balance
from `functions.calculate_historical_eod_token_balances`(
    'bob',
    '0x03c7054bcb39f7b2e5b2c7acb37583e32d70cfa3',
    'erc20'
)
where account_address = '0x8ce8a7ea34035adb46caae3f66f012dacbbe9f01'
order by balance_date desc
limit 20
```

**Daily price**

**Read one BOB token's daily price.** Each row is the midnight UTC price in USD.

```sql theme={null}
select
    prices.timestamp,
    tokens.symbol,
    prices.price
from `metrics_tokens.price_daily` as prices
join `dimensions.tokens` as tokens
    using (token_id)
where prices.timestamp >= timestamp('2026-08-16')
  and prices.timestamp < timestamp('2026-08-23')
  and prices.token_id = '0x03c7054bcb39f7b2e5b2c7acb37583e32d70cfa3-bob'
order by prices.timestamp
```


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