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

# Example responses

> See schema-backed 0xArchive JSON examples for envelopes, market-data payloads, and route families that need OpenAPI checks before typed parsing.

See what each route family returns before you write a parser, test, warehouse schema, or agent prompt. The examples use the field names in the OpenAPI contract.

Examples show returned values; they are not the schema source. OpenAPI and Endpoint Reference remain the exact type source: take types from [OpenAPI](/openapi) or the [Endpoint reference](/api-reference), and use these examples to check envelope handling, request IDs, pagination, venue context, and parser boundaries. When a route's OpenAPI schema exposes `data` as generic objects, keep the envelope and metadata, inspect the current endpoint response, and avoid binding a fixed model from an example.

Most market-data routes use this envelope:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {},
  "meta": {
    "count": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## L2 order book snapshot

Request:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=2" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "symbol": "BTC",
    "coin": "BTC",
    "timestamp": "2026-05-15T12:00:00.123Z",
    "bids": [
      { "px": "103248.50", "sz": "1.247", "n": 8 },
      { "px": "103248.00", "sz": "0.614", "n": 4 }
    ],
    "asks": [
      { "px": "103249.00", "sz": "0.892", "n": 5 },
      { "px": "103249.50", "sz": "1.103", "n": 7 }
    ],
    "mid_price": "103248.75",
    "spread": "0.50",
    "spread_bps": "0.05"
  },
  "meta": {
    "count": 1,
    "request_id": "6b52701d-1c45-4b5a-b215-7d6bb841f781"
  }
}
```

The L2 shape is aggregated by price level. `px` is the level price, `sz` is total size at that price, and `n` is the number of orders contributing to the level.

## Trade list

Request:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "coin": "BTC",
      "side": "B",
      "price": "103250.00",
      "size": "0.035",
      "timestamp": "2026-05-15T12:00:01.420Z",
      "trade_id": 907964252522803,
      "order_id": 481237650192,
      "tx_hash": "0xe266d353038e679c5d7e042433054f0000e1d8e52f7860ecda84573b9b5a02ca",
      "crossed": true,
      "fee": "0.0723",
      "fee_token": "USDC",
      "closed_pnl": "0",
      "direction": "Open Long",
      "user_address": "0x84eec0068b37919cc8f13d7454073ac167374cc0",
      "maker_address": "0x4d969e59b312970cc07af266938a4433ccae0b4c",
      "taker_address": "0x84eec0068b37919cc8f13d7454073ac167374cc0"
    }
  ],
  "meta": {
    "count": 1,
    "has_more": true,
    "next_cursor": "1768478401420_907964252522803",
    "request_id": "0e6de908-5e6a-4cbb-86e3-7b9e589cbb2e"
  }
}
```

`side` uses venue side codes. Preserve `direction`, maker/taker fields, fees, cursor, and request ID when trades feed a backtest or risk view.

## Empty page with cursor exhausted

Some bounded historical requests can succeed with no returned rows. Treat an empty `data` array as a valid response when `success` is true; the job decision should come from the requested window, data-quality state, and `meta.has_more`. A final page can be empty when the previous page was exactly full; `has_more` is `false` on it and `next_cursor` is absent.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [],
  "meta": {
    "count": 0,
    "has_more": false,
    "request_id": "2a708546-6f7f-48d7-bd33-45a31c947d52"
  }
}
```

Do not fabricate missing trades, books, or candles when a route returns an empty page. Store the route, symbol, window, cursor state, request ID, and data-quality decision so the downstream output can explain the gap.

## Funding, open interest, and candles

Funding response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "coin": "BTC",
      "timestamp": "2026-05-15T08:00:00.000Z",
      "funding_rate": "0.00025",
      "premium": "0.00050"
    }
  ],
  "meta": {
    "count": 1,
    "request_id": "35158c3b-bd12-48b7-9cd7-62702f7f052e"
  }
}
```

Open-interest response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "coin": "BTC",
      "timestamp": "2026-05-15T12:00:00.000Z",
      "open_interest": "500000.00",
      "mark_price": "103245.50",
      "oracle_price": "103241.25",
      "day_ntl_volume": "10000000.00",
      "prev_day_price": "102900.00",
      "mid_price": "103248.75"
    }
  ],
  "meta": {
    "count": 1,
    "request_id": "7c9fd2c7-c3d0-4873-8bd8-5c44f38a404f"
  }
}
```

Candle response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "timestamp": "2026-05-15T12:00:00Z",
      "open": 103210.5,
      "high": 103300,
      "low": 103150.25,
      "close": 103248.75,
      "volume": 1250.5,
      "quote_volume": 129118281.25,
      "trade_count": 4520
    }
  ],
  "meta": {
    "count": 1,
    "has_more": false,
    "request_id": "f7e84508-5c5f-4da8-b1a8-c6a8b9e5214c"
  }
}
```

Funding, open-interest, and candle routes are separate series. Store interval, route path, venue family, symbol, cursor, and request ID where the route returns one.

## Liquidation event

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "BTC",
      "coin": "BTC",
      "timestamp": "2026-05-15T12:05:00.000Z",
      "liquidated_user": "0x84eec0068b37919cc8f13d7454073ac167374cc0",
      "liquidator_user": "0x4d969e59b312970cc07af266938a4433ccae0b4c",
      "price": "102900.50",
      "size": "1.5",
      "side": "B",
      "mark_price": "102880.25",
      "closed_pnl": "-1250.50",
      "direction": "Close Long",
      "trade_id": 1234567890,
      "tx_hash": "0xe266d353038e679c5d7e042433054f0000e1d8e52f7860ecda84573b9b5a02ca"
    }
  ],
  "meta": {
    "count": 1,
    "has_more": true,
    "next_cursor": "1768478700000_1234567890",
    "request_id": "8e3ba08c-687d-4e86-b616-01a56bf9e880"
  }
}
```

Liquidations are not trades with a different label. Keep liquidation route, direction, side, mark price, users, cursor, and request metadata available for audits.

## Hyperliquid Spot trade

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "HYPE-USDC",
      "coin": "HYPE-USDC",
      "side": "A",
      "price": "38.1200",
      "size": "45.7",
      "timestamp": "2026-05-15T12:06:00.000Z",
      "trade_id": 77551201,
      "crossed": true,
      "fee": "0.3482",
      "fee_token": "USDC",
      "taker_address": "0x84eec0068b37919cc8f13d7454073ac167374cc0",
      "maker_address": "0x4d969e59b312970cc07af266938a4433ccae0b4c"
    }
  ],
  "meta": {
    "count": 1,
    "request_id": "6a613450-8016-4d21-9b93-74a298b43a29"
  }
}
```

Spot uses pair symbols such as `HYPE-USDC`. Keep Spot routes separate from core perp symbols such as `HYPE`.

## HIP-3 builder market trade

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    {
      "symbol": "km:US500",
      "coin": "km:US500",
      "side": "B",
      "price": "6225.40",
      "size": "3.0",
      "timestamp": "2026-05-15T12:06:30.000Z",
      "trade_id": 443901772,
      "crossed": true,
      "fee": "0.1125",
      "fee_token": "USDC",
      "direction": "Open Long",
      "user_address": "0x84eec0068b37919cc8f13d7454073ac167374cc0"
    }
  ],
  "meta": {
    "count": 1,
    "has_more": true,
    "next_cursor": "1768478790000_443901772",
    "request_id": "99701146-06b3-48e9-9387-665936ea2628"
  }
}
```

HIP-3 symbols preserve builder prefixes such as `km:`. Do not strip the prefix when routing, storing rows, or comparing to Hyperliquid core symbols.

## HIP-4 outcome book

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "symbol": "#0",
    "coin": "#0",
    "timestamp": "2026-05-15T12:07:00.000Z",
    "bids": [
      { "px": "0.6498", "sz": "1200", "n": 4 }
    ],
    "asks": [
      { "px": "0.6504", "sz": "900", "n": 3 }
    ],
    "mid_price": "0.6501",
    "spread": "0.0006",
    "spread_bps": "9.23"
  },
  "meta": {
    "count": 1,
    "request_id": "f7fe688d-1af8-4c4e-9b60-74e7f61dfd0c"
  }
}
```

For HIP-4, fields such as `mid_price` and `mark_price` are probability-like values in `[0, 1]`, not ordinary USD prices.

## L4, L3, and lifecycle routes

L4 current snapshot routes return one reconstructed book object in `data`; their `/history` routes return arrays of snapshot objects. Lighter L3 follows the same grain: the current route returns one book object, while history returns an array of snapshots. Diff and lifecycle routes are separate array response contracts; use the route's Endpoint Reference page for their item shape. Do not normalize these route families into one shared array or object model.

| Route family | Parser rule |
| - | - |
| Hyperliquid L4 checkpoint, `/v1/hyperliquid/orderbook/{symbol}/l4` | Preserve raw object fields, route, symbol, cursor, and request ID. |
| Hyperliquid L4 diffs, `/v1/hyperliquid/orderbook/{symbol}/l4/diffs` | Apply records in returned order and store sequence-like fields when present. |
| Hyperliquid order history, `/v1/hyperliquid/orders/{symbol}/history` | Keep status, side, price, size, order identifiers, timestamps, and request metadata when present. |
| Lighter L3 order book, `/v1/lighter/l3orderbook/{symbol}` | Treat L3 as individual-order depth, not an L2 price-level book. |

Read the route's Endpoint Reference page before creating typed models for these route families. Do not copy L4 or L3 field names from another venue, export schema, or browser view into API client code.

## Lighter L3 order book

Request:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/lighter/l3orderbook/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "coin": "BTC",
    "timestamp": "2026-05-15T12:08:00.000Z",
    "orders": [
      {
        "order_index": 562952175455810,
        "owner_account_index": 102394,
        "side": "bid",
        "price": 103242.1,
        "remaining_size": 0.42,
        "original_size": 0.42
      },
      {
        "order_index": 562952175455811,
        "owner_account_index": 98804,
        "side": "ask",
        "price": 103243,
        "remaining_size": 0.35,
        "original_size": 0.5
      }
    ],
    "bid_count": 250,
    "ask_count": 250,
    "total_bid_size": 450.5,
    "total_ask_size": 380.2,
    "mid_price": "103242.55",
    "spread": "0.9",
    "spread_bps": "0.09",
    "truncated": true
  },
  "meta": {
    "count": 1,
    "request_id": "3e6a94cf-22af-4bf1-bfe7-5b72c1b970c0"
  }
}
```

Lighter L3 represents individual-order depth. The latest L3 route returns a single object in `data`, not an array of books. `order_index` and `owner_account_index` are numeric Lighter indexes; `price`, `remaining_size`, and `original_size` are JSON numbers. These fields are not owner addresses, wallet addresses, or raw order IDs. Do not parse it as an aggregated L2 book, and keep the Lighter venue family attached to stored records.

## Data freshness

Request:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/freshness/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "symbol": "BTC",
    "coin": "BTC",
    "exchange": "hyperliquid",
    "measured_at": "2026-05-15T12:08:30.000Z",
    "orderbook": {
      "last_updated": "2026-05-15T12:08:29.700Z",
      "lag_ms": 300
    },
    "trades": {
      "last_updated": "2026-05-15T12:08:29.100Z",
      "lag_ms": 900
    },
    "funding": {
      "last_updated": "2026-05-15T08:00:00.000Z",
      "lag_ms": 14910000
    },
    "open_interest": {
      "last_updated": "2026-05-15T12:08:00.000Z",
      "lag_ms": 30000
    },
    "liquidations": {
      "last_updated": "2026-05-15T12:07:58.000Z",
      "lag_ms": 32000
    }
  },
  "meta": {
    "count": 1,
    "request_id": "dfb82a16-4b34-421f-87f6-2d424ab07673"
  }
}
```

Freshness responses should travel with downstream output when the result feeds a backtest, alert, dashboard, model, or export.

## Data-quality coverage response

Request:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "exchange": "hyperliquid",
  "symbol": "BTC",
  "data_types": {
    "orderbook": {
      "earliest": "2023-04-15T00:00:07.400Z",
      "latest": "2026-05-15T06:10:17.661Z",
      "total_records": 174035149,
      "completeness": 100,
      "historical_coverage": 98.3,
      "gaps": [
        {
          "start": "2026-05-13T18:59:04.312Z",
          "end": "2026-05-13T19:04:07.152Z",
          "duration_minutes": 5
        }
      ],
      "cadence": {
        "median_interval_seconds": 1,
        "p95_interval_seconds": 1,
        "sample_count": 86388
      }
    },
    "trades": {
      "earliest": "2023-04-19T23:20:23.280Z",
      "latest": "2026-05-15T06:09:46.353Z",
      "total_records": 331220828,
      "completeness": 100,
      "historical_coverage": 88.2,
      "gaps": []
    }
  }
}
```

Data-quality coverage routes use resource-specific response bodies rather than the ordinary market-data envelope. Store the coverage response with the downstream data request ID and job tolerance. Do not require `success`, `data`, or `meta.request_id` from coverage bodies that do not expose those fields.

## Error response

Request without an API key:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1"
```

Example response:

```json theme={"theme":"github-dark"}
{
  "success": false,
  "code": 401,
  "error_code": "unauthorized",
  "error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
  "request_id": "1be62fa0-7ea8-4ad6-a557-22fd0c568a4b"
}
```

Treat HTTP status as the control signal and `error_code` as the reason. The JSON body explains what failed and carries the request ID needed for logs, support, retries, or agent tasks.

## Next step

Handle every failure a parser can meet with [Errors](/errors).


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