Human's manual - Token Terminal Docs

The catalog is a set of BigQuery tables. These docs describe every one of them, and every page follows the same shape. This page explains the organization, the table names, the parts of a page and the marks on it.

Organization

The catalog is one set of tables, presented four ways.

Band	What it is
Core entities	The model of the system and the actors in it. A project runs apps on chains and issues assets; an asset is deployed as tokens; tokens move between accounts. Every table in the catalog is keyed to one or more of those actors. Each entity section holds their registry, the events they take part in, and their daily numbers.
Core datasets	A dataset that belongs to no single market and no single chain: Financial statements, Prices, Agentic payments, Yields, Token transfers, Account labels and P&L. Each one answers a question on its own terms, so its shape follows the question rather than the house pattern. The entity keys still join: every row carries a `project_id`, `asset_id`, `token_id` or account address.
Market verticals	A cross-chain slice into one market: Stablecoins, Tokenized assets, DEX, Perpetuals, Lending, Bridges and the rest. A market is the entity tables with one filter applied, so its pages point back at the tables the entities own.
Chain verticals	One chain’s slice across every market: its raw blocks and transactions, then every entity and market layer with data on that chain. Each chain page lists the layers the chain carries and the date each one starts.

Dataset types

Every catalog table lives in one of five kinds of dataset, and the dataset name says what kind of table it is. Each kind has its own icon in the sidebar.

Dimensions are the registry. A dimension is the metadata of every thing of one kind, one row per thing: its name, its identifiers and its classifications. dimensions.assets is every asset, dimensions.chains every chain, dimensions.dex_pools every trading pool. Nothing on a dimension row changes from day to day. Every other table joins a dimension on its id. The Registry page of each section documents them.

Assets ▸ Registry

Asset names, where each is issued, and what each one tracks.

Projects ▸ Registry

Project and app names, market sectors, and who runs what.

DEX ▸ Registry

Pool identity, the fee it charges, its tokens, and who runs it.

Facts are events. A fact is one row per thing that happened onchain, at the time it happened: the block, the transaction, the accounts involved, the amount and the ids of the dimensions it belongs to. facts_tokens.transfers is every token transfer, facts_bridge_tokens.transfers every cross-chain transfer, facts_lending_markets.deposits every deposit into a lending market. Amounts are in the token’s own units; a USD value is a join to prices. Facts are the record every metric is built from. Each fact table has its own page, named by its event: Transfers, Trades, Deposits.

Tokens ▸ Transfers

Every fungible token transfer.

Bridges ▸ Transfers

Cross-chain bridge transfers, with the sending and arriving sides matched.

Perpetuals ▸ Trades

Individual perpetual and order-book trades.

Metrics are aggregates over a period. Each measure has its own table, holding one row per thing per period with that thing’s identifier columns and one value column: daily for most tables, hourly for prices. Every measure of one kind of thing sits in one dataset, so metrics_assets.market_cap_circulating_total_daily is every asset’s supply on every day and metrics_tokens.price_hourly is every token’s price every hour. Reading two measures at once is a join on the thing’s id and the period. Metrics are built from the facts and keyed to the same dimensions, so a metric row joins its registry row on the same id. The Metrics page of each section documents them, and Metric definitions holds the unit and the combination rule of every measure.

Assets ▸ Metrics

Daily asset tables: supply, holders, transfers, price, yield and the gap from peg.

Projects ▸ Metrics

TVL, Fees, Revenue, Token incentives, Active users and sector-specific volume at every level.

Tokens ▸ Prices

One USD price per token per day, and per hour.

Reports are a set of measures pre-joined into one row, for a question you would otherwise answer by joining several metrics tables. A report row is one thing for one period, carrying every measure the question needs side by side, so reports_projects.financial_statements_quarterly is one project’s income statement and treasury for a quarter, in one row, rather than eight metrics tables joined on project and period. Reports hold nothing the metrics tables do not: every column traces back to a measure, so a figure read here and the same figure read from its metrics table agree. Reach for a report when the question is already the one it answers, and for metrics when it is not.A period in the table name means the table carries history, one row per period. No period in the name means one row per thing, as of now.

Core datasets ▸ Financial statements

A protocol’s income statement and treasury, by reporting period.

Functions are calculations on request. A function runs when you call it, for figures too numerous to store. functions.calculate_latest_token_balances returns every holder of a token and their balance, worked out from the token’s balance changes at query time. Function pages document them.

Tokens ▸ Balances

Holder balances on any past date, computed at query time.

Stablecoins ▸ Balances

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

Raw chain datasets stand apart from the four. Each chain has its own dataset named after it, holding the chain’s own record in a standardized shape: ethereum.transactions is every Ethereum transaction, solana.blocks every Solana block. Chains of the same kind share one shape, so a query written for one EVM chain runs on another with the dataset name swapped. Chain verticals document them.

Ethereum ▸ Raw

The standardized Ethereum blocks, transactions, logs and internal calls.

Base ▸ Raw

The standardized Base blocks, transactions, logs and internal calls.

Solana

Standardized Solana blocks, transactions, instructions, account activity and rewards.

Table names

A table name is dataset.table. The dataset says what kind of table it is, and for facts and metrics it also says which things the table is about. Things are plural in a table name and singular in the identifier column that joins them: facts_lending_markets.deposits carries lending_market_id, which joins dimensions.lending_markets.

dimensions.<things>: the things, plural. One row per thing.

Table	Reads as
`dimensions.assets`	The registry of assets.
`dimensions.asset_tokens`	The registry of asset tokens: one asset on one chain.
`dimensions.dex_pools`	The registry of DEX pools.
`dimensions.lending_markets`	The registry of lending markets.
`dimensions.metrics`	The registry of measures: the unit and combination rule of every one.

facts_<things>.<events>: the dataset names the thing the event happens to, plural; the table names the event, plural. One row per event. The thing’s identifier column joins its dimension.

Table	Thing	Event	Reads as
`facts_tokens.transfers`	Token	Transfer	Transfers of tokens, one row per transfer.
`facts_tokens.balance_changes`	Token	Balance change	Balance changes of tokens, two rows per transfer: one per side.
`facts_bridge_tokens.transfers`	Bridge	Transfer	Transfers across bridges, one row per cross-chain transfer with both legs paired.
`facts_lending_markets.deposits`	Lending market	Deposit	Deposits into lending markets, one row per deposit.
`facts_perp_markets.trades`	Perp market	Trade	Trades on perpetual markets, one row per leg of a fill.

metrics_<things>.<measure>_<period>: the dataset names the level, the things measured, plural; two things joined means one row per pair, and every level rolls up to the one above it. The table names the measure and the period, the row’s time step. One measure per table, so a row carries the level’s identifier columns, the period column and one value column of the same name as the measure.

Table	Level	Measure	Period
`metrics_assets.market_cap_circulating_total_daily`	One asset	Circulating market cap	Day
`metrics_asset_tokens.holders_native_daily`	One asset on one chain	Holders	Day
`metrics_projects.fees_daily`	One project	Fees	Day
`metrics_project_chains.fees_daily`	One project on one chain	Fees	Day
`metrics_dex_pool_pairs.trading_volume_daily`	One pool, one traded pair	Trading volume	Day
`metrics_tokens.price_daily`	One token	Price	Day
`metrics_tokens.price_hourly`	One token	Price	Hour

reports_<things>.<report>_<period>: the dataset names the things the report is about, plural, and the table names the report and the period each row covers. Unlike a metrics table it carries many measures rather than one, because the point of a report is that the joining is already done.

Table	Reads as
`reports_projects.financial_statements_quarterly`	One project’s financial statement for one quarter, per row.
`reports_projects.financial_statements_yearly`	The same statement over calendar years.

functions.calculate_<result>: calculate_, then what comes back. Called with arguments, in place of a table name.

Function	Reads as
`functions.calculate_latest_token_balances`	Calculates the latest balance of every holder of one token.
`functions.calculate_historical_eod_token_balances`	Calculates every holder’s balance of one token at the end of a past day.

<chain>.<table>: the chain’s chain_id as the dataset, then the record type, plural. One row per block, transaction, log or call.

Table	Reads as
`ethereum.blocks`	Ethereum’s blocks, one row per block.
`ethereum.transactions`	Ethereum’s transactions, one row per transaction.
`base.logs`	Base’s event logs, one row per log.
`solana.account_activity`	Solana’s account activity, one row per account touched per transaction.

Page kinds

Every page is one of the kinds below. Each kind has a fixed flow of parts, top to bottom.

The first page of a section.

Part	What it holds
Intro	What the entity or the market is, in a few sentences.
Pages	One card per page in the section.

Stablecoins ▸ Overview

Every stablecoin: supply, holders, transfers and off-peg, across every chain.

Projects ▸ Overview

Protocols, the apps they run, and financial metrics at every level.

EVM ecosystem ▸ Overview

Standardized blocks, transactions, logs and traces for every EVM chain.

The dimension tables of a section.

Part	What it holds
Intro	What the tables describe; with several tables, one bullet per table with its grain.
Columns	Every column, its type and one line on what it holds. With several tables this is Tables: one tab per table, each with its own column table.
Sample queries	One tab per question, each opening with a bold sentence saying what the query answers.

Assets ▸ Registry

Asset names, where each is issued, and what each one tracks.

Projects ▸ Registry

Project and app names, market sectors, and who runs what.

Lending ▸ Registry

Every lending market: one asset inside one lending pool.

One fact table, named by its event: Transfers, Trades, Deposits.

Part	What it holds
Intro	What the table records and what one row stands for: “one row per transfer”.
Columns	Every column, its type and one line on what it holds.
Sample queries	A yellow box naming the timestamp column to bound, then one tab per question.
Notes	Caveats: what the table does not hold, or a rule that is easy to get wrong.

Tokens ▸ Transfers

Every fungible token transfer.

Bridges ▸ Transfers

Cross-chain bridge transfers, with the sending and arriving sides matched.

Perpetuals ▸ Trades

Individual perpetual and order-book trades.

The metrics tables of a section.

Part	What it holds
Intro	What is measured, and the dataset behind each level with the grain of its rows.
Tables	One tab per level. Each tab lists that level’s tables with the value column each one carries.
Sample queries	One tab per question, each bounded on `timestamp`.
Notes	Caveats: which measures do not add up, and what an empty cell means.

Assets ▸ Metrics

Daily asset tables: supply, holders, transfers, price, yield and the gap from peg.

Projects ▸ Metrics

TVL, Fees, Revenue, Token incentives, Active users and sector-specific volume at every level.

DEX ▸ Metrics

Daily volume, TVL, fees and flash-loan volume per pool and per pair.

The functions of a section.

Part	What it holds
Intro	What the functions compute and from which table.
Functions	One tab per function: its parameters, what it returns, and what the result means.
Sample queries	One tab per question, each calling a function in place of a table.
Notes	Caveats: cost, and what a missing row means.

Tokens ▸ Balances

Holder balances on any past date, computed at query time.

Stablecoins ▸ Balances

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

A market’s page over a table another section owns.

Part	What it holds
Intro	The filter that selects the market, and the pointer to the owning page: “Every column is documented at …”.
Sample queries	One tab per question, with the filter applied.
Notes	Caveats specific to the market.

Stablecoins ▸ Transfers

Every stablecoin transfer.

Stablecoins ▸ Metrics

Daily supply, holders, transfers and off-peg, per stablecoin and per deployment.

Tokenized assets ▸ Metrics

Daily tokenized asset supply, holders, transfer activity and price.

The first page of a chain section.

Part	What it holds
Intro	What the catalog holds for the chain and the dataset the chain’s own record sits in.
Layers	One row per layer with data on the chain, with the date the layer starts.
Filtering	The `chain_id` filter that selects the chain in every catalog table, with one query.

Ethereum ▸ Overview

Everything the catalog holds for Ethereum, from raw blocks to project activity.

Base ▸ Overview

Everything the catalog holds for Base, from raw blocks to project activity.

Solana

Standardized Solana blocks, transactions, instructions, account activity and rewards.

One layer on one chain: a worked view of that layer with the chain filter applied.

Part	What it holds
Intro	What the layer holds on this chain, and the pointer to the page that owns the columns.
Tables	On the Raw page only: the chain’s own tables, one line each.
Sample queries	One tab per question, with `chain_id` fixed.
Notes	Caveats specific to the chain.

Ethereum ▸ Raw

The standardized Ethereum blocks, transactions, logs and internal calls.

Ethereum ▸ DEX

Ethereum trading pools, their daily volume, value locked and fees.

Base ▸ Stablecoins

Every stablecoin issued on Base: supply, holders and transfers.

One page per family for the chains that have stopped, in place of a section each.

Part	What it holds
Intro	The tables the family carries, and that the record has ended, so both dates are final.
Chain tabs	One tab per chain, holding a row per raw table with the earliest and latest month it covers.

Archived chains ▸ EVM ecosystem

The archived EVM chains, and the months each raw table covers.

Archived chains ▸ Substrate ecosystem

The archived Substrate chains, and the months each raw table covers.

Marks

Mark	Meaning
In progress	A `Soon` tag beside a page title, a banner at the top of a page, or bold text on a card. The table is documented ahead of serving: the page is its spec, and the table lands behind it.
Since	A date in a chain page’s Layers table: the earliest day that layer holds for the chain.
Warning box	The table is large and split by day. The box names the column to bound. A query with no bound reads the whole table, and the whole table is billed to you.
Your BQ Project ID	The field at the right end of the top bar. Write your project id there and the browser keeps it. Every sample query on every page rewrites itself to run in your project.

Identifiers

Simple identifiers are lowercase names. Combined identifiers join their parts with dashes.

Identifier	Shape	Example
`chain_id`	Chain name	`ethereum`
`asset_id`	Asset name	`usdc`
`project_id`	Project name	`uniswap`
`app_id`	Project name and version	`uniswap-v3`
`token_id`	`{token_address}-{chain_id}`	`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48-ethereum`
`asset_token_id`	`{asset_id}-{token_address}-{chain_id}`	`usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48-ethereum`

An asset is one identity across chains and a token is one contract on one chain: USDC is one row in dimensions.assets and one row per chain in dimensions.asset_tokens. EVM addresses are stored lowercase: wrap an address copied from a block explorer in lower() before matching it. Solana addresses are base58 and case-sensitive: stored and matched verbatim. Accounts covers the address rules.

Numbers

An empty cell is not zero. It means no figure exists for that measure, for that thing, on that day.
Units live in the metric definition. dimensions.metrics names the unit of every measure: usd, count, ratio or pct. Ratios are fractions: an apy of 0.05 is five percent, and an off_peg of -0.02 is two percent below peg.
Every measure is additive, semi-additive or non-additive.
- Additive: flows, such as Fees or Trading volume. They add up across days and across things: a week is seven days added together, a project is its apps added together.
- Semi-additive: balances, such as TVL or Supply. They add up across things but not across days: a week’s figure is the last day’s.
- Non-additive: rates and counts of distinct addresses, such as APY or Active users. They add up neither way.
Metric definitions holds the class and the rule for every measure.
A long table holds one row per measure. Most tables give each measure its own column, one row per thing per day. Financial statements instead carries a metric_id column and a value column, so one statement is a set of rows rather than one row. Filter to the line items you want, or pivot them onto one row with max(if(metric_id = ...)).

Running a query

Get the share

The catalog arrives in your own Google Cloud project as a BigQuery share, and compute is billed to you. Contact us to arrange it.

Write your project id

Type your BigQuery project id into the field at the right end of the top bar. Every sample query on every page carries it.

Copy a sample query

Open the page for the table, pick the tab whose bold sentence matches your question, and copy the query.

Run it in BigQuery

Paste the query into the BigQuery console and run it. Keep the date bound the query came with, and widen it once the result looks right.

​Organization

​Dataset types

Assets ▸ Registry

Projects ▸ Registry

DEX ▸ Registry

Tokens ▸ Transfers

Bridges ▸ Transfers

Perpetuals ▸ Trades

Assets ▸ Metrics

Projects ▸ Metrics

Tokens ▸ Prices

Core datasets ▸ Financial statements

Tokens ▸ Balances

Stablecoins ▸ Balances

Ethereum ▸ Raw

Base ▸ Raw

Solana

​Table names

​Page kinds

Stablecoins ▸ Overview

Projects ▸ Overview

EVM ecosystem ▸ Overview

Assets ▸ Registry

Projects ▸ Registry

Lending ▸ Registry

Tokens ▸ Transfers

Bridges ▸ Transfers

Perpetuals ▸ Trades

Assets ▸ Metrics

Projects ▸ Metrics

DEX ▸ Metrics

Tokens ▸ Balances

Stablecoins ▸ Balances

Stablecoins ▸ Transfers

Stablecoins ▸ Metrics

Tokenized assets ▸ Metrics

Ethereum ▸ Overview

Base ▸ Overview

Solana

Ethereum ▸ Raw

Ethereum ▸ DEX

Base ▸ Stablecoins

Archived chains ▸ EVM ecosystem

Archived chains ▸ Substrate ecosystem

​Marks

​Identifiers

​Numbers

​Running a query

Organization

Dataset types

Table names

Page kinds

Marks

Identifiers

Numbers

Running a query