Skip to main content
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 show returned values; they are not the schema source. Use OpenAPI or Endpoint reference 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: 
{
  "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=2" \
  -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,
    "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. 
{
  "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: 
{
  "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,
    "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

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

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

The generated OpenAPI contract exposes several high-depth routes as data: object[] because the records are route-specific:
Route familyExample pathParser rule
Hyperliquid L4 checkpoint/v1/hyperliquid/orderbook/{symbol}/l4Preserve raw object fields, route, symbol, cursor, and request ID.
Hyperliquid L4 diffs/v1/hyperliquid/orderbook/{symbol}/l4/diffsApply records in returned order and store sequence-like fields when present.
Hyperliquid order history/v1/hyperliquid/orders/{symbol}/historyKeep 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: 
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": 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: 
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,
  "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 Checklist

Use this checklist when adding or changing examples.
Coverage areaRequired example behavior
Success envelopeEvery successful JSON example includes success, data, and meta.request_id.
Error envelopeAt least one failure example shows success: false, error.code, error.message, and meta.request_id.
Empty dataAt least one successful empty array example shows count: 0 and next_cursor: null.
Venue semanticsSpot pairs, HIP-3 prefixes, HIP-4 outcome IDs, and Lighter symbols stay visibly distinct.
Data-quality coverageResource-specific coverage bodies do not have to use the ordinary market-data envelope.
Generic routesL4, L3, lifecycle, and other generic object routes tell clients to inspect the endpoint response before binding fixed types.
Parser boundaryThe page states that examples show returned values, while OpenAPI and Endpoint Reference remain the exact type source.

​
Next Step

Use Responses for envelope and parser behavior, Schemas for field notes, Examples for request code, and the REST family pages for route selection.
Last modified on June 28, 2026