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
  }
}

meta field	Meaning
block	The latest L2 block the data reflects
block_ts	That block’s timestamp (unix ms)
block_age_ms	How old that block is
lag_ms	How long ago our index applied it
safe_block	Latest block whose batch is posted to Ethereum
finalized_block	Latest block finalized on Ethereum
next_cursor	On paginated lists: pass it as ?cursor= for the next page

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.

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:

Level	Meaning
latest	Confirmed by the Robinhood Chain sequencer (sub-second)
safe	Its batch has been posted to Ethereum
finalized	Finalized on Ethereum

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.