# Responses & conventions

> The Crius API response envelope, meta block, number and amount formats, timestamps, addresses, pagination, finality levels and liquidity and market-cap definitions.

Source: https://crius.sh/docs/conventions/

## The envelope

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

```json
{
  "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](https://crius.sh/docs/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](https://crius.sh/docs/concepts/finality/).

## 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.