l4Book | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

2 per coin per minute (except BTC which is 20 per minute)

Processing

Realtime

Estimate your monthly cost for this API using the Pricing Calculator.

GoldRush-native. l4Book is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.
Perps only. No spot assets.
coin is required. Unlike l2Book and l2BookDiff, you cannot omit coin to stream every asset. Open one subscription per asset.
Snapshot, then diffs. The first message is always a Snapshot; every message thereafter is an Updates. Clients must seed local book state from the snapshot and apply diffs from there. On reconnect, drop local state and re-seed from the next snapshot.
Per-order detail. Each entry exposes user, oid, cloid, tif, and trigger metadata - enabling queue-position reconstruction, per-trader flow attribution, and microstructure analytics that are not possible with l2Book.
See the L4 Order Book recipe for patterns to maintain book state, attribute flow by user, or reconstruct aggregated price levels.

Note: When "coin":"BTC" is used, a credit rate of 20 credits per minute subscribed is applied.

Endpoint

wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>

string

required

Your GoldRush API key. Passed as a query parameter at connection time - no Authorization header is used.

Send this JSON message after the connection is established:

string

required

Always "subscribe".

object

required

Show properties

string

required

Always "l4Book".

string

required

Asset symbol - e.g. "BTC", "ETH", "@107" for spot pairs. For HIP-3 markets, include the deployer prefix. Required - unlike l2Book, l4Book does not support wildcard subscriptions; each subscription is locked to a single asset.

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"l4Book","coin":"BTC"}}

import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "l4Book", coin: "BTC" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "l4Book") return;

  if (msg.data.Snapshot) {
    const { coin, time, block_height, levels: [bids, asks] } = msg.data.Snapshot;
    console.log("snapshot", coin, time, block_height, "bids:", bids.length, "asks:", asks.length);
  } else if (msg.data.Updates) {
    const { time, block_height, order_statuses, book_diffs } = msg.data.Updates;
    console.log("updates", time, block_height, "statuses:", order_statuses.length, "diffs:", book_diffs.length);
  }
});

import asyncio, json, os
import websockets

async def main():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l4Book", "coin": "BTC"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l4Book":
                continue
            data = msg["data"]
            if "Snapshot" in data:
                snap = data["Snapshot"]
                bids, asks = snap["levels"]
                print("snapshot", snap["coin"], snap["time"], snap["block_height"], "bids:", len(bids), "asks:", len(asks))
            elif "Updates" in data:
                upd = data["Updates"]
                print("updates", upd["time"], upd["block_height"], "statuses:", len(upd["order_statuses"]), "diffs:", len(upd["book_diffs"]))

asyncio.run(main())

Unsubscribe

Send the same subscription body with method: "unsubscribe":

{
  "method": "unsubscribe",
  "subscription": { "type": "l4Book", "coin": "BTC" }
}

Streamed messages

Every message has channel: "l4Book". The data payload contains exactly one of two variants: a Snapshot (emitted once, immediately after subscribe) or an Updates (emitted on each subsequent HyperCore block where the book for coin changed).

Initial snapshot

The first message after subscribe carries the full resting book at the current block. Each entry in levels[0] (bids) and levels[1] (asks) is an individual order - not an aggregated price level.

{
  "channel": "l4Book",
  "data": {
    "Snapshot": {
      "coin": "BTC",
      "time": 1778865761968,
      "block_height": 997719816,
      "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
          }
        ]
      ]
    }
  }
}

Incremental updates

Subsequent messages carry only what changed since the previous block. order_statuses describes order lifecycle events (open, etc.); book_diffs carries the corresponding price-level changes.

{
  "channel": "l4Book",
  "data": {
    "Updates": {
      "time": 1778865761768,
      "block_height": 997719813,
      "order_statuses": [
        {
          "time": "2026-05-15T17:22:41.768005701",
          "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
          "status": "open",
          "order": {
            "user": null,
            "coin": "BTC",
            "side": "B",
            "limitPx": "79242.0",
            "sz": "0.00867",
            "oid": 427632416336,
            "timestamp": 1778865761768,
            "triggerCondition": "N/A",
            "isTrigger": false,
            "triggerPx": "0.0",
            "isPositionTpsl": false,
            "reduceOnly": false,
            "orderType": "Limit",
            "tif": "Alo",
            "cloid": null
          }
        }
      ],
      "book_diffs": [
        {
          "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
          "oid": 427632416336,
          "px": "79242.0",
          "coin": "BTC",
          "raw_book_diff": { "new": { "sz": "0.00867" } }
        }
      ]
    }
  }
}

Response fields

string

Always "l4Book".

object

Contains exactly one of Snapshot or Updates.

Show Snapshot (first message after subscribe)

string

Asset symbol the snapshot belongs to.

int

HyperCore block timestamp in milliseconds.

int

HyperCore block height the snapshot was taken at.

array<array<Order>>

Tuple [bids, asks]. Each side is an array of individual Order objects (see below), in queue order at their respective price.

Show Updates (per-block diffs)

int

HyperCore block timestamp in milliseconds.

int

HyperCore block height.

array<object>

Order lifecycle events at this block.

Show order_status fields

string

ISO-8601 timestamp with nanosecond precision.

string

Wallet address that owns the order.

string

Lifecycle status (e.g. "open").

Order

The order, in the same shape as a snapshot entry. user inside this nested object is null because it duplicates the parent user.

array<object>

Per-order book changes at this block.

Show book_diff fields

string

Wallet address that owns the order.

int

Order id the diff applies to.

string

Price level the diff applies to (decimal string).

string

Asset symbol.

object

The change descriptor. Observed shape: { "new": { "sz": "<size>" } } for a newly resting order. Other shapes may carry size deltas or cancellations - inspect the keys to discriminate.

Order object

The Order type appears inside Snapshot.levels[*][*] and Updates.order_statuses[*].order.

string | null

Wallet address that owns the order. null when the order is nested inside an order_status (the parent already carries it).

string

Asset symbol.

string

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

string

Limit price (decimal string).

string

Resting size (decimal string, base units).

int

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

int

Order-placement timestamp in HyperCore milliseconds.

string

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

boolean

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

string

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

boolean

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

boolean

True if the order is flagged reduce-only.

string

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

string

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

string | null

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

Last reviewed: 2026-06-24

Foundational API

Hyperliquid API

JSON-RPC

Service Keys

l4Book | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed messages

Initial snapshot

Incremental updates

Response fields

Order object

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed messages

​Initial snapshot

​Incremental updates

​Response fields

​Order object

Endpoint

Subscribe

Example

Unsubscribe

Streamed messages

Initial snapshot

Incremental updates

Response fields

Order object