Overview
API v2 adds community token lists, risk-aware search and resolve, and chain-native multichain assets on the same host and key as v1.
API v2 is additive: every v1 endpoint keeps working unchanged. v2 covers three things:
- Token lists — named, ordered sets of Solana mints with an accountable curator. Read ours, publish your own, and compose the lists you trust into one corpus.
- Risk-aware search and resolve — a judgment pipeline over the long tail of Solana tokens that ranks, warns and suppresses by a policy you can tune, and explains every decision.
- Multichain assets — the curated assets you know from v1, with their tokens on Solana and
the EVM chains, addressed by
<chain>:<address>.
The base URL is https://api.tokens.xyz/v2. Every v2 endpoint takes the same x-api-key header
as v1 and needs only the default assets:read scope; see Authentication.
Start with the Quickstart for one working call per family.
Token lists
A list is a plugin: consuming apps name the lists they trust and compose them with
GET /v2/lists/tokens. There is deliberately no global "all lists" union, because trust in a
curator is the whole model. Any API key can create lists; the creating key's project owns them.
Lists may include mints outside the curated registry — those tokens carry verified: false so
your UI can show caution.
Read Token lists for the model and Lists for the reference.
Risk-aware search and resolve
GET /v2/search merges candidates from a live market-data provider, the token index and the
curated registry, then runs them through hard gates, a weighted score and explanations. You pick
a policy (strict, default, degen) and can override individual gates. Whatever a gate removes
comes back in suppressed[] with the gate that fired, so nothing is silently hidden.
GET /v2/resolve answers "which mint is USDC?" with one confident result, or refuses
explicitly (ambiguous, no_confident_match) rather than guessing.
Read Risk-aware search for policies and codes and Search & Resolve for the reference.
Multichain assets
The asset surface has two nouns. An asset is the curated, chain-agnostic thing (usd,
bitcoin, tesla). A variant is one token on one chain that represents it, identified by
exactly one key, <chain>:<address>. Every number on an asset is computed over all of its chains
by default; chain= narrows what is listed, never what is summed. GET /v2/chains publishes a
capability flag set per chain so you gate features on the flags, not on chain === 'solana'.
v2 returns only curated assets. An address-shaped {assetId} is 400 invalid_asset_id, and a
token the registry does not know is 404 variant_not_found (or missing[] in a batch). The same
is true of v1: an unregistered Solana mint is 404 with details.code: "asset_not_registered".
For the long tail of unregistered Solana tokens use Token lists or
GET /v2/search.
Read Multichain assets for the rules and Migrating from v1 for the endpoint and field maps.
Route index
| Family | Routes | Reference |
|---|---|---|
| Chains | GET /v2/chains | Chains |
| Assets | GET /v2/assets, GET /v2/assets/{assetId}, GET /v2/assets/{assetId}/variants | Assets |
| Variants | GET /v2/variants/{chain}/{address}, GET /v2/variants?keys= | Variants |
| Search | GET /v2/search, GET /v2/resolve | Search & Resolve |
| Lists: read | GET /v2/lists, GET /v2/lists/{slug}, GET /v2/lists/tokens | Lists |
| Lists: manage | GET /v2/lists/check-slug, POST /v2/lists, PATCH /v2/lists/{slug}, DELETE /v2/lists/{slug}, POST /v2/lists/{slug}/members, PUT /v2/lists/{slug}/members/{mint}, DELETE /v2/lists/{slug}/members/{mint} | Lists → Managing lists |
| Lists: curator search | GET /v2/lists/search-tokens | Lists |
| Registry | GET /v2/registry, GET /v2/registry/{mint} | Registry |
The Solana Foundation's asset registry is served under the /v2 prefix but documented in its own
section: see Registry.
Which API should I use?
- You need Solana market data, OHLCV, risk, DEX markets or swap routing for a registered asset: stay on v1. Those features have not moved to v2.
- You need an asset's tokens on more than one chain, or you address tokens by
<chain>:<address>: use the v2 asset and variant routes. - You need tokens that are not in the curated registry: use lists when a curator you trust publishes them, and search when you need to find them by symbol, name or mint.
- You are building a token picker or a swap input: start with
GET /v2/resolveand fall back to search when it isambiguous.