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

# Lighter quickstart

> Make a first Lighter request with 0xArchive: create a key, call the Lighter order book, and confirm the response before pulling trades, funding, or L3 depth.

Make your first Lighter request: create a key, call the Lighter order book under `/v1/lighter/*`, and confirm the response shape.

<Steps>
  <Step title="Create a key">
    Open the [dashboard](https://0xarchive.io/dashboard?utm_source=docs\&utm_medium=referral\&utm_campaign=docs_referral\&utm_content=lighter_create_key) and create an API key.
  </Step>

  <Step title="Set it in your shell">
    ```bash theme={"theme":"github-dark"}
    export OXARCHIVE_API_KEY="0xa_your_api_key"
    ```
  </Step>

  <Step title="Call the Lighter order book">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/lighter/orderbook/BTC?depth=1" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```
  </Step>

  <Step title="Confirm the result">
    Continue when the request returns HTTP `200`, `success: true`, an order-book object in `data`, and `meta.request_id`.
  </Step>
</Steps>

## Expected response

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

```json theme={"theme":"github-dark"}
{
  "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, symbol, response timestamp, and request ID with the result. A `BTC` string alone does not say which venue it came from.

## If the call fails

| Code | Meaning and what to 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 the key's status |
| `403` | The window is outside your plan's history window or span (`historical_depth_exceeded`, `historical_range_exceeded`), or the key was refused (`forbidden`). Branch on `error_code`; a `403` does not mean the route needs a higher plan |
| `404` | The Lighter symbol or route was not found. Check the Lighter namespace and the instruments on [Lighter REST](/rest-api/lighter) |
| `429` | A rate, concurrency, or credit limit was reached. Honor `Retry-After`; otherwise back off and reduce concurrency |

Keep `meta.request_id`, or the `x-request-id` response header, with a failed request. [Errors](/errors) covers retry decisions and [Rate limits](/rate-limits) covers capacity.

## L2 and L3

The L2 route answers price-level questions. When you need individual resting orders, for queue behavior or reconstruction, use `/v1/lighter/l3orderbook/{symbol}`: it returns orders with numeric `order_index`, `owner_account_index`, `price`, `remaining_size`, and `original_size` fields. Lighter L3 is not the same data as Hyperliquid L4, so label the depth level in storage, tests, and exports. Add gap handling before L3 or replay output reaches a production job; [SDK reconstruction](/sdks/reconstruction) covers local order-book maintenance.

## Check coverage before widening

Lighter per-fill trade rows begin January 17, 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 with [Data quality](/data-quality) before a long history or reconstruction job relies on a window.

From here, [Lighter REST](/rest-api/lighter) lists every route, including `/v1/lighter/liquidations/{symbol}` and `/v1/lighter/liquidations/{symbol}/volume`. For live order books, trades, open interest, and funding, use [Lighter WebSocket channels](/websocket/lighter), and use [WebSocket replay](/websocket/replay) when event order matters.

## Next step

Pull a bounded window of Lighter trades, funding, or depth with the [Lighter historical data API](/lighter-historical-data-api).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.