> ## 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. # Agent's manual > Whole data catalog. One page. Caveman format. For model that write query. This page = whole catalog, one page, for model that write query. Nothing link out. Human? Read [Human's manual](/docs/catalog/humans-manual) instead. Page written in [caveman](https://github.com/juliusbrussee/caveman) format. Few token, same rule. No article, no auxiliary verb, no hedge, no transition. Identifier, type, number, negation stay exact. Only grammar go. Read once. Then build table name yourself. No lookup. Name tell you grain, keys, time column, value columns. Name never lie. ## Build table name Name = `dataset.table`. Dataset say what kind, what about. Table say rest. | Pattern | Rows | Key columns | Time column | | ------------------------------------- | --------------------------------------- | ------------------------- | ----------------- | | `dimensions.` | One per thing | `_id` | none | | `facts_.` | One per event | `_id` + event keys | `block_timestamp` | | `metrics_._` | One per thing per period | `_id` | `timestamp` | | `reports_._` | One per thing per period | `_id` | `timestamp` | | `functions.calculate_` | Table function, call with arguments | arguments | argument | | `.` | One per block, transaction, log or call | none | `block_timestamp` | Metrics table = ONE measure. Columns = level ids + `timestamp` + one value column. Value column name = table name minus period. `metrics_projects.fees_daily` → `project_id`, `timestamp`, `fees`. Done. No page needed. Do NOT select column the name not promise. Levels roll up: `app_chains` → `apps` → `projects`. `asset_tokens` → `assets`. Use biggest level that answer question. Rollup already exist. Cheaper. Already correct. ## Rules. Break rule = wrong answer or big bill. All these seen for real. 1. **Bound time column. ALWAYS.** No bound = read whole table. You pay, not us. Facts use `block_timestamp`. Metrics + reports use `timestamp`. 2. **Time bound alone is NOT enough.** Not every table is partitioned, and a bound on an unpartitioned column prunes nothing. Every table is clustered, so also filter its cluster key: the entity id for a metrics table, `token_address` for token facts. Read the keys from `INFORMATION_SCHEMA.COLUMNS`: `is_partitioning_column` and `clustering_ordinal_position`. Filter the leading cluster column first, order matters. Empty result = the object is a VIEW, which reports no keys; take its contract from its page. 3. **Partition column naked on left.** `date(block_timestamp) >= x` = read every partition. Function hide column from pruner. Write `block_timestamp >= timestamp('2026-01-01')`. 4. **Bound BOTH sides of join.** Bound not travel across join. Two tables, two bounds. 5. **One token = filter `token_address` + `chain_id`. NOT `token_id`.** Same rows, but `token_address` is the cluster key and `chain_id` drops whole chains at plan time. `token_id` is derived, reaches no cluster key, and reads every chain: terabytes against megabytes. Keep `token_id` for join to `dimensions.tokens`. 6. **Set `maximum_bytes_billed` on EVERY job.** Over the cap, the query fails before it runs and bills nothing; the error names the bytes it needed. Wrong query costs you an error, not money. `bq query --maximum_bytes_billed=`, or `maximumBytesBilled` in the job config of any client library. Set it low, raise it when the failure tells you to. 7. **Bytes scanned is the bill, NOT rows returned.** [BigQuery on-demand](https://cloud.google.com/bigquery/pricing#analysis_pricing_models) charges per byte the query reads, at a rate per TiB, with a 10 MiB floor per table per query. `limit` changes NOTHING: `limit 10` reads the same bytes as no limit. Naming columns DOES cut the bill, because storage is columnar. Never `select *`. 8. **No recursive CTE. No unbounded self-join.** `with recursive` reads again every step and the bytes compound; a fan-out join multiplies rows before you see them. Size the join with a count first. A question that seems to need recursion wants a smaller question. 9. **Empty ≠ zero.** Empty = no figure exist for that measure, that thing, that day. Do NOT coalesce 0 then average or sum across. Do NOT call it decline. 10. **Get unit from `dimensions.metrics` BEFORE format.** Unit = `usd`, `count`, `ratio`, `pct`. Ratio = fraction: `apy` 0.05 = 5 percent, `off_peg` -0.02 = 2 percent under peg. NEVER assume dollar. 11. **Sum only how `dimensions.metrics` allow.** * *Additive* (fees, volume): sum across day, sum across thing. Both fine. * *Semi-additive* (TVL, supply, open interest): sum across thing. NEVER across day. Week = last day of week. * *Non-additive* (APY, active users, share, funding rate): sum NEITHER way. Week active users = count distinct address over week from fact table. Add 7 daily counts = count same person 7 time. Wrong. 12. **Address case matter.** EVM stored lowercase: wrap explorer address in `lower()`. Solana base58, case-sensitive, match verbatim. 13. **`value_raw` = STRING.** `uint256` overflow every BigQuery number type. Cast `BIGNUMERIC`, divide by `pow(10, decimals)` from `dimensions.tokens`. 14. **Financial statements long, NOT wide.** `reports_projects.financial_statements_*` have `metric_id` + `value`. One statement = many row. Filter line item, or pivot with `max(if(metric_id = ...))`. 15. **NEVER query table from *Not served yet* list.** Those are spec, not table. Tell user data not available. Do NOT write query that cannot run. ## Join keys Id = lowercase name. Combined id = parts joined with dash. Every table carry at least one. That is why catalog join. | Identifier | Shape | Example | | ---------------- | --------------------------------------- | --------------------------- | | `chain_id` | Chain name | `ethereum` | | `project_id` | Project name | `uniswap` | | `app_id` | Project name + version | `uniswap-v3` | | `asset_id` | Asset name | `usdc` | | `token_id` | `{token_address}-{chain_id}` | `0xa0b8…eb48-ethereum` | | `asset_token_id` | `{asset_id}-{token_address}-{chain_id}` | `usdc-0xa0b8…eb48-ethereum` | Asset = one identity, all chains. Token = one contract, one chain. USDC = one row `dimensions.assets`, one row per chain `dimensions.asset_tokens`. ## Question → table Shortest correct path for common question. Prefer metrics table over sum facts table yourself: smaller, and additivity already settled. | Question | Table | | ----------------------------------------- | ----------------------------------------------------------- | | Fees, revenue, TVL, users of a project | `metrics_projects._daily` | | Same, split by chain | `metrics_project_chains._daily` | | Same, one version of a protocol | `metrics_apps._daily` (`app_id` = `uniswap-v3`) | | Project income statement | `reports_projects.financial_statements_quarterly` | | Stablecoin or fund supply | `metrics_assets.market_cap_circulating_total_daily` | | Same, one chain | `metrics_asset_tokens.market_cap_circulating_native_daily` | | Holders of asset | `metrics_assets.holders_native_daily` | | Who hold token right now | `functions.calculate_latest_token_balances` | | Who held token on past day | `functions.calculate_historical_eod_token_balances` | | Every transfer of token | `facts_tokens.transfers` | | Token price series | `metrics_tokens.price_daily`, `metrics_tokens.price_hourly` | | DEX volume, one pool | `metrics_dex_pools.trading_volume_daily` | | DEX volume, one traded pair | `metrics_dex_pool_pairs.trading_volume_daily` | | Perp open interest, funding, liquidations | `metrics_perp_markets._daily` | | Chain fees and revenue | `metrics_chains.fees_daily`, `metrics_chains.revenue_daily` | | What measure mean, unit, additivity | `dimensions.metrics` | | Which measures exist for one thing | `dimensions.metric_instances` | ## All tables Every table in catalog. Generated from pages, so complete at build time. ### Dimensions `dimensions.accounts`, `dimensions.apps`, `dimensions.asset_tokens`, `dimensions.assets`, `dimensions.chains`, `dimensions.contracts`, `dimensions.dex_pools`, `dimensions.lending_market_reserves`, `dimensions.lending_markets`, `dimensions.metric_instances`, `dimensions.metrics`, `dimensions.order_book_markets`, `dimensions.perp_markets`, `dimensions.projects`, `dimensions.reference_assets`, `dimensions.tokens`, `dimensions.transfer_purposes` ### Facts | Table | Key columns | Status | | -------------------------------------- | ----------------------- | -------------- | | `facts_asset_tokens.senders` | `asset_token_id` | served | | `facts_asset_tokens.senders_hll` | `asset_token_id` | served | | `facts_bridge_tokens.transfers` | `bridge_id`, `token_id` | served | | `facts_chains.transactions` | `chain_id` | not served yet | | `facts_dex_pools.trades` | `dex_pool_id` | not served yet | | `facts_lending_markets.borrows` | `lending_market_id` | not served yet | | `facts_lending_markets.deposits` | `lending_market_id` | not served yet | | `facts_lending_markets.flash_loans` | `lending_market_id` | not served yet | | `facts_lending_markets.interest_rates` | `lending_market_id` | served | | `facts_lending_markets.liquidations` | `lending_market_id` | not served yet | | `facts_lending_markets.repayments` | `lending_market_id` | not served yet | | `facts_lending_markets.withdrawals` | `lending_market_id` | not served yet | | `facts_order_book_markets.trades` | `order_book_market_id` | served | | `facts_perp_markets.trades` | `perp_market_id` | served | | `facts_tokens.balance_changes` | `token_id` | served | | `facts_tokens.transfers` | `token_id` | served | ### Metrics | Dataset | Key columns | Periods | Measures | | ---------------------------------- | -------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metrics_app_chains` | `app_id`, `chain_id` | daily | `active_loans`, `fees`, `revenue`, `trading_volume`, `tvl` | | `metrics_apps` | `app_id` | daily | `active_loans`, `assets_staked`, `fees`, `outstanding_supply`, `revenue`, `token_incentives`, `trading_volume`, `tvl`, `user_dau`, `user_mau`, `user_wau` | | `metrics_asset_tokens` | `asset_token_id` | daily | `agentic_user_dau_bridged`, `agentic_user_dau_native`, `agentic_user_mau_bridged`, `agentic_user_mau_native`, `agentic_user_wau_bridged`, `agentic_user_wau_native`, `apy`, `holders_bridged`, `holders_native`, `market_cap_circulating_bridged`, `market_cap_circulating_native`, `market_cap_circulating_total`, `mints_bridged`, `mints_native`, `mints_total`, `redemptions_bridged`, `redemptions_native`, `redemptions_total`, `transfer_count_agentic_bridged`, `transfer_count_agentic_native`, `transfer_count_agentic_total`, `transfer_count_bridged`, `transfer_count_native`, `transfer_count_total`, `transfer_volume_agentic_bridged`, `transfer_volume_agentic_native`, `transfer_volume_agentic_total`, `transfer_volume_bridged`, `transfer_volume_native`, `transfer_volume_total`, `user_dau_bridged`, `user_dau_native`, `user_mau_bridged`, `user_mau_native`, `user_wau_bridged`, `user_wau_native` | | `metrics_assets` | `asset_id` | daily | `agentic_user_dau`, `agentic_user_mau`, `agentic_user_wau`, `apy`, `holders_bridged`, `holders_native`, `market_cap_circulating_bridged`, `market_cap_circulating_native`, `market_cap_circulating_offchain`, `market_cap_circulating_total`, `mints_bridged`, `mints_native`, `mints_total`, `off_peg`, `price`, `redemptions_bridged`, `redemptions_native`, `redemptions_total`, `transfer_count_agentic_bridged`, `transfer_count_agentic_native`, `transfer_count_agentic_total`, `transfer_count_bridged`, `transfer_count_native`, `transfer_count_total`, `transfer_volume_agentic_bridged`, `transfer_volume_agentic_native`, `transfer_volume_agentic_total`, `transfer_volume_bridged`, `transfer_volume_native`, `transfer_volume_total`, `user_dau`, `user_mau`, `user_wau` | | `metrics_bridge_tokens` | `bridge_id`, `token_id` | daily | `destination_transfer_volume`, `source_transfer_volume` | | `metrics_chains` | `chain_id` | daily | `fees`, `fees_supply_side`, `revenue` | | `metrics_dex_pool_pairs` | `dex_pool_id`, `token_in_id`, `token_out_id` | daily | `trading_volume` | | `metrics_dex_pools` | `dex_pool_id` | daily | `fees`, `flash_loan_volume`, `trading_volume`, `tvl` | | `metrics_lending_markets` | `lending_market_id` | daily | `active_loans`, `collateral`, `tvl` | | `metrics_order_book_market_tokens` | `order_book_market_id`, `token_id` | daily | `fees`, `fees_supply_side`, `revenue`, `trading_volume` | | `metrics_order_book_markets` | `order_book_market_id` | daily | `fees`, `fees_supply_side`, `revenue`, `trading_volume` | | `metrics_perp_market_tokens` | `perp_market_id`, `token_id` | daily | `exchange_notional_trading_volume`, `fees`, `fees_supply_side`, `interface_notional_trading_volume`, `notional_trading_volume`, `revenue` | | `metrics_perp_markets` | `perp_market_id` | daily | `active_traders`, `average_long_position_size`, `average_short_position_size`, `exchange_notional_trading_volume`, `fees`, `fees_supply_side`, `funding_rate`, `interface_notional_trading_volume`, `long_liquidations`, `long_open_interest`, `long_traders`, `median_long_position_size`, `median_short_position_size`, `open_interest`, `price`, `revenue`, `short_liquidations`, `short_open_interest`, `short_traders`, `top10_long_trader_share`, `top10_short_trader_share`, `trades_count`, `volume_to_open_interest` | | `metrics_project_chains` | `project_id`, `chain_id` | daily | `active_loans`, `assets_staked`, `fees`, `outstanding_supply`, `revenue`, `token_incentives`, `trading_volume`, `tvl`, `user_dau`, `user_mau`, `user_wau` | | `metrics_projects` | `project_id` | daily | `active_loans`, `assets_staked`, `earnings`, `expenses`, `fees`, `outstanding_supply`, `revenue`, `token_incentives`, `trading_volume`, `treasury`, `treasury_net`, `tvl`, `user_dau`, `user_mau`, `user_wau` | | `metrics_tokens` | `token_id` | daily, hourly | `price` | ### Reports | Dataset | Key columns | Periods | Reports | | ------------------ | ------------ | ----------------- | ---------------------- | | `reports_projects` | `project_id` | quarterly, yearly | `financial_statements` | ### Functions `functions.calculate_historical_eod_token_balances`, `functions.calculate_latest_token_balances` ## Not served yet Name documented before table land. Page = spec. Table NOT exist. Query these = fail. `dimensions.transfer_purposes`, `facts_chains.transactions`, `facts_dex_pools.trades`, `facts_lending_markets.borrows`, `facts_lending_markets.deposits`, `facts_lending_markets.flash_loans`, `facts_lending_markets.liquidations`, `facts_lending_markets.repayments`, `facts_lending_markets.withdrawals` ## Access Catalog = BigQuery share in caller own Google Cloud project. Caller pay compute. No public endpoint. No anonymous access. Missing dataset error = share not set up. Human must arrange. Say so. Do NOT retry.