> ## 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 and market-data payload shapes.

Generated endpoint pages contain the route-specific schemas. This page covers the shared response model, common market-data payload shapes, and the fields most clients should handle consistently.

Use [Responses](/responses) when you need parser behavior, [Example Responses](/response-examples) when you need payload examples, [Examples](/examples) when you need copyable request code, and [Export Schemas](/export-schemas) when the user is choosing Parquet file datasets.

## Schema Source

OpenAPI and the generated endpoint reference are the route-specific contract for REST requests and responses. Generated schema pages are derived from the refreshed local `openapi.json` so builders can browse component schemas, operation schemas, and route families without treating examples as complete schema coverage. Response examples are teaching artifacts; they are not the schema contract.

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "0xArchive response envelope",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the request succeeded."
    },
    "data": {
      "description": "Route-specific payload documented by the generated operation schema."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string"
        },
        "request_id": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}
```

<CardGroup cols={2}>
  <Card title="Component Schemas" icon="braces" href="/schemas/components">
    Browse every generated OpenAPI component schema.
  </Card>

  <Card title="Operation Schemas" icon="route" href="/schemas/operations">
    Open route-level request and response JSON Schema pages.
  </Card>

  <Card title="Hyperliquid Core Schemas" icon="layers" href="/schemas/families/hyperliquid-core">
    Review generated Hyperliquid core operation contracts.
  </Card>

  <Card title="Hyperliquid Spot Schemas" icon="orbit" href="/schemas/families/hyperliquid-spot">
    Review generated Spot operation contracts.
  </Card>

  <Card title="HIP-3 Schemas" icon="git-branch" href="/schemas/families/hip3">
    Review generated HIP-3 operation contracts.
  </Card>

  <Card title="HIP-4 Schemas" icon="split" href="/schemas/families/hip4">
    Review generated HIP-4 operation contracts.
  </Card>

  <Card title="Lighter Schemas" icon="zap" href="/schemas/families/lighter">
    Review generated Lighter operation contracts.
  </Card>

  <Card title="Data Quality Schemas" icon="shield-check" href="/schemas/families/data-quality">
    Review generated status, coverage, and quality contracts.
  </Card>

  <Card title="Export Manifest Schemas" icon="table-properties" href="/schemas/export-manifests">
    Browse generator-backed Data Catalog export manifest schemas.
  </Card>

  <Card title="WebSocket Messages" icon="radio" href="/schemas/websocket-messages">
    See the generated bridge to the current WebSocket command inventory.
  </Card>
</CardGroup>

## 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.next_cursor" type="string">
  Cursor for the next page when a paginated historical route has more results.
</ResponseField>

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

## Schema Families

| Family                    | Schema intent                                                                                | 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                                | `/funding/{symbol}`, `/openinterest/{symbol}`                                          |
| Liquidations and orders   | Liquidation events, order history, flow, and TPSL records                                    | Liquidation and order routes where available                                           |
| Spot TWAP                 | Hyperliquid Spot TWAP records                                                                | `/v1/hyperliquid/spot/twap/{symbol}`                                                   |
| Data quality              | Coverage, status, incidents, latency, and SLA records                                        | `/v1/data-quality/*`                                                                   |
| Wallet auth               | SIWE challenge, signup, key, revoke, and subscribe responses                                 | `/v1/auth/web3/challenge`, `/v1/web3/signup`, `/v1/web3/keys`                          |
| Export datasets           | Parquet schema keys, coverage keys, rough columns, pricing units, and file-delivery metadata | Data Catalog export schemas                                                            |

## Client Schema Packet

Use this packet before generating types, warehouse tables, or agent parser instructions.

| Schema decision       | Public rule                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Route-specific type   | Start from the generated endpoint reference in [OpenAPI](/openapi) or the route-level pages in [Operation Schemas](/schemas/operations). |
| Shared envelope       | Apply `success`, `data`, `meta.count`, `meta.next_cursor`, and `meta.request_id` handling consistently.                                  |
| 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, HIP-3 prefixes, HIP-4 outcome identifiers, and Lighter symbols distinct.                                                |
| 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.            |

## 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 where the source supports 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>

## Schema Use In Clients

Generated endpoint pages are the source for route-specific schemas. Use this page for shared behavior that should appear in every client: success handling, pagination metadata, request IDs, timestamp parsing, and error propagation.

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 relying on floating-point defaults in strategy, accounting, or model code.

## 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`.

## Venue-Specific Meaning

The same field name can mean different things by venue family. HIP-4 prices are probabilities, not USD prices. Spot symbols are pairs such as `HYPE-USDC`. HIP-3 symbols can include a builder prefix such as `km:US500`. Lighter routes live under their own namespace. Preserve the venue family in stored records so downstream joins do not treat unrelated symbols as the same instrument.

## Examples And Responses

Examples are teaching artifacts, not the schema source. They should show route family, auth, request IDs, bounded scope, and schema-backed payload shapes, but client code should still parse from the generated schema. Response handling should check HTTP status, `success`, `error.code`, pagination metadata, and `meta.request_id`.

<CardGroup cols={2}>
  <Card title="REST API" icon="square-terminal" href="/rest-api">
    Open endpoint-specific schemas.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/errors">
    Handle error responses and request IDs.
  </Card>

  <Card title="Responses" icon="braces" href="/responses">
    Parse envelopes, pagination, errors, and decimal-sensitive fields.
  </Card>

  <Card title="Example Responses" icon="file-json" href="/response-examples">
    Review schema-backed JSON examples before writing parsers or tests.
  </Card>

  <Card title="Examples" icon="code-2" href="/examples">
    Copy bounded request, parser, WebSocket, and agent examples.
  </Card>

  <Card title="Export Schemas" icon="table-properties" href="/export-schemas">
    Choose Parquet export datasets and preserve schema keys.
  </Card>
</CardGroup>