Skip to main content

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.

Subscribe to a GoldRush-native order-level view of the Hyperliquid book. Unlike l2Book, which emits a full aggregated snapshot every tick, l4Book emits a single Snapshot of every resting order on subscribe and then per-block Updates carrying individual order_statuses and book_diffs. Each order in the stream includes its user, oid, cloid, orderType, tif, and trigger metadata - enough to reconstruct queue position, per-trader flow, and microstructure. This channel is not available on wss://api.hyperliquid.xyz/ws - it is exclusive to wss://hypercore.goldrushdata.com/ws.

​
Endpoint

wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>
​
key
string
required
Your GoldRush API key. Passed as a query parameter at connection time - no Authorization header is used.

​
Subscribe

Send this JSON message after the connection is established:
​
method
string
required
Always "subscribe".
​
subscription
object
required

​
Example

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

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

​
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

​
channel
string
Always "l4Book".
​
data
object
Contains exactly one of Snapshot or Updates.

​
Order object

The Order type appears inside Snapshot.levels[*][*] and Updates.order_statuses[*].order.
​
user
string | null
Wallet address that owns the order. null when the order is nested inside an order_status (the parent already carries it).
​
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.

​
Notes

  • 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.
  • coin is required. Unlike l2Book, 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. For aggregated {px, sz, n} snapshots without per-order detail, use l2Book.