> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Response schemas

> Understand common 0xArchive response envelopes, request metadata, pagination, error shapes, and market-data payload schemas.

Model the response shapes every REST route shares, then take each route's own types from its operation schema. [Responses](/responses) covers parser behavior and [Example responses](/response-examples) 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:

```json theme={"theme":"github-dark"}
{
  "$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](/schemas/components) | Every OpenAPI component schema |
| [Operation schemas](/schemas/operations) | Request and response JSON Schema for each route |
| [Hyperliquid core](/schemas/families/hyperliquid-core) | Hyperliquid core operations |
| [Hyperliquid Spot](/schemas/families/hyperliquid-spot) | Spot operations |
| [HIP-3](/schemas/families/hip3) | HIP-3 operations |
| [HIP-4](/schemas/families/hip4) | HIP-4 operations |
| [Lighter](/schemas/families/lighter) | Lighter operations |
| [Lighter on Robinhood Chain](/schemas/families/rh-lighter) | Lighter on Robinhood Chain operations |
| [Webhooks](/schemas/families/webhooks) | Webhook configuration and callback schemas |
| [Data quality](/schemas/families/data-quality) | Status, coverage, and quality operations |
| [Export manifests](/schemas/export-manifests) | Data Catalog export manifest schemas |
| [WebSocket messages](/schemas/websocket-messages) | The WebSocket command and message inventory |

## Envelope

<ResponseField name="success" type="boolean">
  `true` for successful responses. Error responses use `success: false`.
</ResponseField>

<ResponseField name="data" type="object | array">
  Route payload. Historical list routes usually return arrays, while market-state routes often return objects.
</ResponseField>

<ResponseField name="meta.count" type="integer">
  Number of returned items.
</ResponseField>

<ResponseField name="meta.has_more" type="boolean">
  On cursor-paged routes, `true` when another page exists. Keep paging while it is `true`.
</ResponseField>

<ResponseField name="meta.next_cursor" type="string">
  Opaque cursor for the next page. Present exactly when `meta.has_more` is `true`; send it back unchanged as `cursor`.
</ResponseField>

<ResponseField name="meta.symbol" type="string">
  On per-symbol routes, the canonical public symbol for the venue.
</ResponseField>

<ResponseField name="meta.venue" type="string">
  On per-symbol routes, the venue key: `hyperliquid`, `hip3`, `hip4`, `spot`, `lighter`, or `rh-lighter`.
</ResponseField>

<ResponseField name="meta.request_id" type="string">
  Identifier to log for debugging and support.
</ResponseField>

## Error

Every error response uses one shape. Branch on `error_code`; the full list with HTTP statuses is on [Errors](/errors).

<ResponseField name="success" type="boolean">
  Always `false`.
</ResponseField>

<ResponseField name="code" type="integer">
  The HTTP status.
</ResponseField>

<ResponseField name="error_code" type="string">
  Stable snake\_case reason, for example `invalid_parameter`, `unsupported_for_venue`, or `rate_limited`.
</ResponseField>

<ResponseField name="error" type="string">
  Human-readable message. Do not parse it.
</ResponseField>

<ResponseField name="request_id" type="string">
  Identifier for the failed request, at the top level of error bodies.
</ResponseField>

<ResponseField name="param" type="string">
  The parameter that caused the error, when one did. `valid_values` lists the accepted values when the set is small.
</ResponseField>

## 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](/capabilities). See [Pagination](/rest-api/pagination).

The generated [Error](/schemas/components/error) and [ApiMeta](/schemas/components/api-meta) 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](/api-reference), [OpenAPI](/openapi), or route-level pages in [Operation schemas](/schemas/operations). |
| 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](/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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Trades">
    Trade payloads include side, price, size, timestamp, and route-specific fields such as wallet/account identifiers when the source returns them.
  </Accordion>

  <Accordion title="Funding and open interest">
    Funding and OI payloads include timestamped rate, premium, mark, mid, and open-interest fields depending on venue family.
  </Accordion>

  <Accordion title="HIP-4 prices">
    HIP-4 `mark_price` and `mid_price` represent implied probability in `[0, 1]`, not USD.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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](/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](/schemas/operations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.