Skip to main content

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 protocols
    • GET /v1/tokens — List tokens
    • GET /v1/networks — List networks
  • Market data
    • GET /v1/prices — List price observations
    • GET /v1/candles — List price candles
    • GET /v1/holder-snapshots — List daily holder statistics
  • On-chain activity
    • GET /v1/transfers — List token movements
    • GET /v1/pools — List liquidity pools
    • GET /v1/swaps — List swaps through a pool
    • GET /v1/daily-metrics — List a pool's daily metrics
    • GET /v1/wallets — List tracked wallets
    • GET /v1/balances — List a wallet's token balances
  • Key management
    • GET /v1/me — Identify the calling key
    • GET /v1/me/origins — List the calling key's browser origins
    • PUT /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/protocols lists 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/me is 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's details say 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 a Retry-After header telling you how many seconds to wait.

Where to start​

  1. Getting started — issue a key and make a first call.
  2. Authentication — how the x-api-key header works, and browser origins.
  3. Conventions — pagination, time windows and amounts.
  4. Errors — every error code and what to do about it.