API conventions

Use the REST envelope and pagination rules below for market-data reads. WebSocket messages use their channel schemas, with the versioning and error codes described on this page. Changes to this contract are additive. Existing fields, types, and status codes keep working for existing clients. The few changes that cannot be additive are opt-in through a dated version, described under Versioning.

Response envelope

The shared REST response envelope has three keys:

{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "side": "B",
      "price": "82782",
      "size": "0.00025",
      "timestamp": "2026-09-28T14:55:17.295Z"
    }
  ],
  "meta": {
    "count": 1,
    "has_more": true,
    "next_cursor": "1790607317295_494699715524397",
    "symbol": "BTC",
    "venue": "hyperliquid",
    "request_id": "ea17ef99-bca1-4d06-9461-0e920e66a2c8"
  }
}

data is the payload: an array for lists and history, an object for a single snapshot. meta describes the response. Records are not required to repeat the symbol or venue, so read both from meta.

`meta` field	When present	Meaning
`request_id`	Every enveloped response	Identifier for this request. Log it with every page and quote it to support
`count`	List payloads	Number of records in this response, not the total available
`has_more`	Cursor-paged routes	`true` when another page exists. See Pagination
`next_cursor`	Exactly when `has_more` is `true`	Opaque string to send back as `cursor`
`symbol`	Per-symbol routes	The canonical public symbol for the venue, for example `BTC`, `km:US500`, `#0`, or `HYPE-USDC`
`venue`	Per-symbol routes	One of `hyperliquid`, `hip3`, `hip4`, `spot`, `lighter`, `rh-lighter`
`coverage_from`, `notice`	Empty responses whose window ends before the symbol’s coverage	Where coverage starts and why the page is empty. See Coverage signals
`finalized_through`	Lighter and Lighter on Robinhood Chain trades	The latest finalized trade time. History is canonical up to this point
`requested_end`, `clamped_to`	Lighter trade history when `end` is later than `finalized_through`	The `end` you sent and the finalized time the range was clamped to
`preliminary_row_count`	Lighter `/recent` trades	Rows in the response that are preliminary and not yet finalized

A few catalog and status routes (data quality, /v1/status/coverage, and /v1/symbols) return their own body shape by default, with success: true and meta.request_id added. With the version header they return the standard envelope, where data holds the body (the symbol array for /v1/symbols). Health checks use a direct response body. GET /health returns {"service":"0xarchive-api","status":"ok"}, including when the version header is sent. Its request identifier is in the X-Request-Id response header. See the health check schema.

Errors

Every error response is JSON with the same shape, including authentication failures and unknown routes:

{
  "success": false,
  "code": 400,
  "error_code": "invalid_parameter",
  "error": "Invalid side 'long'. Use buy or sell.",
  "param": "side",
  "valid_values": ["buy", "sell"],
  "request_id": "ec63b7a2-438d-4cf0-8ebf-a94d61697ff8"
}

code is the HTTP status. error_code is a stable, machine-readable name: branch on it, not on the message text. param and valid_values appear when one parameter caused the error. The full list of codes, their statuses, and what to do about each is on Errors. WebSocket error messages carry the same error_code.

Versioning

Send 0xArchive-Version: 2026-10-01 on REST requests, and version=2026-10-01 in the WebSocket connection URL, to receive the current contract. Without it, responses keep their earlier shape, so existing integrations keep working unchanged. The official SDKs, CLI, and hosted MCP send it for you.

curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=10" \
  -H "X-API-Key: $OXARCHIVE_API_KEY" \
  -H "0xArchive-Version: 2026-10-01"

wss://api.0xarchive.io/ws?version=2026-10-01

Authenticate the WebSocket as usual, with Authorization: Bearer $OXARCHIVE_API_KEY in the opening handshake; see WebSocket connection. A response shaped by the version echoes it in the 0xArchive-Version response header, and WebSocket subscribed and replay_started messages include "version": "2026-10-01". A later dated value is read as the newest version the API supports. A value that is not a supported date is ignored and the default shape is returned. Responses carry Vary: 0xArchive-Version, so caches keep the two shapes apart. What the version changes:

Area	Without the version	With `2026-10-01`
Error codes	Four earlier names: `invalid_query_params`, `invalid_path_params`, `history_window_exceeded`, `request_range_exceeded`	`invalid_parameter`, `invalid_parameter`, `historical_depth_exceeded`, `historical_range_exceeded`
A `start`, `end`, or `timestamp` that cannot be parsed	`invalid_query_params`	`invalid_time_range`
Time fields on a few payloads	Integer milliseconds in `timestamp` or `snapshot_ts`	RFC 3339 string, plus an integer `timestamp_ms` or `snapshot_ts_ms`. Applies to L4 snapshot resting orders (an unknown queue time becomes `null`), cumulative volume delta buckets, HIP-3 oracle prices and discovery bounds, Lighter and Lighter on Robinhood Chain liquidations and liquidation volume, and liquidation-level and trigger-level snapshots
Data quality, `/v1/status/coverage`, `/v1/symbols`	Route-specific body plus `success` and `meta.request_id`	Standard `{ success, data, meta }` envelope
Lighter and Lighter on Robinhood Chain WebSocket replay	Stored row shapes	The same message shapes as the live channels

We recommend sending the version on every request in new code. Pin the exact date rather than computing it, so a future version never changes your parser without a code change.

Time

Requests accept either form for start, end, timestamp, and at:

Unix milliseconds, for example 1790553600000.
RFC 3339, for example 2026-09-28T00:00:00Z or 2026-09-28T02:00:00+02:00. URL-encode + as %2B; a literal + is also accepted.

REST response times are RFC 3339 UTC strings, with milliseconds where the source has them, for example 2026-09-28T14:55:17.295Z. Integer milliseconds appear only in fields whose names end in _ms. The few payloads that still carry integer times without the version header are listed in the Versioning table. Store times in UTC and convert only for display. Point-in-time reads take timestamp. The levels routes also accept at as a synonym.

Pagination

Every cursor-paged route sets meta.has_more. meta.next_cursor is present exactly when has_more is true.

Send the first request with start, end, limit, and any filters.
While meta.has_more is true, send the same request again with cursor set to meta.next_cursor. Keep every other parameter unchanged.
Stop when meta.has_more is false.

The cursor is an opaque string. Do not parse, build, or modify it. A page can hold fewer rows than limit and still have more to come, and the last page can be empty when the previous page was exactly full. Stop on has_more, never on a short page. The maximum limit for each route family is published as page_limit in capabilities. Details and examples are on Pagination.

Parameter names

Name	Meaning
`symbol`	The market, in paths, query parameters, and `meta`. Each venue has its own symbol style: `BTC`, `HYPE-USDC`, `km:US500`, `#0`. Some routes also accept the older `coin`
`interval`	Bucket width on aggregated series such as candles, funding, open interest, cumulative volume delta, and order flow. Order flow also accepts `granularity` as an alias. On Lighter order book history, `granularity` is a different setting: the history resolution
`start`, `end`	The time window. See Time
`limit`, `cursor`	Page size and continuation. See Pagination
`side`	On every trades route, including `/recent`: `buy` or `sell`, filtered before paging, so a full page holds `limit` matching trades. Response rows keep the venue code, `B` or `A`
`triggered`	On Hyperliquid, HIP-3, and HIP-4 order history: `true` or `false`
`depth`	Price levels per side on order book snapshots and history, including full-depth L2 history. The accepted maximum depends on the route

Every documented parameter changes the result. A value outside the accepted set is rejected with 400 and names the parameter, rather than being silently ignored.

Coverage signals

Each data type has a first served row on each venue, published as available_from in capabilities. Per-symbol dates are in /v1/symbols.

A range that starts before the first row and ends after it is served from the first row. You do not need to trim start.
A range that ends before a symbol’s coverage begins returns an empty data array with meta.coverage_from and meta.notice, so an empty page is never mistaken for a quiet market.
A range that ends before a data type’s policy floor (for example Hyperliquid candles before 2025-03-01) returns 400 with error_code range_before_coverage.

{
  "success": true,
  "data": [],
  "meta": {
    "count": 0,
    "has_more": false,
    "symbol": "km:US500",
    "venue": "hip3",
    "coverage_from": "2026-01-12T00:00:00Z",
    "notice": "No data in the requested range. HIP-3 trades coverage for km:US500 begins 2026-01-12 (UTC); the requested window ends before coverage starts. See /v1/symbols for per-symbol coverage dates.",
    "request_id": "26157aa1-a118-4676-a8a0-99fee73fa049"
  }
}

Unsupported combinations and unknown routes

A route that asks a venue for a data type it does not offer, such as order flow on Hyperliquid Spot, returns 404 with error_code unsupported_for_venue. The message and the available_on list name the venues and routes that do serve it. Any other unknown path returns 404 with error_code route_not_found. Neither is ever an empty or plain-text response.

Deprecated root routes

The unprefixed routes /v1/trades/{symbol}, /v1/orderbook/{symbol}, /v1/funding/{symbol}, /v1/openinterest/{symbol}, and /v1/instruments are aliases for Hyperliquid. They keep working, and every response carries Deprecation: true and a Link header with rel="successor-version" that points at /v1/hyperliquid/. Use the venue-prefixed routes in new code. No removal date has been set.

Capabilities

GET /v1/capabilities lists what each venue serves: one row per venue and data type, with its REST routes, WebSocket channels, whether live streaming and replay are available, the first served time, the cadence, the page limit, and the accepted intervals. It is public, needs no API key, and costs no credits. Use it to check a combination before you call it, and to drive venue and channel choices in your own code. The rendered table is on Capabilities.

Errors

Every error_code, its HTTP status, and what to do next.

Capabilities

Venue and data type matrix with live, replay, and history start.

Pagination

Follow has_more and next_cursor through long histories.

Data conventions

Decimal strings, numeric fields, and HIP-4 probabilities.

Get started

Plans & limits

Response envelope

Errors

Versioning

Time

Parameter names

Coverage signals

Unsupported combinations and unknown routes

Deprecated root routes

Capabilities

Errors

Capabilities

Pagination

Data conventions

​Response envelope

​Errors

​Versioning

​Time

​Pagination

​Parameter names

​Coverage signals

​Unsupported combinations and unknown routes

​Deprecated root routes

​Capabilities

​Related pages

Errors

Capabilities

Pagination

Data conventions

Response envelope

Errors

Versioning

Time

Pagination

Parameter names

Coverage signals

Unsupported combinations and unknown routes

Deprecated root routes

Capabilities

Related pages