Response schemas

Model the response shapes every REST route shares, then take each route’s own types from its operation schema. Responses covers parser behavior and Example responses shows real payloads.

Schema source

OpenAPI, the Endpoint Reference, and the operation schemas define REST requests and responses. The schema pages are refreshed from openapi.json, so you can browse component schemas, operation schemas, and route families directly. Examples help with parser expectations, but client types should come from the schema pages. The shared envelope, as JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "0xArchive response envelope",
  "oneOf": [
    {
      "title": "Success",
      "type": "object",
      "required": ["success", "data", "meta"],
      "properties": {
        "success": { "const": true },
        "data": {
          "description": "Route-specific payload documented by the generated operation schema."
        },
        "meta": {
          "type": "object",
          "required": ["request_id"],
          "properties": {
            "request_id": { "type": "string" },
            "count": { "type": "integer" },
            "has_more": { "type": "boolean" },
            "next_cursor": {
              "type": "string",
              "description": "Present exactly when has_more is true. Opaque."
            },
            "symbol": { "type": "string" },
            "venue": {
              "enum": ["hyperliquid", "hip3", "hip4", "spot", "lighter", "rh-lighter"]
            },
            "coverage_from": { "type": "string", "format": "date-time" },
            "notice": { "type": "string" }
          },
          "additionalProperties": true
        }
      }
    },
    {
      "title": "Error",
      "type": "object",
      "required": ["success", "code", "error_code", "error", "request_id"],
      "properties": {
        "success": { "const": false },
        "code": { "type": "integer", "description": "HTTP status." },
        "error_code": {
          "type": "string",
          "description": "Stable reason. See /errors for the full list."
        },
        "error": { "type": "string", "description": "Human-readable message." },
        "request_id": { "type": "string" },
        "param": { "type": "string" },
        "valid_values": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": true
    }
  ]
}

Browse schemas by family

Schemas	What they cover
Component schemas	Every OpenAPI component schema
Operation schemas	Request and response JSON Schema for each route
Hyperliquid core	Hyperliquid core operations
Hyperliquid Spot	Spot operations
HIP-3	HIP-3 operations
HIP-4	HIP-4 operations
Lighter	Lighter operations
Lighter on Robinhood Chain	Lighter on Robinhood Chain operations
Webhooks	Webhook configuration and callback schemas
Data quality	Status, coverage, and quality operations
Export manifests	Data Catalog export manifest schemas
WebSocket messages	The WebSocket command and message inventory

Envelope

boolean

true for successful responses. Error responses use success: false.

object | array

Route payload. Historical list routes usually return arrays, while market-state routes often return objects.

integer

Number of returned items.

boolean

On cursor-paged routes, true when another page exists. Keep paging while it is true.

string

Opaque cursor for the next page. Present exactly when meta.has_more is true; send it back unchanged as cursor.

string

On per-symbol routes, the canonical public symbol for the venue.

string

On per-symbol routes, the venue key: hyperliquid, hip3, hip4, spot, lighter, or rh-lighter.

string

Identifier to log for debugging and support.

Error

Every error response uses one shape. Branch on error_code; the full list with HTTP statuses is on Errors.

boolean

Always false.

integer

The HTTP status.

string

Stable snake_case reason, for example invalid_parameter, unsupported_for_venue, or rate_limited.

string

Human-readable message. Do not parse it.

string

Identifier for the failed request, at the top level of error bodies.

string

The parameter that caused the error, when one did. valid_values lists the accepted values when the set is small.

Pagination

Cursor-paged routes set meta.has_more. While it is true, repeat the request with cursor set to meta.next_cursor and every other parameter unchanged; stop when it is false. A final page can be empty. The largest limit per route family is page_limit in capabilities. See Pagination. The generated Error and ApiMeta component pages follow the published OpenAPI document and are refreshed with it.

What each data family holds

Family	What it holds, and example routes
Instruments and pairs	Market discovery and symbol metadata. `/v1/hyperliquid/instruments`, `/v1/hyperliquid/spot/pairs`, `/v1/lighter/instruments`
Order books	Bids, asks, timestamps, spread, depth, and route-specific order-book records. `/orderbook/{symbol}`, L3, L4, and history routes
Trades	Side, price, size, timestamp, and source-specific fields. `/trades/{symbol}` and recent trade routes
Candles	OHLC-style time buckets. `/candles/{symbol}`
Funding and open interest	Timestamped funding, premium, mark/mid context, and OI values. `/v1/hyperliquid/funding/{symbol}`, `/v1/hyperliquid/openinterest/{symbol}`, and venue-specific equivalents
Liquidations and orders	Liquidation events, order history, flow, and TPSL records. Completed-liquidation, projected-liquidation-level, and order-history routes by venue family
Spot TWAP	Hyperliquid Spot TWAP records. `/v1/hyperliquid/spot/twap/{symbol}`
Data quality	Coverage, status, incidents, latency, and SLA records. `/v1/data-quality/*`
Wallet access and SIWE	Existing-wallet challenge, verification, key management, retired signup, and paid subscribe responses. `/v1/auth/web3/challenge`, `/v1/auth/web3/verify`, `/v1/web3/keys`, `/v1/web3/signup`, `/v1/web3/subscribe`
Export datasets	Parquet schema keys, coverage keys, rough columns, pricing units, and file-delivery metadata. Data Catalog export schemas

Model client types

Apply these rules when you generate types, warehouse tables, or parser instructions.

Schema decision	Rule
Route-specific type	Start from Endpoint reference, OpenAPI, or route-level pages in Operation schemas.
Shared envelope	Apply `success`, `data`, `meta.count`, `meta.has_more`, `meta.next_cursor`, and `meta.request_id` handling consistently, and branch on `error_code` for errors.
Empty result state	Model `success: true` with an empty array separately from transport failure, auth failure, and missing-route errors.
Venue-specific fields	Keep Spot pairs such as `HYPE-USDC`, HIP-3 builder prefixes such as `km:US500`, HIP-4 outcome identifiers, and Lighter symbols distinct, and store the venue family with each record so joins never treat unrelated symbols as one instrument.
Decimal values	Treat prices, sizes, rates, spreads, open interest, and probability-like fields as decimal-sensitive.
High-depth books	Keep L2 snapshots, L3 individual orders, L4 book state, and L4 order events as separate schemas.
Export files	Use Export schemas; do not reuse JSON response schemas as Parquet table contracts without source metadata.

Keep numeric-looking market fields as strings unless the route schema or generated type states otherwise. Prices, sizes, spreads, rates, and open-interest values often need decimal-safe handling; convert them at the application edge with a decimal library instead of floating-point defaults in strategy, accounting, or model code.

Market fields

Order books

Order-book payloads include bids, asks, timestamps, mid price, spread, and venue-specific depth fields. L3 and L4 records should be stored separately from ordinary L2 snapshots.

Trades

Trade payloads include side, price, size, timestamp, and route-specific fields such as wallet/account identifiers when the source returns them.

Funding and open interest

Funding and OI payloads include timestamped rate, premium, mark, mid, and open-interest fields depending on venue family.

HIP-4 prices

HIP-4 mark_price and mid_price represent implied probability in [0, 1], not USD.

Data quality records

Coverage, latency, freshness, incident, and SLA payloads are trust signals. A client should compare them to the job tolerance before downstream systems use market data.

Export schemas versus API schemas

API schemas describe JSON responses from REST and WebSocket surfaces. Export schemas describe file-style Parquet datasets from the Data Catalog. Keep those models separate. An API order-book response, an L2 export, an L3 export, an L4 order-book export, and an order-events export can all represent order-book-adjacent data, but they should not share one warehouse schema without preserving source and schema key. Use Export schemas for schema keys such as l2_orderbook, l3_orderbook, l4_orderbook, l4_orders, trades, funding, oi, and liquidations.

Next step

Open a route’s request and response JSON Schema in Operation schemas.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Schema source

Browse schemas by family

Envelope

Error

What each data family holds

Model client types

Market fields

Export schemas versus API schemas

Next step

​Schema source

​Browse schemas by family

​Envelope

​Error

​Pagination

​What each data family holds

​Model client types

​Market fields

​Export schemas versus API schemas

​Next step

Schema source

Browse schemas by family

Envelope

Error

Pagination

What each data family holds

Model client types

Market fields

Export schemas versus API schemas

Next step