Responses

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
`meta.coverage_from`	Present only when the requested window ends before recorded coverage for the symbol; ISO 8601 start of coverage
`meta.notice`	Present alongside `meta.coverage_from`; explains the empty result and points to `/v1/symbols` for per-symbol dates

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. Before treating that as “no market activity,” check meta for coverage annotations. The two empty states mean different things, and clients and coding agents that skip this check misread pre-coverage windows as quiet markets.

Empty `data` plus	Meaning	Next call
`meta.coverage_from` and `meta.notice` present	The requested window ends before recorded coverage for that symbol begins, so there is no data to fetch in that window	Move the window to `meta.coverage_from` or later; check `/v1/symbols` for per-symbol coverage dates
No coverage annotations	No pre-coverage condition was detected. Usually a quiet market inside coverage; a window past the end of a symbol’s coverage, such as a delisted or settled market, returns the same plain envelope	Confirm the window against `/v1/symbols` coverage dates before recording a quiet market, then continue, widen, or record as-is

A request to /v1/hyperliquid/trades/{symbol} for a window that ends before the symbol’s coverage starts returns:

{
  "success": true,
  "data": [],
  "meta": {
    "count": 0,
    "request_id": "d9c8c1ca-a583-471e-9efa-a4fcd03d7777",
    "coverage_from": "2024-12-05T00:00:00Z",
    "notice": "No data in the requested range. Hyperliquid trades coverage for HYPE begins 2024-12-05 (UTC); the requested window ends before coverage starts. See /v1/symbols for per-symbol coverage dates."
  }
}

meta.coverage_from is the ISO 8601 start of recorded coverage for the requested symbol and data type. meta.notice is a human-readable explanation of why the page is empty. These fields appear on trades, candles, order book history, funding, open interest, and liquidation range queries across venues when the requested window ends after the venue family’s earliest recorded date for that data type but before the symbol’s own coverage begins. Windows that end before the venue family’s earliest recorded date return a 400 range error instead, and quiet windows inside coverage return the plain envelope without annotations. Do not turn an empty page into synthetic rows in either state. Store the route, query parameters, meta.count, meta.next_cursor, meta.request_id, and any coverage annotations, then decide whether the downstream job should move the window, 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 with meta.coverage_from and meta.notice means the requested window ends before coverage for that symbol begins; move the window forward and check /v1/symbols. An empty array without those fields means no pre-coverage condition was detected: usually a quiet page inside coverage, though a window past the end of a symbol’s coverage returns the same plain envelope, so confirm the window against /v1/symbols coverage dates before recording a quiet market. Do not fabricate rows in either state. A null or missing field means “not available for this record,” not zero. A coverage gap inside covered history 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. Check meta.coverage_from and meta.notice first: present means the window predates coverage; absent usually means a quiet market, though windows past the end of a symbol’s coverage also return the plain envelope, so confirm coverage dates via /v1/symbols.

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.

Requests

Reliability

Responses

Success Envelope

Response Handling Checklist

Error Envelope

Empty Success Responses

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

​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

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