Reader'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 three ways.

Band	What it is
Core entities	The model of the system and the actors in it: Projects, Chains, Assets, Tokens and Accounts. Every table in the catalog is keyed to one or more of these. A project runs apps on chains and issues assets; an asset is deployed as tokens; tokens move between accounts. Each entity section holds the registry of those actors, the events they take part in, and their daily numbers.
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 datasets, and the dataset 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.token_transfers is every token transfer, facts.bridge_transfers every cross-chain transfer, facts.lending_market_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. A metric table is one row per thing per period, with that thing’s measures for the period: daily for most tables, hourly for prices. metrics.assets_daily is every asset on every day with supply, holders, transfer volume and price; metrics.tokens_prices_hourly is every token’s price every hour. 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 four levels.

Tokens ▸ Prices

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

In progress. Screeners are not served yet. Stay tuned!

Screeners are rankings. A screener is a stock screener over the catalog: every thing of one kind in one table, with its current level and its change over the last day, week and month, ready to filter and rank. screeners.dex_pools is every live trading pool with its TVL now and its volume and fees over 1, 7 and 30 days. A screener reads the last month of the daily metrics and stores the result, so ranking thousands of pools is one small read. It holds no history; the metrics table beneath it does.

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 five. 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. The table part is built from the same words in every dataset: the things it holds, plural, and for facts and metrics what about them. Things are plural in a table name and singular in the identifier column that joins them: facts.lending_market_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.<thing>_<events>: the thing the event happens to, then the event, plural. One row per event. The thing’s identifier column joins its dimension.

Table	Thing	Event	Reads as
`facts.token_transfers`	Token	Transfer	Transfers of tokens, one row per transfer.
`facts.token_balance_changes`	Token	Balance change	Balance changes of tokens, two rows per transfer: one per side.
`facts.bridge_transfers`	Bridge	Transfer	Transfers across bridges, one row per cross-chain transfer with both legs paired.
`facts.lending_market_deposits`	Lending market	Deposit	Deposits into lending markets, one row per deposit.
`facts.perp_trades`	Perp market	Trade	Trades on perpetual markets, one row per leg of a fill.

metrics.<things>_<measure>_<period>: three parts, in order. The level names the things, plural; two things joined means one row per pair, and every level rolls up to the one above it. The measure names what is measured, and is absent when the table holds every measure for its level. The period is the row’s time step.

Table	Level	Measure	Period
`metrics.assets_daily`	One asset	Every measure	Day
`metrics.asset_tokens_daily`	One asset on one chain	Every measure	Day
`metrics.projects_daily`	One project	Every measure	Day
`metrics.projects_chains_daily`	One project on one chain	Every measure	Day
`metrics.dex_pool_pairs_daily`	One pool, one traded pair	Every measure	Day
`metrics.tokens_prices_daily`	One token	Price	Day
`metrics.tokens_prices_hourly`	One token	Price	Hour

screeners.<things>: the things, plural, same word as their dimension and their metrics table. One row per thing as it stands now. In progress.

Table	Reads as
`screeners.dex_pools`	The ranking of DEX pools: TVL now, volume and fees over 1, 7 and 30 days.
`screeners.perp_markets`	The ranking of perpetual markets.
`screeners.lending_markets`	The ranking of lending markets.

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 eight kinds. 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 four levels.

Chain verticals ▸ Overview

Everything the catalog holds for one chain, family by family.

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, one bullet per table with its level and period.
Tables	One tab per level, each with its own column table. Projects ▸ Metrics adds Measures before it: one tab per measure family.
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 four levels.

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.

Marks

Mark	Meaning
In progress	A 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 there is no table to query until it lands.
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.

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

Tokens ▸ Balances

Stablecoins ▸ Balances

Ethereum ▸ Raw

Base ▸ Raw

Solana

​Table names

​Page kinds

Stablecoins ▸ Overview

Projects ▸ Overview

Chain verticals ▸ 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

​Marks

​Identifiers

​Numbers

​Running a query

Organization

Dataset types

Table names

Page kinds

Marks

Identifiers

Numbers

Running a query