Tokenflow API
The Tokenflow platform indexes on-chain activity for the protocols it serves: token movements, swaps, liquidity pools, prices and holder statistics. This API is how a program reads that data from outside the Tokenflow dashboard.
It is shaped like the data, not like the screens. Every resource is a list you filter and page through with the same conventions, so a client written against one resource already knows how to read the next one.
What this API is for
- Wallets, funds, market makers and bots that need protocol data on their own schedule.
- AI agents that query token and holder data as a tool.
- The Tokenflow embeddable widget, which is built on these same endpoints.
What you can read
- Discover
GET /v1/protocols— List protocolsGET /v1/tokens— List tokensGET /v1/networks— List networks
- Market data
GET /v1/prices— List price observationsGET /v1/candles— List price candlesGET /v1/holder-snapshots— List daily holder statistics
- On-chain activity
GET /v1/transfers— List token movementsGET /v1/pools— List liquidity poolsGET /v1/swaps— List swaps through a poolGET /v1/daily-metrics— List a pool's daily metricsGET /v1/wallets— List tracked walletsGET /v1/balances— List a wallet's token balances
- Key management
GET /v1/me— Identify the calling keyGET /v1/me/origins— List the calling key's browser originsPUT /v1/me/origins— Replace the calling key's browser origins
Every operation, with its parameters and a console to try it, is in the API reference.
Who can read what
- Discovery and market data — the protocol catalogue, prices, candles and holder statistics — are readable by any key.
- On-chain activity — movements, pools, swaps, wallets and balances — belongs to a protocol:
- a key issued for a protocol reads that protocol in full, including the names and labels its team gave its wallets;
- any key reads what a protocol publishes on its public page in the Tokenflow dashboard — the same data, at the same level of detail. A protocol can publish its liquidity but not its holders, or its holders without its own labels, and the API follows that choice exactly.
- A protocol that publishes nothing is refused with
PROTOCOL_NOT_PUBLIC, exactly as if it did not exist./v1/protocolslists the ones you can read.
Tenant-private data is never served to anyone outside the protocol it belongs to.
Plans and limits
Every call is counted against the account that owns the key — the protocol for a protocol key, you for a personal key — so all of a protocol's keys share one allowance.
- What a call costs. Plain rows (catalogue, prices, candles, transfers, swaps, wallets, balances) cost 1 credit. Computed views — holder snapshots, pools and daily pool metrics — cost 5.
/v1/meis free. - Only successful calls count. A request that ends in an error costs nothing.
- Running out. On the free plan, a request past the monthly allowance is refused with
INSUFFICIENT_CREDITS(HTTP 402) until the next calendar month (UTC) or until you move to a paid plan; the error'sdetailssay which plan you are on and where to upgrade. Paid plans never stop at the allowance: extra usage is billed on the next invoice. - Requests per minute. Each plan has a per-minute ceiling. Past it you get
RATE_LIMITED(HTTP 429) with aRetry-Afterheader telling you how many seconds to wait.
Where to start
- Getting started — issue a key and make a first call.
- Authentication — how the
x-api-keyheader works, and browser origins. - Conventions — pagination, time windows and amounts.
- Errors — every error code and what to do about it.