Tokens & prices

Tokens

Token list for a chain: the tokens we list first, then everything the indexer knows, ranked by pool count so the deepest match comes first. Search matches symbol, name or address. This is how you turn a ticker a user typed into an address you can quote.

One ordered sequence, sliced by offset. limit defaults to 60 and caps at 200. data.hasMore and data.nextOffset tell you whether to ask again. Page until hasMore is false rather than until a page comes back short. A page can be short and still not be the last one; an empty page is always the last one, and a limit below 1 is read as 1, so the loop always makes progress.

Price

The USD price is derived from our own pool index and reflects real depth, rather than being relayed from a third-party mid-market feed. Use the batch form for a portfolio view. Fifty tokens in one call costs one call against your quota; fifty separate calls cost fifty.

Every answer names its origin. source is index when the figure comes from our own pools, which is every token our index can price. Where it cannot, a cached figure from GeckoTerminal fills the gap with source: "external" and a fetchedAt timestamp in Unix seconds, so you always know which kind of number you are holding. An external figure is never served for a token our index prices.

{
  "success": true,
  "data": { "usd": 3421.87, "source": "index", "fetchedAt": null, "stale": false }
}

A token nobody can price answers usd: null. Earlier deployments answered usd: 0.0 there; the change is deliberate, because zero reads as “worthless” and poisons any arithmetic done on it, while null says what is true. If your integration compared usd against zero, it already handles null through the same falsy check; if it does arithmetic on usd, guard for null first. A cold external miss also answers null and queues a background fetch, so a retry moments later usually succeeds.

The batch form returns data.prices exactly as before, values as plain numbers, plus parallel data.sources and data.fetchedAt maps keyed the same way. Tokens the oracle cannot price now also appear when a fresh external figure exists; tokens with neither remain omitted, which still means “we don't know” rather than “worth nothing”.

On both forms, stale describes our own index. It is the same per-chain freshness predicate that gates /v1/build, so it applies to entries whose source is index. An external figure is not subject to that gate; its own age is its fetchedAt. On the batch form the flag is chain-level, so exempt the external entries yourself when applying it per token.

Both forms also carry change24h, the token's move over the last 24 hours, as a RATIO (0.023 is +2.3%), not a percentage. It is null wherever we have no price from 24 hours ago to compare against, which today is most tokens while the history fills in. Null means unknown: render a dash, never a zero, and never assume a missing value means the price held steady.

A literal 0.0 is a measured answer, and one class of tokens produces it every day: the USD stablecoins the index prices everything else from, USDC, USDT and the other stable hubs. They are the anchor, one dollar by definition with no pool state behind the figure (their asOfBlock is null), so the current price and the 24-hour-ago sample are both exactly 1.0 and the ratio is exactly zero. That is neither a rounding artifact nor a missing sample: a stablecoin's wobble around its peg is not something this index measures.

{
  "success": true,
  "data": { "usd": 3421.87, "change24h": null, "source": "index", "stale": false }
}