Responses - 0xArchive

Response parsing should preserve the payload and the meta context that makes it usable later. Use Example responses for schema-backed payload examples, Schemas for shared field notes, and OpenAPI for endpoint-specific generated schemas. Most market-data routes return a JSON envelope with success, data, and meta. Some auth, system, wallet, and data-quality routes have resource-specific bodies; use the REST reference and response headers for the exact response shape of a specific endpoint.

Success Envelope

{
  "success": true,
  "data": [],
  "meta": {
    "count": 100,
    "next_cursor": "1704067200123_456789",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Field	Client behavior
`success`	Treat `false` as an application-level failure even when a JSON body exists
`data`	Parse according to the endpoint-specific schema
`meta.count`	Use for returned item count, not necessarily total available records
`meta.next_cursor`	Use for pagination when present
`meta.request_id`	Log on success and failure for debugging and support

Response Handling Checklist

Use this checklist before a client, agent, or parser stores response data.

Step	Required handling
HTTP status	Decide retry, auth repair, fail-fast behavior, or support escalation from the status class.
`success`	Treat `success: false` as an application failure even when the HTTP response contains JSON.
`data`	Parse from the endpoint-specific OpenAPI schema, not from a nearby example.
`meta.request_id`	Store request IDs for successes, failed attempts, and paginated pages; for resource-specific auth, system, wallet, or data-quality bodies, store any request ID the route, response header, or client exposes.
`meta.next_cursor`	Keep cursor, route, symbol, query parameters, and request ID together for resumable jobs.
Venue context	Persist venue family and symbol style beside records so joins do not mix Hyperliquid core, Spot, HIP-3, HIP-4, and Lighter.
Decimal fields	Keep numeric-looking market fields decimal-safe until the application boundary.

Error Envelope

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Treat HTTP status as the control signal and the JSON body as debugging context. Validation, auth, route, plan-gate, rate-limit, and upstream errors require different client behavior. Use Errors for the retry model.

Empty Success Responses

Some historical requests return success: true with an empty data array. That can be a valid page for the requested symbol, route, cursor, or time window. Do not turn an empty page into synthetic rows. Store the route, query parameters, meta.count, meta.next_cursor, meta.request_id, and data-quality state, then decide whether the downstream job should continue, narrow the window, or mark the output incomplete.

Pagination

Historical routes can include meta.next_cursor. Keep request IDs per page, not just for the final result. A resumable job should store route family, route path, symbol, query parameters, cursor, request ID, output file, and data-quality decision. Do not widen pagination loops until a one-page request confirms the route family, response shape, and freshness gate.

Field dictionary

What the common fields mean, and the handling that keeps a backtest honest.

Numbers and decimals

Types are not uniform across routes, so check the route before you bind a model.

Where	Type	Handling
L2 order book `px`, `sz`	decimal strings	Keep as strings; convert at the app edge with a decimal library.
L4 order `price`, `size`	numbers	Already numeric in the payload.
funding rate, spread, open interest, mark/oracle price, liquidation value	decimal strings	Decimal-safe; do not parse as floats when precision matters.

Timestamps

There are two clocks. Log both when you store a record.

Field	Meaning
`timestamp`	Event time, when the data was that state at the venue.
`checkpoint_timestamp`	(L4) the instant the reconstructed book is current to.
`measured_at`, `last_updated`	(data-quality / freshness) when 0xArchive last measured the data (ingest/measure time, not event time).

Order-book fields

Field	Where	Meaning
`px`, `sz`, `n`	L2	Price, size, and the number of orders resting at that level.
`oid`	L3 / L4	Exchange order ID, the stable handle for one order across diffs and history.
`user_address`	L3 / L4 / trades	Wallet that placed the order or fill.
`side`	books / trades	Venue-native side code: `B` = bid/buy, `A` = ask/sell.
`diffs_applied`, `last_block_number`	L4	Reconstruction metadata: diffs rolled onto the checkpoint, and the chain block it is current to.

Trade and liquidation fields

Field	Meaning
`trade_id`	Venue trade/fill ID.
`cloid`	Client order ID, when the placer set one.
`closed_pnl`	Realized PnL on a closing fill.
`direction`	Human label such as `Open Long` or `Close Long`.
`fee`, `fee_token`	Fee paid and its token; a negative `fee` is a maker rebate.
`liquidated_user`, `liquidator_user`	On liquidations, the liquidated wallet and the liquidator.

IDs to keep

Store meta.request_id (or the x-request-id header) for support. Keep oid, trade_id, and cloid to join order lifecycle across snapshots, diffs, and fills.

Probability, not price

HIP-4 mark_price and mid_price are implied probabilities in [0, 1], not USD. Spot symbols are pairs, and HIP-3 symbols can carry a builder prefix. Keep the venue family with every record so a later join stays inside one family.

Empty, null, and gap are different

An empty data array on success: true is a valid empty page, so do not fabricate rows. A null or missing field means “not available for this record,” not zero. A coverage gap is a third thing: confirm it against the data-quality coverage route rather than inferring it from an empty page.

Data-Quality Responses

Data-quality routes answer whether a downstream job should trust a market-data result. A degraded status, incident, latency issue, or coverage gap does not always mean every route is unusable. It means the client must compare the state to the job tolerance and record that decision. For backtests, alerts, exports, dashboards, and model features, store both the quality response and the downstream data request ID. Coverage routes such as /v1/data-quality/coverage/{exchange}/{symbol} can return resource-specific bodies without success, data, or meta; parse those from the REST reference instead of forcing the market-data envelope onto them.

Export Responses

Data Catalog exports return files and dashboard job state, not ordinary market-data JSON. Preserve the selected market, schema keys, UTC range, estimated size, credits, checkout state, delivery state, and data-rights decision with the export record. If the workflow needs programmatic market data, use REST, WebSocket, SDKs, CLI, MCP Server, or OpenAPI-backed routes.

Parser Checklist

Check HTTP status

Decide retry, fail-fast, auth repair, or support escalation from the status class.

Check body success

Handle success: false as an application error and preserve error.code.

Handle empty pages

Treat success: true plus empty data as a state to record, not as permission to fabricate records.

Log request ID

Store meta.request_id for envelope responses. For resource-specific bodies, store x-request-id or the client wrapper’s request handle when available.

Use the route schema

Parse data from the endpoint-specific OpenAPI schema, not from a nearby example.

Keep venue context

Persist venue family and symbol style beside records so downstream joins do not mix families.

Next Step

Use Example responses for payload examples, Schemas for field categories, and Examples for copyable parser patterns.

​Success Envelope

​Response Handling Checklist

​Error Envelope

​Empty Success Responses

​Pagination

​Field dictionary

​Numbers and decimals

​Timestamps

​Order-book fields

​Trade and liquidation fields

​IDs to keep

​Probability, not price

​Empty, null, and gap are different

​Data-Quality Responses

​Export Responses

​Parser Checklist

​Next Step