> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniblock.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming Hyperliquid with WebSockets

> Consume Hyperliquid HyperCore order book streams in real time through Uniblock’s GoldRush WebSocket.

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](https://goldrush.mintlify.app/api-reference/hyperliquid-websocket/l2-book-diff)
feed.

<Info>
  New to Hyperliquid's architecture? Read
  [HyperCore vs. HyperEVM](/guides/quickstart-guides/hypercore-vs-hyperevm)
  first — this guide covers the HyperCore side (order book data), not the
  EVM JSON-RPC side.
</Info>

## 1. Connect

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

```javascript theme={null}
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");
});
```

<Tip>
  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'`
</Tip>

## 2. Subscribe to the order book

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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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`,
  `userNonFundingLedgerUpdates` — account and venue event streams.

See the [GoldRush provider reference](/reference/websockets/providers/websockets-goldrush)
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.

## Resources

* [GoldRush provider reference](/reference/websockets/providers/websockets-goldrush)
* [GoldRush Hyperliquid WebSocket docs](https://goldrush.mintlify.app/api-reference/hyperliquid-websocket/l2-book-diff)
* [HyperCore vs. HyperEVM](/guides/quickstart-guides/hypercore-vs-hyperevm)