l4BookUpdates | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

1 per coin per minute

Processing

Realtime

GoldRush-native. l4BookUpdates is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.
Order-level (L4) diffs. Like l4Book, every change is per individual order (user, oid, side, raw_book_diff) plus the order-lifecycle order_statuses for the block — not aggregated price levels.
Strictly block-ordered. Diffs are emitted synchronously in monotonic block_height order. This is the difference from l4Book, whose per-block broadcast can deliver adjacent blocks out of order. The l4Book channel is unchanged; l4BookUpdates is the strictly-ordered, sequenced sibling.
Diff-only — no inline snapshot. This stream never sends a Snapshot frame; every message is an Updates batch. Seed your local book from the REST l4BookSnapshot info method, then apply diffs on top — see Bootstrapping & gap detection.
Sequenced for gap detection. Each per-coin diff carries a monotonic seq and the prev_seq it follows; each batch carries a server epoch and a cursor. This lets a client detect a dropped message or a server reset and re-bootstrap deterministically.
Perps only. No spot or prediction-market assets. coin is required — subscribe with a single symbol or an array of symbols; one asset per book.

Note: l4BookUpdates bills a flat rate per subscribed coin per minute, with no BTC premium (unlike l4Book). A multi-coin array bills the sum across its coins.

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 "l4BookUpdates".

string | string[]

required

Asset filter. Perps only. Accepts two shapes:

String - a single perp symbol (e.g. "BTC", "HYPE"). For HIP-3 deployer-perps, include the deployer prefix.
Array of strings - a fixed list of perp symbols (e.g. ["BTC", "ETH", "HYPE"], up to 64). Each coin is sequenced independently and billed independently.

Unlike l2BookDiff2, there is no spot/outcome market filter — l4BookUpdates is perp-only.

Example

Subscribe with	What you receive
`{"type":"l4BookUpdates","coin":"BTC"}`	Order-level diffs for BTC only
`{"type":"l4BookUpdates","coin":["BTC","ETH","HYPE"]}`	Diffs for a fixed list of perps

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

> {"method":"subscribe","subscription":{"type":"l4BookUpdates","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: "l4BookUpdates", coin: "BTC" },
  }));
});

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

  const { block_height, epoch, book_diffs } = msg.data.Updates;
  for (const c of book_diffs) {
    console.log(block_height, epoch, c.coin, "seq", c.prev_seq, "->", c.seq);
    for (const d of c.book_diffs) {
      // d.raw_book_diff is { new: { sz } } | { update: { origSz, newSz } } | "remove"
      console.log("  ", d.side, d.oid, d.px, JSON.stringify(d.raw_book_diff));
    }
  }
});

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, max_size=None) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l4BookUpdates", "coin": "BTC"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l4BookUpdates":
                continue
            upd = msg["data"]["Updates"]
            for c in upd["book_diffs"]:
                print(upd["block_height"], upd["epoch"], c["coin"], "seq", c["prev_seq"], "->", c["seq"])
                for d in c["book_diffs"]:
                    print("  ", d.get("side"), d["oid"], d["px"], d["raw_book_diff"])

asyncio.run(main())

Unsubscribe

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

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

Unsubscribe matches subscriptions by exact body. A subscription created with coin: ["BTC", "ETH"] is a different subscription from one created with coin: "BTC". To narrow a multi-coin set, unsubscribe the original coin array in full, then resubscribe with the smaller list.

Streamed messages

Every message has channel: "l4BookUpdates" and a data payload containing an Updates batch (this stream never emits a Snapshot). An Updates batch is emitted on each HyperCore block where the book for at least one subscribed coin changed. Each per-coin entry carries the block’s order_statuses (order lifecycle events) and book_diffs (per-order changes) for that coin, plus its own seq/prev_seq.

{
  "channel": "l4BookUpdates",
  "data": {
    "Updates": {
      "time": 1778865761768,
      "block_height": 997719813,
      "epoch": "466bf60f-bb7a-4591-89a3-a2660234fef5",
      "cursor": "997719813:1778865761768",
      "book_diffs": [
        {
          "coin": "BTC",
          "seq": 4229978,
          "prev_seq": 4229977,
          "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,
              "side": "B",
              "px": "79242.0",
              "coin": "BTC",
              "raw_book_diff": { "new": { "sz": "0.00867" } }
            }
          ]
        }
      ]
    }
  }
}

The raw_book_diff descriptor is one of:

{ "new": { "sz": "<size>" } } — a newly resting order.
{ "update": { "origSz": "<old>", "newSz": "<new>" } } — a resize (e.g. partial fill).
"remove" — the order left the book (filled or cancelled).

Bootstrapping & gap detection

l4BookUpdates is diff-only, so you build the order-level book yourself by seeding from a snapshot and applying diffs in order — the same mechanism a reference L4 client uses:

Subscribe to l4BookUpdates for your coin(s) and start buffering the incoming Updates.
Fetch a snapshot for each coin from the REST l4BookSnapshot info method. Note its height, epoch, and per-coin seq.
Discard already-applied diffs. Drop any buffered batch whose block_height is ≤ the snapshot’s height (the snapshot already includes those blocks). Equivalently, per coin, drop any diff whose seq ≤ the snapshot’s seq.
Verify the epoch. Every remaining diff’s epoch must equal the snapshot’s epoch. A different epoch means the stream reset after your snapshot — re-fetch the snapshot and restart.
Apply in order. For each coin, the first diff you apply should have prev_seq == snapshot.seq. For each raw_book_diff, insert (new), resize (update), or delete (remove) the order by oid.
Ongoing gap detection. Per coin, each diff’s prev_seq must equal the last seq you applied for that coin. On a mismatch (a dropped message) or an epoch change (a server reset), re-bootstrap that coin from step 2.

The seq/prev_seq are per coin, tracked within the current epoch. Compare them per coin, not globally across the batch.

Response fields

string

Always "l4BookUpdates".

object

Contains an Updates batch.

Show Updates (per-block diffs)

int

HyperCore block timestamp in milliseconds.

int

HyperCore block height these diffs were produced at. Align against the snapshot’s height.

string

Server generation (UUID). Regenerated when the stream resets (e.g. a server restart); a new epoch means your snapshot and buffered diffs are stale, so re-bootstrap. Matches the epoch in the l4BookSnapshot response.

string

A per-batch position marker, formatted "<block_height>:<time>". To recover from a disconnect, re-bootstrap from a fresh l4BookSnapshot (see Bootstrapping & gap detection) — the stream does not replay from this value.

array<object>

Per-coin entries. One entry per subscribed coin whose book changed at this block.

Show per-coin entry

string

Asset symbol this entry applies to.

int

Per-coin monotonic sequence for this entry, within the current epoch.

int

The seq of the previous entry for this coin. Must equal the last seq you applied for the coin (or the snapshot’s seq for the first entry after a bootstrap). A mismatch signals a gap.

array<object>

Order-lifecycle events for this coin 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 an l4Book snapshot entry. user inside this nested object is null because it duplicates the parent user.

array<object>

Per-order book changes for this coin at this block.

Show book_diff fields

string

Wallet address that owns the order.

int

Order id the diff applies to.

string

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

string

Price the order rests at (decimal string).

string

Asset symbol.

object | string

The change descriptor: { "new": { "sz" } }, { "update": { "origSz", "newSz" } }, or the string "remove".

l4Book

subscribe to GoldRush’s order-level Hyperliquid book - initial snapshot of every resting order plus per-block diffs with full metadata.

l4BookSnapshot

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

l2BookDiff2

subscribe to a diff-only L2 order book stream with per-coin sequence numbers and a server epoch for gap detection.

See all Hyperliquid endpoints: Overview hub · WebSocket API reference

Foundational API

Hyperliquid API

JSON-RPC

Service Keys

Ephemeral Keys

l4BookUpdates | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed messages

Bootstrapping & gap detection

Response fields

l4Book

l4BookSnapshot

l2BookDiff2

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed messages

​Bootstrapping & gap detection

​Response fields

​Related endpoints

l4Book

l4BookSnapshot

l2BookDiff2

Endpoint

Subscribe

Example

Unsubscribe

Streamed messages

Bootstrapping & gap detection

Response fields

Related endpoints