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

Use this page when you need to see returned values before writing parsers, tests, warehouse schemas, or agent prompts. Examples here use fields named by the generated OpenAPI contract. 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.

Examples are teaching artifacts, not the schema source. Use [OpenAPI](/openapi) or the generated endpoint page for exact types, then use this page to check envelope handling, request IDs, pagination, venue context, and parser boundaries.

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=2" \
  -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,
    "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 whether `meta.next_cursor` is present.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [],
  "meta": {
    "count": 0,
    "next_cursor": null,
    "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,
    "next_cursor": null,
    "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,
    "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,
    "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

The generated OpenAPI contract exposes several high-depth routes as `data: object[]` because the records are route-specific:

| Route family              | Example path                                  | 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.                                   |

Use the generated endpoint 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": 1250,
    "ask_count": 980,
    "total_bid_size": 450.5,
    "total_ask_size": 380.2,
    "mid_price": 103242.55,
    "spread": 0.9,
    "spread_bps": 0.09
  },
  "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. 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,
  "error": {
    "code": "unauthorized",
    "message": "Missing authentication credentials. Provide X-API-Key header or Bearer token."
  },
  "meta": {
    "request_id": "d9c4bb67-9df0-4655-a3bd-cf9a559c5b91"
  }
}
```

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

## Example Coverage Packet

Use this packet when adding or changing examples.

| Coverage area         | Required example behavior                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Success envelope      | Every successful JSON example includes `success`, `data`, and `meta.request_id`.                                             |
| Error envelope        | At least one failure example shows `success: false`, `error.code`, `error.message`, and `meta.request_id`.                   |
| Empty data            | At least one successful empty array example shows `count: 0` and `next_cursor: null`.                                        |
| Venue semantics       | Spot pairs, HIP-3 prefixes, HIP-4 outcome IDs, and Lighter symbols stay visibly distinct.                                    |
| Data-quality coverage | Resource-specific coverage bodies do not have to use the ordinary market-data envelope.                                      |
| Generic routes        | L4, L3, lifecycle, and other generic object routes tell clients to inspect the endpoint response before binding fixed types. |
| Parser boundary       | The page states that examples teach payload handling, while OpenAPI remains the route-specific schema source.                |

## Next Step

Use [Responses](/responses) for envelope and parser behavior, [Schemas](/schemas) for field notes, [Examples](/examples) for request code, and the REST family pages for route selection.