Streaming Hyperliquid with WebSockets

Hyperliquid’s HyperCore runs the native order book that powers its perps and spot markets. You can’t run a HyperCore node yourself, so the way to get real-time order book data is over a WebSocket. Uniblock exposes this through the GoldRush WebSocket: one connection, authenticated with your Uniblock API key, streaming Hyperliquid’s GoldRush HyperCore feed.

New to Hyperliquid’s architecture? Read HyperCore vs. HyperEVM first, since this guide covers the HyperCore side (order book data), not the EVM JSON-RPC side.

1. Connect

Open a WebSocket to Uniblock’s GoldRush endpoint. Authenticate with the X-API-KEY header (recommended) or an apiKey query parameter.

import WebSocket from "ws";

const ws = new WebSocket("wss://websocket.uniblock.dev/goldrush", {
  headers: { "X-API-KEY": "YOUR_API_KEY" },
});

ws.on("open", () => {
  console.log("Connected to Hyperliquid via Uniblock");
});

You can confirm your credentials before opening a stream by calling the validation endpoint: curl 'https://websocket.uniblock.dev/goldrush/validate' --header 'X-API-KEY: YOUR_API_KEY'

Send a subscribe message once the connection is open. The example below subscribes to l2BookDiff (lightweight per-block order book diffs) for a single asset.

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

Pass a single asset ("HYPE") or an array (["HYPE", "BTC"]) as coin.
Omit coin to stream all assets, but note the wildcard stream is billed at a much higher per-minute rate.

3. Handle snapshot and diff messages

For l2BookDiff, the first message per coin is a full Snapshot; subsequent messages are per-block Updates containing only the changed levels.

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

  if (msg.data.Snapshot) {
    const { coin, levels } = msg.data.Snapshot;
    console.log(`Snapshot for ${coin}`, levels); // [bids, asks]
  } else if (msg.data.Updates) {
    for (const diff of msg.data.Updates.book_diffs) {
      // Each level: { px: price, sz: size, n: order count }.
      // A level with sz === "0" means that price level was removed.
      console.log(`Diff for ${diff.coin}`, diff.levels);
    }
  }
});

Apply each diff on top of your local copy of the book: replace the level at px with the new sz/n, and delete the level when sz is "0".

4. Unsubscribe

Stop a stream by sending an unsubscribe message with the exact same subscription body you subscribed with. Billing for that subscription stops as soon as it’s removed.

ws.send(
  JSON.stringify({
    method: "unsubscribe",
    subscription: { type: "l2BookDiff", coin: "HYPE" },
  }),
);

Other subscription types

l2BookDiff is one of several HyperCore streams available on the same connection. Swap the type (and, for account streams, follow GoldRush’s per-type payload) to subscribe to:

l2Book: full L2 order book snapshots and updates.
l4Book: full per-order (L4) book.
userFills, orderUpdates, liquidationFills, allFills, builderFills, builderLiquidations, userNonFundingLedgerUpdates: account and venue event streams.

See the GoldRush provider reference for the full type list and per-subscription CU pricing.

Best practices

Keep-alive: send a ping every 30–60 seconds to avoid idle timeouts.
Reconnect with backoff: on disconnect, re-open and re-send your subscriptions using exponential backoff.
Scope your subscriptions: subscribe per coin instead of the wildcard stream when you only need a handful of assets; it’s dramatically cheaper.

Quickstart

Guides

Hyperliquid API

Streaming Hyperliquid with WebSockets

1. Connect

3. Handle snapshot and diff messages

4. Unsubscribe

Other subscription types

Best practices

Resources

​1. Connect

​2. Subscribe to the order book

​3. Handle snapshot and diff messages

​4. Unsubscribe

​Other subscription types

​Best practices

​Resources

1. Connect

2. Subscribe to the order book

3. Handle snapshot and diff messages

4. Unsubscribe

Other subscription types

Best practices

Resources