Example responses

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

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 generated operation page for their item shape. Do not normalize these route families into one shared array or object model.

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:

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

API reference

SDKs & tooling

AI & agents

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

Example Coverage Checklist

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

​Example Coverage Checklist

​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

Example Coverage Checklist

Next Step