Hyperliquid WebSocket API

Critical Rules

WebSocket URL: wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY> (note: hypercore, not hyperliquid; auth is a ?key= query parameter, not an Authorization header).
Wire-compatible with wss://api.hyperliquid.xyz/ws for shared subscription types (e.g. l2Book).
No 1000-subscription-per-IP cap. Multiplex many subscriptions on one connection.
l2Book - aggregated price-level snapshots {px, sz, n}. coin is optional - omit it to stream every asset over a single subscription.
l4Book - GoldRush-native order-level stream with user, oid, cloid, tif, and trigger metadata per order. coin is required. Emits a single Snapshot on subscribe, then per-block Updates (order_statuses + book_diffs). Not available on the public Hyperliquid WebSocket.

Available Subscriptions

Channel	Subscription body	Returns
`l2Book`	`{"type":"l2Book","coin":"BTC"}` (or omit `coin`)	Full L2 book snapshot per tick with bids/asks aggregated by significant figures. Self-healing - every message is a complete snapshot.
`l4Book`	`{"type":"l4Book","coin":"BTC"}`	Initial `Snapshot` of every resting order, then per-block `Updates` with `order_statuses` (lifecycle) and `book_diffs` (per-order changes). GoldRush-native, no upstream equivalent.

// Subscribe
{"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}}

// Unsubscribe (same subscription body, method swapped)
{"method":"unsubscribe","subscription":{"type":"l2Book","coin":"BTC"}}

When to use which channel

Need	Use
Top-of-book, spread, depth-weighted mid, slippage / impact estimator	`l2Book`
Stream every asset on one subscription	`l2Book` (omit `coin`)
Queue position, per-user flow attribution, microstructure analytics	`l4Book`
Reconstruct an L2-style aggregated view but keep order-level detail	`l4Book` (aggregate client-side)
OHLCV candles instead of raw book state	Streaming API `ohlcvCandlesForPair` (see `streaming.md`)

The GoldRush Hyperliquid WebSocket API is a drop-in replacement for wss://api.hyperliquid.xyz/ws. Subscription payloads, channel names, and message shapes are byte-for-byte identical to the public Hyperliquid feed. The only difference is the connection URL - authentication is a required key query parameter, so no header changes are needed in your client.

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

Your GoldRush API key. Passed as a query parameter at connection time.

Comparison with the public Hyperliquid WebSocket

	Public WebSocket	GoldRush
URL	`wss://api.hyperliquid.xyz/ws`	`wss://hypercore.goldrushdata.com/ws?key=`
Auth	None	`key` query parameter (required)
Subscriptions per IP	1000	No cap
Wire compatibility	n/a (it’s the source)	Byte-for-byte
Available channels	See Hyperliquid Docs	See Available subscriptions

Available subscriptions

Channel	Subscription body	Returns
`l2Book`	`{"type": "l2Book", "coin": "BTC"}`	Real-time L2 order book snapshots - bids and asks aggregated by significant figures. `coin` is optional - omit it to stream every asset on one subscription.
`l4Book`	`{"type": "l4Book", "coin": "BTC"}`	GoldRush-native order-level book stream - initial `Snapshot` of every resting order plus per-block `Updates` with `order_statuses` and `book_diffs`. Exposes `user`, `oid`, `cloid`, `tif`, and trigger metadata per order. `coin` is required. Not available on the public Hyperliquid WebSocket.

Limits

No 1000-subscription-per-IP cap. On l2Book, filter parameters are optional - omit coin to stream the full L2 book across every asset on a single subscription. l4Book requires coin and is one-asset-per-subscription. See Limits & Connections for details. For richer real-time analytics (pre-decoded HyperCore fills, liquidations, vault events, OHLCV across every HIP-3/HIP-4 market), pair the WebSocket with the GraphQL Streaming API.

Moving from the public Hyperliquid WebSocket to GoldRush is one change:

URL - replace wss://api.hyperliquid.xyz/ws with wss://hypercore.goldrushdata.com/ws?key=.

That’s it. Subscription payloads, channel names, and the streamed message shape are byte-for-byte identical. Authentication is a required key query parameter, so no header swap is needed in your client.

Side-by-side

wscat

Public Hyperliquid

wscat -c wss://api.hyperliquid.xyz/ws

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

GoldRush

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

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

JavaScript / TypeScript

Public Hyperliquid

import WebSocket from "ws";

const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

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

ws.on("message", (raw) => {
  console.log(JSON.parse(raw.toString()));
});

GoldRush

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: "l2Book", coin: "BTC" },
  }));
});

ws.on("message", (raw) => {
  console.log(JSON.parse(raw.toString()));
});

Python

Public Hyperliquid

import asyncio, json
import websockets

async def main():
    async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "BTC"},
        }))
        async for raw in ws:
            print(json.loads(raw))

asyncio.run(main())

GoldRush

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": "l2Book", "coin": "BTC"},
        }))
        async for raw in ws:
            print(json.loads(raw))

asyncio.run(main())

Behavioral notes

Things to be aware of when you cut over.

Stream payloads are byte-equal, modulo live drift

The channel name and data shape match Hyperliquid byte-for-byte - same keys, same nesting, same value types. Numeric fields update independently on each side, so a price level may differ by tens of milliseconds, but the schema is identical.

Auth errors close the connection

A missing or invalid key query param returns HTTP 401 on the upgrade handshake, so the WebSocket never opens. Public Hyperliquid has no auth and never rejects the handshake.

Filter parameters are optional on GoldRush

Parameters that the public Hyperliquid WebSocket requires (e.g. coin on l2Book) are optional on GoldRush. Omit them to stream the entire channel on a single subscription instead of fanning out one subscription per asset. See Limits.

Existing SDKs work after a `wsUrl` override

Most popular Hyperliquid SDKs accept a WebSocket base URL override - point them at wss://hypercore.goldrushdata.com/ws?key= and the rest of the SDK works unchanged. See SDK compatibility for the override snippets.

Authentication

The WebSocket API uses your standard GoldRush API key, passed as a key query parameter at connection time. The same key works against the Foundational API, the Streaming API, the Pipeline API, and the Info API. If you don’t have one yet, sign up here. Never hardcode keys in source. Use environment variables or a secrets manager.

What you gain

No subscription cap. No 1000-subscription-per-IP limit; multiplex hundreds of subscriptions on a single connection.
Wildcard subscriptions. Omit filter parameters to stream the entire channel - e.g. the full L2 order book across every asset on one subscription.
One key for everything Hyperliquid. The same API key unlocks Streaming, Pipeline, the Info API, and HyperEVM via the Foundational API.

The most popular Hyperliquid SDKs work against the GoldRush WebSocket API after a one-line URL override. Authentication is a key query parameter on the connection URL - no header injection is needed.

JavaScript / TypeScript: `nomeida/hyperliquid`

Install

npm

npm install hyperliquid

yarn

yarn add hyperliquid

Configure

import { Hyperliquid } from "hyperliquid";

const sdk = new Hyperliquid({
  // Point at GoldRush - REST and WebSocket
  baseUrl: "https://hypercore.goldrushdata.com",
  wsUrl: `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
  // REST still needs the Authorization header
  headers: {
    Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`,
  },
});

// Existing subscription methods work unchanged
sdk.subscriptions.subscribeToL2Book("BTC", (book) => {
  console.log(book.coin, book.time, book.levels[0][0]);
});

sdk.subscriptions.subscribeToL2Book("ETH", (book) => {
  console.log(book.coin, book.time, book.levels[0][0]);
});

Note: If your SDK version doesn’t expose a wsUrl option, instantiate the WebSocket client manually and pass it to the SDK, or patch the constant the SDK uses. See the override fallback below.

Manual WebSocket fallback

When the SDK doesn’t expose a wsUrl knob, bypass it and drive the raw socket yourself:

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: "l2Book", coin: "BTC" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "l2Book") {
    // Hand off to your application
  }
});

Python: `hyperliquid-dex/hyperliquid-python-sdk`

Install

pip install hyperliquid-python-sdk

Configure

import os
from hyperliquid.info import Info

# Point Info at GoldRush. skip_ws=False opens the WebSocket on init.
info = Info(
    base_url="https://hypercore.goldrushdata.com",
    skip_ws=False,
)

# Override the WebSocket URL on the underlying client so it includes the key
info.ws_manager.ws_url = (
    f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
)

# Inject the Authorization header for REST calls
info.session.headers.update({
    "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"
})

# Existing subscription methods work unchanged
def on_book(msg):
    print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1])

info.subscribe({"type": "l2Book", "coin": "BTC"}, on_book)

Tip: The SDK’s Info class manages both REST and WebSocket. If you only need WebSocket, you can skip the session.headers.update(...) line. If you only need REST, pass skip_ws=True instead.

Verification

After cutover, confirm everything is wired correctly:

Diff a known subscription - subscribe to l2Book for the same coin against both endpoints; the streamed channel and data shape (keys, nesting, types) should match exactly.
Confirm auth - remove the key query parameter and confirm the WebSocket upgrade fails with HTTP 401. If the socket opens, your request isn’t reaching GoldRush.
Confirm wildcard - subscribe to l2Book without a coin and confirm you receive book snapshots for multiple assets. This call would be rejected on the public Hyperliquid WebSocket.

Other SDKs

The pattern is the same for any WebSocket client: override the connection URL to wss://hypercore.goldrushdata.com/ws?key=. If you run into a specific SDK that doesn’t expose a URL override, email us - we’ll publish a recipe.

No subscription cap

The GoldRush Hyperliquid WebSocket API has no per-IP, per-key, or per-connection subscription cap. The 1000-subscription-per-IP limit on the public Hyperliquid WebSocket does not apply. You can:

Open as many concurrent subscriptions as your client supports.
Multiplex hundreds of l2Book subscriptions on a single connection.
Track every active wallet, market, and asset from one process.

Wildcard subscriptions

Filter parameters that the public Hyperliquid WebSocket requires are optional on GoldRush. Omit them to stream the entire channel on one subscription instead of fanning out one subscription per asset.

Channel	Public Hyperliquid	GoldRush
`l2Book`	`coin` required - one subscription per asset	`coin` optional - omit it to stream the full L2 order book across every asset on a single subscription

So a single connection can stream Hyperliquid’s full live book state without any client-side fan-out logic.

How streaming works

Messages are pushed directly from a live Hyperliquid ingestion pipeline - no polling, no cache delay. Latency from upstream Hyperliquid event to your client is dominated by network round-trip from our Tokyo nodes.

Channel	Push trigger
`l2Book`	Every L2 update on the subscribed coin (or every coin, if wildcard).

Connection management

You’re not rate-limited, but a few client-side defaults are worth tuning.

Behavior	Recommended client setting
Reconnect	On unexpected close, reconnect with exponential backoff capped at ~30 seconds. Re-send your subscription messages after the new socket opens.
Heartbeat	Send an application-level `ping` every 30 seconds. The server replies with `pong`. Most WebSocket libraries handle this automatically; verify yours does.
Max message size	L2 book snapshots for wildcard subscriptions can exceed 1 MB. Raise your client’s `maxPayload` (Node `ws` library) or `max_size` (Python `websockets`) if you’re receiving truncated messages.
Backpressure	If your handler can’t keep up with incoming messages, your client buffer will fill. Drain to a queue or downstream consumer; don’t block the read loop on application work.

Reconnect sketch

TypeScript

import WebSocket from "ws";

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

  ws.on("open", () => {
    ws.send(JSON.stringify({
      method: "subscribe",
      subscription: { type: "l2Book" }, // wildcard - all assets
    }));
  });

  ws.on("close", () => setTimeout(connect, Math.min(30_000, backoff *= 2)));
  ws.on("error", () => ws.close());
  ws.on("message", handle);
}

let backoff = 1_000;
connect();

Python

import asyncio, json, os
import websockets

async def consume():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    backoff = 1
    while True:
        try:
            async with websockets.connect(uri, max_size=8 * 1024 * 1024, ping_interval=30) as ws:
                backoff = 1
                await ws.send(json.dumps({
                    "method": "subscribe",
                    "subscription": {"type": "l2Book"},  # wildcard
                }))
                async for raw in ws:
                    handle(json.loads(raw))
        except Exception:
            await asyncio.sleep(min(30, backoff))
            backoff *= 2

asyncio.run(consume())

Watch out for client-side limits

GoldRush has no caps, but the rest of your stack might:

OS file descriptor limits - if you’re opening many connections in parallel, raise ulimit -n.
Reverse proxy idle timeouts - if you’re terminating WS through nginx, HAProxy, or a cloud load balancer, set the idle timeout above your heartbeat interval (typically 60 seconds minimum).
Browser concurrency - browsers limit WebSocket connections per origin; one connection multiplexing many subscriptions is always preferable to many connections.

Network and TLS

HTTP/1.1 Upgrade to WSS is supported (standard WebSocket handshake).
TLS 1.2+ required.
Compression (permessage-deflate) is negotiated when offered by the client.

Need higher guarantees?

Enterprise SLA, dedicated capacity, regional pinning, and on-prem options are all available. Email sales.

WebSocket API Reference

L2 Order Book

Subscribe to a continuous stream of L2 order book snapshots for any Hyperliquid perp or spot asset. The payload is wire-equal to the public Hyperliquid l2Book WebSocket subscription - same channel name, same levels shape, same aggregation parameters. Point your client at wss://hypercore.goldrushdata.com/ws?key= and the rest of your code stays the same.

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

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:

Parameter	Type	Required	Description
`method`	`string`	Yes	Always `"subscribe"`.
`subscription`	`object`	Yes	__RESPONSE_ROW__type string Always `"l2Book"`. __RESPONSE_ROW__coin string Asset symbol - e.g. `"BTC"`, `"ETH"`, `"@107"` for spot pairs. For HIP-3 markets, include the deployer prefix. Omit to receive snapshots for all assets in the order book. __RESPONSE_ROW__nSigFigs int Significant figures used for price aggregation. One of `2`, `3`, `4`, `5`, or `null` for full precision. Defaults to `null`. __RESPONSE_ROW__mantissa int When `nSigFigs` is 5, controls the mantissa rounding. One of `1`, `2`, or `5`. Not allowed for other `nSigFigs` values.

Example

wscat

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

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

TypeScript

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: "l2Book", coin: "BTC" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "l2Book") {
    const { coin, time, levels: [bids, asks] } = msg.data;
    console.log(coin, time, "top bid:", bids[0], "top ask:", asks[0]);
  }
});

Python

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": "l2Book", "coin": "BTC"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "l2Book":
                print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1])

asyncio.run(main())

Unsubscribe

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

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

Streamed message

Each message has channel: "l2Book" and a data payload with the current book snapshot for the subscribed coin.

{
  "channel": "l2Book",
  "data": {
    "coin": "BTC",
    "time": 1762450000123,
    "block_height": 996629014,
    "levels": [
      [
        { "px": "68210.0", "sz": "1.2345", "n": 3 },
        { "px": "68209.5", "sz": "4.5670", "n": 5 },
        { "px": "68209.0", "sz": "2.1100", "n": 2 }
      ],
      [
        { "px": "68215.0", "sz": "0.8900", "n": 2 },
        { "px": "68215.5", "sz": "3.4500", "n": 4 },
        { "px": "68216.0", "sz": "1.2300", "n": 1 }
      ]
    ]
  }
}

Field	Type	Description
`channel`	`string`	Always `"l2Book"`.
`data`	`object`
`data.coin`	`string`	Asset symbol the snapshot belongs to.
`data.time`	`int`	HyperCore block timestamp in milliseconds.
`data.block_height`	`int`	HyperCore block height the snapshot was taken at.
`data.levels`	`array>`	Tuple `[bids, asks]`. Each side is an array of price levels in best-first order. __RESPONSE_ROW__px string Price for this level (decimal string). __RESPONSE_ROW__data.sz string Aggregate size resting at this level (decimal string, base units). __RESPONSE_ROW__data.n int Number of orders aggregated into this level.

Notes

Wire-compatible with wss://api.hyperliquid.xyz/ws l2Book subscriptions - same channel name, same levels shape.
coin is optional on GoldRush. Omit it to stream the entire L2 order book across every asset on a single subscription. The public Hyperliquid API requires coin and locks each subscription to one asset at a time.
No 1000-subscription-per-IP cap - multiplex hundreds of l2Book subscriptions on a single connection.
For OHLCV candles instead of raw book state, use the Streaming API OHLCV streams.

L4 Order Book Diff

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=

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:

Parameter	Type	Required	Description
`method`	`string`	Yes	Always `"subscribe"`.
`subscription`	`object`	Yes	__RESPONSE_ROW__type string Always `"l4Book"`. __RESPONSE_ROW__coin string 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

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

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

TypeScript

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);
  }
});

Python

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

Field	Type	Description
`channel`	`string`	Always `"l4Book"`.
`data`	`object`	Contains exactly one of `Snapshot` or `Updates`.
`data.coin`	`string`	Asset symbol the snapshot belongs to.
`data.time`	`int`	HyperCore block timestamp in milliseconds.
`data.block_height`	`int`	HyperCore block height the snapshot was taken at.
`data.levels`	`array>`	Tuple `[bids, asks]`. Each side is an array of individual Order objects (see below), in queue order at their respective price.
`data.time`	`int`	HyperCore block timestamp in milliseconds.
`data.block_height`	`int`	HyperCore block height.
`data.order_statuses`	`array`	Order lifecycle events at this block. __RESPONSE_ROW__time string ISO-8601 timestamp with nanosecond precision. __RESPONSE_ROW__data.user string Wallet address that owns the order. __RESPONSE_ROW__data.status string Lifecycle status (e.g. `"open"`). __RESPONSE_ROW__data.order Order The order, in the same shape as a snapshot entry. `user` inside this nested object is `null` because it duplicates the parent `user`. __RESPONSE_ROW__book_diffs array Per-order book changes at this block. __RESPONSE_ROW__book_diffs.user string Wallet address that owns the order. __RESPONSE_ROW__book_diffs.oid int Order id the diff applies to. __RESPONSE_ROW__book_diffs.px string Price level the diff applies to (decimal string). __RESPONSE_ROW__book_diffs.coin string Asset symbol. __RESPONSE_ROW__book_diffs.raw_book_diff object The change descriptor. Observed shape: `{ "new": { "sz": "" } }` 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.

Field	Type	Description
`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.

Recipes

The l2Book channel on wss://hypercore.goldrushdata.com/ws?key= is wire-equal to the public Hyperliquid feed but with coin made optional and the per-IP subscription cap removed. This recipe shows how to turn that stream into common trading and analytics building blocks. For the raw subscription shape see the l2Book reference; for the connection model see the WebSocket API overview.

What you get

Complete snapshots, not diffs. Every l2Book message contains the current time, coin, and a full [bids, asks] tuple in best-first order, with px / sz / n per level. Consume each message in isolation - no sequence numbers to track, no diff replay buffer, no REST snapshot to bootstrap.
Self-healing on packet loss. Drop a message, reconnect mid-session, or restart your process - the next message arrives with the full book state, so your in-memory view is correct on the very next tick.
Upstream-compatible aggregation knobs. nSigFigs accepts 2, 3, 4, 5, or null (full precision). mantissa accepts 1, 2, or 5, and is only valid when nSigFigs is 5.
Wildcard coverage. Omit coin to stream every asset’s book over a single subscription, instead of fanning out one subscription per asset.

The pattern below keeps a Map in memory. Each incoming message replaces the entry for its coin, so the map is always current and never needs reconciliation.

TypeScript

import WebSocket from "ws";

type Level = { px: string; sz: string; n: number };
type Snapshot = { time: number; bids: Level[]; asks: Level[] };

const books = new Map();

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

ws.on("open", () => {
  // Omit `coin` to stream every asset on one subscription.
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "l2Book", coin: "BTC" },
  }));
});

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

  const { coin, time, levels: [bids, asks] } = msg.data;
  books.set(coin, { time, bids, asks });

  console.log(coin, time, "bid:", bids[0]?.px, "ask:", asks[0]?.px);
});

Python

import asyncio, json, os
import websockets

books: dict[str, dict] = {}

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": "l2Book", "coin": "BTC"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l2Book":
                continue
            data = msg["data"]
            coin, time = data["coin"], data["time"]
            bids, asks = data["levels"]
            books[coin] = {"time": time, "bids": bids, "asks": asks}
            print(coin, time, "bid:", bids[0]["px"], "ask:", asks[0]["px"])

asyncio.run(main())

Patterns

Top-of-book tracker

Read bids[0] and asks[0] directly from each message. The spread is Number(asks[0].px) - Number(bids[0].px). No state required - every message is self-contained, so a single-line transformation gives you a live ticker.

Depth-weighted mid quote

Sum px * sz across the first K levels on each side, then average. This produces a fair-value mid that’s robust to thin top-of-book liquidity, and is useful as a hedging or pricing reference.

TypeScript

function depthWeightedMid(snap: Snapshot, k = 5): number {
  const side = (levels: Level[]) => {
    let num = 0, den = 0;
    for (const { px, sz } of levels.slice(0, k)) {
      const p = Number(px), s = Number(sz);
      num += p * s;
      den += s;
    }
    return den > 0 ? num / den : NaN;
  };
  return (side(snap.bids) + side(snap.asks)) / 2;
}

Slippage / impact estimator

Walk levels on the relevant side until cumulative sz covers the requested notional. Return the size-weighted average fill price - the difference vs the top-of-book is your expected slippage.

TypeScript

function estimateFill(levels: Level[], targetSize: number): number {
  let remaining = targetSize, notional = 0;
  for (const { px, sz } of levels) {
    const take = Math.min(remaining, Number(sz));
    notional += take * Number(px);
    remaining -= take;
    if (remaining  0 ? NaN : notional / targetSize;
}

// Buying 10 BTC against current asks:
const avgFill = estimateFill(books.get("BTC")!.asks, 10);

Liquidity heatmap

On each message, append [time, coin, side, px, sz] rows to your time-series store (Clickhouse, TimescaleDB, Parquet). Because every message is a complete snapshot of the top levels, the heatmap rebuilds correctly from any contiguous slice of history - you don’t need a separate “initial book” record to seed the visualisation.

Handling reconnects

Reconnect logic is a one-liner: open a new socket and resend the same subscribe payload. The first message after subscribe is a full book snapshot, so your books map is correct on the next tick - there’s nothing to replay, nothing to buffer, and no sequence numbers to reconcile against a separately-fetched REST snapshot.

TypeScript

function connect() {
  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: "l2Book", coin: "BTC" },
  })));
  ws.on("close", () => setTimeout(connect, 1000));
  return ws;
}

l2Book API reference - full subscription and message schema.
WebSocket API overview - endpoint URL, auth, and limits.
clearinghouseState - pair the live book with per-account position and margin state.
OHLCV pairs stream - candles instead of raw book state.

The l4Book channel on wss://hypercore.goldrushdata.com/ws?key= is a GoldRush-exclusive stream - it has no equivalent on wss://api.hyperliquid.xyz/ws. After subscribing, the server sends a single Snapshot of every resting order, then per-block Updates carrying lifecycle events and per-order book changes. Each order arrives with its user, oid, cloid, tif, and trigger metadata, so you can reconstruct queue position, attribute flow to specific wallets, and run microstructure analytics that l2Book’s aggregated {px, sz, n} view hides. For the raw subscription shape see the l4Book reference; for the connection model see the WebSocket API overview.

What you get

Per-order visibility. Every level in the snapshot is an individual order keyed by oid, with user, cloid, tif, orderType, and trigger metadata attached. l2Book only exposes {px, sz, n} per price level.
Snapshot + diff transport. One full Snapshot on subscribe, then per-block Updates containing order_statuses (lifecycle events) and book_diffs (per-order changes). Apply diffs to local state.
Per-block cadence. Updates fire on each HyperCore block where the book for the subscribed coin changed. The time and block_height fields anchor each message to a specific block.
GoldRush-exclusive. Not available on the public Hyperliquid WebSocket - this stream surfaces user attribution and per-order metadata the public feed never exposes.
One coin per subscription. Unlike l2Book, coin is required. To cover multiple assets, open one l4Book subscription per asset on the same connection.

The pattern below keeps a Map per coin. The snapshot seeds the map; each Updates message applies book_diffs against it. Reconnects drop the map and re-seed from the next snapshot.

TypeScript

import WebSocket from "ws";

type Order = {
  user: string | null;
  coin: string;
  side: "B" | "A";
  limitPx: string;
  sz: string;
  oid: number;
  timestamp: number;
  triggerCondition: string;
  isTrigger: boolean;
  triggerPx: string;
  isPositionTpsl: boolean;
  reduceOnly: boolean;
  orderType: string;
  tif: string;
  cloid: string | null;
};

const orders = new Map();

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) {
    orders.clear();
    const [bids, asks] = msg.data.Snapshot.levels;
    for (const o of [...bids, ...asks]) orders.set(o.oid, o);
    console.log("seeded from snapshot:", orders.size, "orders");
    return;
  }

  if (msg.data.Updates) {
    const { order_statuses, book_diffs } = msg.data.Updates;

    for (const s of order_statuses) {
      // Re-attach the parent `user` since the nested order has user=null.
      orders.set(s.order.oid, { ...s.order, user: s.user });
    }

    for (const d of book_diffs) {
      const existing = orders.get(d.oid);
      if (!existing) continue;
      if (d.raw_book_diff.new) {
        orders.set(d.oid, { ...existing, sz: d.raw_book_diff.new.sz });
      }
      // Other raw_book_diff shapes (deletes, modifies) belong here.
    }
  }
});

Python

import asyncio, json, os
import websockets

orders: dict[int, dict] = {}

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:
                orders.clear()
                bids, asks = data["Snapshot"]["levels"]
                for o in bids + asks:
                    orders[o["oid"]] = o
                print("seeded from snapshot:", len(orders), "orders")
                continue

            if "Updates" in data:
                for s in data["Updates"]["order_statuses"]:
                    o = {**s["order"], "user": s["user"]}
                    orders[o["oid"]] = o
                for d in data["Updates"]["book_diffs"]:
                    existing = orders.get(d["oid"])
                    if not existing:
                        continue
                    new = d["raw_book_diff"].get("new")
                    if new:
                        existing["sz"] = new["sz"]

asyncio.run(main())

Patterns

Track individual orders by `oid`

oid is the Hyperliquid order id, stable for the lifetime of the order - use it as the primary key in your local map. cloid is the client-supplied id (may be null); index on it when you need to correlate fills back to a specific trading bot’s instructions.

Per-user flow attribution

Every order entry carries user. Group orders by wallet to surface market-maker behavior, identify spoofing patterns, or build a per-trader heatmap of resting size. Pair this with clearinghouseState for per-user position and margin context.

TypeScript

function sizeByUser(orders: Map) {
  const totals = new Map();
  for (const o of orders.values()) {
    if (!o.user) continue;
    totals.set(o.user, (totals.get(o.user) ?? 0) + Number(o.sz));
  }
  return totals;
}

Reconstruct aggregated price levels

If a downstream consumer expects an l2Book-style aggregated view, sum sz across all orders sharing a limitPx on the same side. Going the other way isn’t possible - l2Book collapses the per-order detail you’d lose.

TypeScript

function aggregate(orders: Map) {
  const bids = new Map();
  const asks = new Map();
  for (const o of orders.values()) {
    const book = o.side === "B" ? bids : asks;
    book.set(o.limitPx, (book.get(o.limitPx) ?? 0) + Number(o.sz));
  }
  return { bids, asks };
}

Handling reconnects

On reconnect, resend the same subscribe payload. The first message back is always a fresh Snapshot - drop your local orders map and re-seed from it. Do not attempt to replay missed Updates - the snapshot is authoritative and supersedes anything you held before the disconnect.

TypeScript

function connect() {
  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("close", () => {
    orders.clear();
    setTimeout(connect, 1000);
  });
  return ws;
}

l4Book API reference - full subscription, snapshot, and update schema.
l2Book reference - aggregated price-level snapshots when per-order detail isn’t needed.
WebSocket API overview - endpoint URL, auth, and limits.
clearinghouseState - pair per-user resting orders with position and margin state.

Learn about GoldRush

Components

Documentation Index

​Hyperliquid WebSocket API

​Critical Rules

​Available Subscriptions

​Subscribe / Unsubscribe Pattern

​When to use which channel

​Endpoint

​Comparison with the public Hyperliquid WebSocket

​Available subscriptions

​Limits

​Side-by-side

​wscat

​JavaScript / TypeScript

​Python

​Behavioral notes

​Stream payloads are byte-equal, modulo live drift

​Auth errors close the connection

​Filter parameters are optional on GoldRush

​Existing SDKs work after a wsUrl override

​Authentication

​What you gain

​JavaScript / TypeScript: nomeida/hyperliquid

​Install

​Configure

​Manual WebSocket fallback

​Python: hyperliquid-dex/hyperliquid-python-sdk

​Install

​Configure

​Verification

​Other SDKs

​No subscription cap

​Wildcard subscriptions

​How streaming works

​Connection management

​Reconnect sketch

​Watch out for client-side limits

​Network and TLS

​Need higher guarantees?

​WebSocket API Reference

​L2 Order Book

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Notes

​L4 Order Book Diff

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed messages

​Initial snapshot

​Incremental updates

​Response fields

​Order object

​Notes

​Recipes

​What you get

​Subscribe and hold book state

​Patterns

​Top-of-book tracker

​Depth-weighted mid quote

​Slippage / impact estimator

​Liquidity heatmap

​Handling reconnects

​Related

​What you get

​Subscribe and maintain book state

​Patterns

​Track individual orders by oid

​Per-user flow attribution

​Reconstruct aggregated price levels

​Handling reconnects

​Related

Hyperliquid WebSocket API

Critical Rules

Available Subscriptions

Subscribe / Unsubscribe Pattern

When to use which channel

Endpoint

Comparison with the public Hyperliquid WebSocket

Available subscriptions

Limits

Side-by-side

wscat

JavaScript / TypeScript

Python

Behavioral notes

Stream payloads are byte-equal, modulo live drift

Auth errors close the connection

Filter parameters are optional on GoldRush

Existing SDKs work after a `wsUrl` override

Authentication

What you gain

JavaScript / TypeScript: `nomeida/hyperliquid`

Install

Configure

Manual WebSocket fallback

Python: `hyperliquid-dex/hyperliquid-python-sdk`

Install

Configure

Verification

Other SDKs

No subscription cap

Wildcard subscriptions

How streaming works

Connection management

Reconnect sketch

Watch out for client-side limits

Network and TLS

Need higher guarantees?

WebSocket API Reference

L2 Order Book

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Notes

L4 Order Book Diff

Endpoint

Subscribe

Example

Unsubscribe

Streamed messages

Initial snapshot

Incremental updates

Response fields

Order object

Notes

Recipes

What you get

Subscribe and hold book state

Patterns

Top-of-book tracker

Depth-weighted mid quote

Slippage / impact estimator

Liquidity heatmap

Handling reconnects

Related

What you get

Subscribe and maintain book state

Patterns

Track individual orders by `oid`

Per-user flow attribution

Reconstruct aggregated price levels

Handling reconnects

Related