Lighter API Quickstart

Create a key, call the Lighter order-book route, and confirm the response shape. Lighter is a separate top-level venue family under /v1/lighter/*.

Create a key

Open the dashboard and create an API key.

Set it in your shell

export OXARCHIVE_API_KEY="0xa_your_api_key"

Call the Lighter order book

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

Confirm the result

Continue when the request returns HTTP 200, success: true, an order-book object in data, and meta.request_id.

Expected response

The Lighter L2 route returns aggregated price levels with decimal-string px and sz fields and an order count in n:

{
  "success": true,
  "data": {
    "coin": "BTC",
    "symbol": "BTC",
    "timestamp": "2026-08-28T00:00:00.000Z",
    "bids": [{ "px": "61077.0", "sz": "0.0003", "n": 1 }],
    "asks": [{ "px": "61078.0", "sz": "11.73086", "n": 1 }],
    "mid_price": "61077.5"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Keep the venue family, symbol, response timestamp, and request ID with the result. L3 is a different route and data grain: /v1/lighter/l3orderbook/{symbol} returns individual resting orders with numeric order_index, owner_account_index, price, remaining_size, and original_size fields.

If the call fails

Code	Means	Do
`400`	The symbol, depth, or another parameter is invalid	Check the Lighter route and parameter value before retrying
`401`	The API key is missing or invalid	Check `X-API-Key` and key status
`403`	The supplied key or request is not accepted for this route	Check the exact endpoint, route family, symbol, and schema, then verify the account or key contract. Published route access is not a higher-tier feature; plans govern capacity and request windows, not route availability
`404`	The Lighter symbol or route was not found	Check the Lighter namespace and instruments
`429`	Rate, concurrency, or credit limit reached	Honor `Retry-After`, otherwise back off and reduce concurrency

Keep meta.request_id or the x-request-id response header with the failed request. Use Errors and request IDs for retry decisions and Rate limits for capacity controls.

Check freshness before widening

Use Data quality before a long Lighter history or reconstruction job. Lighter per-fill trade rows begin August 27, 2025; exact starts vary by market. L3 order-level history begins March 5, 2026 and is capped at 250 orders per side per tick. Check the exact symbol and data type before relying on a window.

Lighter request checklist

Field	Starter value
Venue family	Lighter.xyz
Namespace	`/v1/lighter/*`
First route	`/v1/lighter/orderbook/BTC`
First fields to log	route, symbol, response timestamp, `meta.request_id`, status code
Next branch	trades, candles, funding, OI, liquidations, L3, replay, or reconstruction

Keep this checklist separate from Hyperliquid core, Spot, HIP-3, and HIP-4. A BTC string is not enough context for logs or generated clients.

Next branches

Lighter REST

Exact routes and route-specific response guidance for the Lighter family.

Lighter historical data API

Historical windows and per-fill boundaries for Lighter.

Use Historical market data for bounded windows, WebSocket replay when event ordering matters, and Data quality before an output feeds a backtest, alert, export, or model. The Lighter REST reference includes /v1/lighter/liquidations/{symbol} and /v1/lighter/liquidations/{symbol}/volume; use SDK reconstruction when the workflow needs local order-book maintenance.

Common mistakes

Do not route Lighter symbols through Hyperliquid examples. Do not treat Lighter L3 and Hyperliquid L4 as the same primitive. Keep venue family in logs, storage, and generated code so later joins distinguish sources.

L2 versus L3

Use L2 routes when aggregated price-level depth answers the question. Use L3 when the workflow needs order-level state, queue behavior, or reconstruction-oriented history. Keep L3 separate in storage, tests, and exports, and label the depth level in every result. If the next workflow is L3 or replay, add gap handling before using the result in a production job.

Get started

Plans & limits

Lighter API Quickstart

Expected response

If the call fails

Check freshness before widening

Lighter request checklist

Next branches

Lighter REST

Lighter historical data API

Common mistakes

L2 versus L3

​Expected response

​If the call fails

​Check freshness before widening

​Lighter request checklist

​Next branches

Lighter REST

Lighter historical data API

​Common mistakes

​L2 versus L3

Expected response

If the call fails

Check freshness before widening

Lighter request checklist

Next branches

Common mistakes

L2 versus L3