> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# l4BookSnapshot | Hyperliquid Info API

> Hyperliquid l4BookSnapshot: fetch a full order-level (L4) order book snapshot for one coin, with height, epoch, and seq to bootstrap the l4BookUpdates stream.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per call</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

The Hyperliquid info endpoint with `type: "l4BookSnapshot"` is used to fetch a full **order-level (L4)** order book snapshot for one coin - every resting order, not aggregated price levels - carrying the `height`, `epoch`, and per-coin `seq` needed to bootstrap and align the [`l4BookUpdates`](/docs/api-reference/hyperliquid-websocket/l4-book-updates) diff stream.

<Info>
  * GoldRush-native. `l4BookSnapshot` is not a `POST api.hyperliquid.xyz/info` method - it is served only by the GoldRush endpoint.
  * **Bootstrap for [`l4BookUpdates`](/docs/api-reference/hyperliquid-websocket/l4-book-updates).** That WebSocket stream is diff-only; this endpoint provides the initial order-level book to seed from, plus the `height`/`epoch`/`seq` to align the diffs onto it.
  * **Order-level.** Unlike the aggregated [`l2BookDiffSnapshot`](/docs/api-reference/hyperliquid-info/l2-book-diff-snapshot), each entry is an **individual order** (`user`, `oid`, `side`, `sz`, `tif`, trigger metadata), enabling queue-position reconstruction and per-trader flow attribution.
  * **Perps only.** No spot or prediction-market assets.
  * The snapshot already reflects every diff **up to and including** its own `height` (it is taken after that block is applied), so discard any diff at or below it.
</Info>

Returns a point-in-time, full order-level book for one `coin` - two arrays of individual orders (bids first, then asks, each in queue order at its price) - together with the `height`, `epoch`, and per-coin `seq` that tie the snapshot to the `l4BookUpdates` stream.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
```

## Request

<ParamField body="type" type="string" required default="l4BookSnapshot">
  Always `"l4BookSnapshot"`.
</ParamField>

<ParamField body="coin" type="string" required>
  The perp asset symbol, e.g. `"BTC"`. For HIP-3 markets use the deployer-prefixed form.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://hypercore.goldrushdata.com/info \
    -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "l4BookSnapshot",
      "coin": "BTC"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://hypercore.goldrushdata.com/info", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "l4BookSnapshot",
      coin: "BTC",
    }),
  });

  const snap = await response.json();
  const { height, epoch, seq } = snap;
  const [bids, asks] = snap.levels;
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.post(
      "https://hypercore.goldrushdata.com/info",
      headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
      json={"type": "l4BookSnapshot", "coin": "BTC"},
  )

  snap = response.json()
  height, epoch, seq = snap["height"], snap["epoch"], snap["seq"]
  bids, asks = snap["levels"]
  ```
</CodeGroup>

## Response

A single JSON object. `levels` is a two-element array: element 0 is the bid side, element 1 is the ask side. Each entry is an **individual order** (not an aggregated level), in queue order at its price.

```json theme={null}
{
  "coin": "BTC",
  "time": 1778865761968,
  "height": 997719816,
  "epoch": "466bf60f-bb7a-4591-89a3-a2660234fef5",
  "seq": 4229977,
  "levels": [
    [
      {
        "user": "0xa62b923a112d50d03e1e096bbd53422490dac104",
        "coin": "BTC",
        "side": "B",
        "limitPx": "79242",
        "sz": "0.74831",
        "oid": 427632406005,
        "timestamp": 1778865761305,
        "triggerCondition": "N/A",
        "isTrigger": false,
        "triggerPx": "0.0",
        "isPositionTpsl": false,
        "reduceOnly": false,
        "orderType": "Limit",
        "tif": "Alo",
        "cloid": "0x00000000000000000000019e2c8b7d66"
      }
    ],
    [
      {
        "user": "0xfcf104006bfff47695c1dc21dad3e9de1e72098e",
        "coin": "BTC",
        "side": "A",
        "limitPx": "79250",
        "sz": "0.2961",
        "oid": 427632406032,
        "timestamp": 1778865761305,
        "triggerCondition": "N/A",
        "isTrigger": false,
        "triggerPx": "0.0",
        "isPositionTpsl": false,
        "reduceOnly": false,
        "orderType": "Limit",
        "tif": "Gtc",
        "cloid": null
      }
    ]
  ]
}
```

### Field descriptions

<Note>
  `limitPx`, `sz`, and `triggerPx` are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats.
</Note>

<ResponseField name="coin" type="string">The asset the book is for - echoes the request `coin`.</ResponseField>
<ResponseField name="time" type="int">Snapshot timestamp in milliseconds since Unix epoch.</ResponseField>
<ResponseField name="height" type="int">HyperCore block height the snapshot was taken at. Discard any `l4BookUpdates` batch whose `block_height` is ≤ this value.</ResponseField>
<ResponseField name="epoch" type="string">Server generation (UUID). Must match the `epoch` on the `l4BookUpdates` batches you apply; a different `epoch` means the stream reset and you should re-fetch.</ResponseField>
<ResponseField name="seq" type="int">The per-coin sequence this snapshot is aligned to. The first `l4BookUpdates` entry you apply for this coin should have `prev_seq == seq`.</ResponseField>

<ResponseField name="levels" type="array<array<Order>>">
  Two-element array: `levels[0]` are bids, `levels[1]` are asks. Each side is an array of individual **Order** objects (see below), in queue order at their respective price.
</ResponseField>

### Order object

<ResponseField name="user" type="string">Wallet address that owns the order.</ResponseField>
<ResponseField name="coin" type="string">Asset symbol.</ResponseField>
<ResponseField name="side" type="string">`"B"` for bid, `"A"` for ask.</ResponseField>
<ResponseField name="limitPx" type="string">Limit price (decimal string).</ResponseField>
<ResponseField name="sz" type="string">Resting size (decimal string, base units).</ResponseField>
<ResponseField name="oid" type="int">Hyperliquid order id - stable for the lifetime of the order.</ResponseField>
<ResponseField name="timestamp" type="int">Order-placement timestamp in HyperCore milliseconds.</ResponseField>
<ResponseField name="triggerCondition" type="string">Trigger condition string (e.g. `"N/A"` for plain limit orders).</ResponseField>
<ResponseField name="isTrigger" type="boolean">True if this is a stop / take-profit trigger order.</ResponseField>
<ResponseField name="triggerPx" type="string">Trigger price (decimal string, `"0.0"` for non-trigger orders).</ResponseField>
<ResponseField name="isPositionTpsl" type="boolean">True if this is a position-level TP/SL.</ResponseField>
<ResponseField name="reduceOnly" type="boolean">True if the order is flagged reduce-only.</ResponseField>
<ResponseField name="orderType" type="string">Hyperliquid order type (e.g. `"Limit"`).</ResponseField>
<ResponseField name="tif" type="string">Time-in-force (e.g. `"Alo"`, `"Gtc"`, `"Ioc"`).</ResponseField>
<ResponseField name="cloid" type="string | null">Client-supplied order id (hex string), or `null` if none was provided.</ResponseField>

## Bootstrapping the l4BookUpdates stream

Use this snapshot to seed a local order-level book, then keep it current with the [`l4BookUpdates`](/docs/api-reference/hyperliquid-websocket/l4-book-updates) WebSocket stream:

1. Subscribe to `l4BookUpdates` for your coin(s) and start buffering `Updates`.
2. Fetch this snapshot; note `height`, `epoch`, and `seq`.
3. Drop any buffered batch whose `block_height` ≤ `height`.
4. Confirm each remaining batch's `epoch` equals this snapshot's `epoch` (else re-fetch).
5. Apply diffs in order - the first for the coin has `prev_seq == seq`. Insert (`new`), resize (`update`), or delete (`remove`) each order by `oid`.
6. Keep checking per-coin `prev_seq` continuity; on a gap or `epoch` change, re-fetch and re-bootstrap.

## Related endpoints

<CardGroup cols={2}>
  <Card title="l4BookUpdates" href="/docs/api-reference/hyperliquid-websocket/l4-book-updates">subscribe to a strictly-ordered, diff-only order-level (L4) book stream with per-coin sequence numbers and a server epoch for gap detection.</Card>
  <Card title="l4Book" href="/docs/api-reference/hyperliquid-websocket/l4-book">subscribe to GoldRush's order-level Hyperliquid book - initial snapshot of every resting order plus per-block diffs with full metadata.</Card>
  <Card title="l2BookDiffSnapshot" href="/docs/api-reference/hyperliquid-info/l2-book-diff-snapshot">fetch a full-depth L2 order book snapshot for one coin, with height, epoch, and seq to bootstrap the l2BookDiff2 stream.</Card>
</CardGroup>

See all Hyperliquid endpoints: [Overview hub](/docs/goldrush-hyperliquid/overview) · [Info API reference](/docs/goldrush-hyperliquid/info-api/overview)