Example responses

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 or the Endpoint 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:

{
  "success": true,
  "data": {},
  "meta": {
    "count": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

L2 order book snapshot

Request:

curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=2" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Example response:

{
  "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:

curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Example response:

{
  "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.

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

curl "https://api.0xarchive.io/v1/lighter/l3orderbook/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Example response:

{
  "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:

curl "https://api.0xarchive.io/v1/hyperliquid/freshness/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Example response:

{
  "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:

curl "https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Example response:

{
  "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:

curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?limit=1"

Example response:

{
  "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.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

L2 order book snapshot

Trade list

Empty page with cursor exhausted

Funding, open interest, and candles

Liquidation event

Hyperliquid Spot trade

HIP-3 builder market trade

HIP-4 outcome book

L4, L3, and lifecycle routes

Lighter L3 order book

Data freshness

Data-quality coverage response

Error response

Next step

​L2 order book snapshot

​Trade list

​Empty page with cursor exhausted

​Funding, open interest, and candles

​Liquidation event

​Hyperliquid Spot trade

​HIP-3 builder market trade

​HIP-4 outcome book

​L4, L3, and lifecycle routes

​Lighter L3 order book

​Data freshness

​Data-quality coverage response

​Error response

​Next step

L2 order book snapshot

Trade list

Empty page with cursor exhausted

Funding, open interest, and candles

Liquidation event

Hyperliquid Spot trade

HIP-3 builder market trade

HIP-4 outcome book

L4, L3, and lifecycle routes

Lighter L3 order book

Data freshness

Data-quality coverage response

Error response

Next step