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

> [card] Credit Cost
>
> 1 per call

> [card] Processing
>
> Realtime

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`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l4-book-updates) diff stream.

> [!NOTE]
>
> * GoldRush-native. `l4BookSnapshot` is not a `POST api.hyperliquid.xyz/info` method - it is served only by the GoldRush endpoint.
> * **Bootstrap for [`l4BookUpdates`](https://goldrush.dev/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`](https://goldrush.dev/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.

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

**type** `string` *required* (default: l4BookSnapshot)

Always `"l4BookSnapshot"`.

**coin** `string` *required*

The perp asset symbol, e.g. `"BTC"`. For HIP-3 markets use the deployer-prefixed form.

### Example

```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"]
```

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

**coin** `string`

The asset the book is for - echoes the request `coin`.

**time** `int`

Snapshot timestamp in milliseconds since Unix epoch.

**height** `int`

HyperCore block height the snapshot was taken at. Discard any `l4BookUpdates` batch whose `block_height` is ≤ this value.

**epoch** `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.

**seq** `int`

The per-coin sequence this snapshot is aligned to. The first `l4BookUpdates` entry you apply for this coin should have `prev_seq == seq`.

**levels** `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.

### Order object

**user** `string`

Wallet address that owns the order.

**coin** `string`

Asset symbol.

**side** `string`

`"B"` for bid, `"A"` for ask.

**limitPx** `string`

Limit price (decimal string).

**sz** `string`

Resting size (decimal string, base units).

**oid** `int`

Hyperliquid order id - stable for the lifetime of the order.

**timestamp** `int`

Order-placement timestamp in HyperCore milliseconds.

**triggerCondition** `string`

Trigger condition string (e.g. `"N/A"` for plain limit orders).

**isTrigger** `boolean`

True if this is a stop / take-profit trigger order.

**triggerPx** `string`

Trigger price (decimal string, `"0.0"` for non-trigger orders).

**isPositionTpsl** `boolean`

True if this is a position-level TP/SL.

**reduceOnly** `boolean`

True if the order is flagged reduce-only.

**orderType** `string`

Hyperliquid order type (e.g. `"Limit"`).

**tif** `string`

Time-in-force (e.g. `"Alo"`, `"Gtc"`, `"Ioc"`).

**cloid** `string | null`

Client-supplied order id (hex string), or `null` if none was provided.

## Bootstrapping the l4BookUpdates stream

Use this snapshot to seed a local order-level book, then keep it current with the [`l4BookUpdates`](https://goldrush.dev/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

> [card] [l2BookDiffSnapshot](https://goldrush.dev/docs/api-reference/hyperliquid-info/l2-book-diff-snapshot.md)
>
> fetch a full-depth L2 order book snapshot for one coin, with height, epoch, and seq to bootstrap the l2BookDiff2 stream.

> [card] [candleSnapshot](https://goldrush.dev/docs/api-reference/hyperliquid-info/candle-snapshot.md)
>
> fetch historical OHLCV candles for a coin and interval over a time window for charting and backtesting.

> [card] [l2Book](https://goldrush.dev/docs/api-reference/hyperliquid-info/l2-book.md)
>
> fetch an aggregated Level-2 order book snapshot for a single coin - bids and asks as price, size, and order-count levels.

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


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