Responses & conventions

The envelope

Every successful response is a JSON object with data and meta:

{
  "data": { "symbol": "WETH", "usd": 2381.97 },
  "meta": {
    "chain": "robinhood",
    "block": 95503718,
    "block_ts": 1792712926000,
    "block_age_ms": 1050,
    "lag_ms": 37,
    "safe_block": 95497061,
    "finalized_block": 95493649
  }
}

Errors use {"error": {"code": "…", "message": "…"}} with a matching HTTP status. See Errors.

Numbers and amounts

• USD values, prices and ratios are JSON numbers, always in plain decimal notation (0.00000576413, never 5.76e-6), rounded to 6 significant digits.
• Token amounts are in human units (already divided by the token’s decimals).
• Percentages are 0–100 (12.5 means 12.5%).
• liquidity_usd is 2 × the quote side of a pool (the convention DEX screeners use). quote_liquidity_usd is the real quote amount sellers could withdraw. For bonding curves only the real quote raised counts.
• market_cap_usd = price × (total supply − tokens burned at 0x0 or 0x…dEaD), with unsold bonding-curve tokens included. fdv_usd = price × total supply.

Time

• Every *_ts field is unix milliseconds (UTC).
• Stats windows: 1s, 30s, 1m, 5m, 1h, 4h, 6h, 24h, plus all_time totals.
• Candle intervals: 1s, 30s, 1m, 5m, 15m, 1h, 4h, 6h, 1d.
• Robinhood Chain produces a block roughly every 100 ms. Inside contracts, block.number is the Ethereum L1 block (about 12 s), which is why per-block contract rules (anti-snipe, sell throttles) act on L1 blocks; responses expose both block and l1_block where it matters.

Addresses

Addresses are accepted in any case and always returned lowercase. Native ETH is 0x0000000000000000000000000000000000000000 with symbol ETH. Uniswap v4 pools are identified by their 32-byte pool id.

Token logo and links

A token’s logo and links have one shape on every endpoint. They come from the token’s own metadata first (its launch, its on-chain metadata URI, its verified source), with its DexScreener profile filling any gaps.

• The token profile (/token/{address}) has the full object in metadata:

"metadata": {
  "logo": "https://…/logo.png",
  "banner": "https://…/header.png",
  "description": "…",
  "links": { "website": "https://…", "twitter": "https://x.com/…", "telegram": null, "discord": null, "farcaster": null, "github": null },
  "sources": { "logo": "metadata_uri", "links": "launch" }
}

• Lists and search (/tokens, /search) carry the same logo and links on each row.
• Any token inside another object (pool sides, trades, wallet holdings, launch pairs, liquidity events, prices, WebSocket trades) carries the same logo next to its address and symbol.

links always has all six keys, null when unknown, so you can read links.twitter without checking the shape. metadata.socials (one {url, source} object per platform) and dexscreener.profile remain for existing integrations; new code should read metadata.logo and metadata.links.

Pagination

Lists take limit (each endpoint documents its maximum, usually 500) and return meta.next_cursor when there is more. Pass it back as cursor; cursors are opaque and stable.

Finality

Every event (trade, transfer, liquidity change) carries a finality level:

Most apps can use latest. If you need settled data only, filter by finality where an endpoint supports it, or subscribe to the stream with "finality": "safe". See Finality & reorgs.

History

Fields marked history: "partial" or since_index_start cover data from when our index started for that item; they become complete once the history backfill reaches it. Profiles show history: "complete" once everything is indexed.