> ## 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.

# Connect & Migrate

> Open your first Uniblock Hyperliquid WebSocket connection, and switch from the public HyperCore WebSocket by changing one URL.

This guide walks through opening a connection, subscribing, and — if you're already on Hyperliquid's public WebSocket — migrating with a one-line change.

<Info>
  Grab your API key from the
  [Uniblock dashboard](https://dashboard.uniblock.dev).
</Info>

## 1. Connect

Open a WebSocket to Uniblock's endpoint and 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>
  Confirm your credentials before opening a stream:
  `curl 'https://websocket.uniblock.dev/goldrush/validate' --header 'X-API-KEY: YOUR_API_KEY'`
</Tip>

## 2. Subscribe

Send a `subscribe` message once the connection is open:

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

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

See the [WebSocket overview](/guides/hyperliquid/websockets/overview) for every channel and its payload shape.

## Migrate from the public WebSocket

Switching from Hyperliquid's public HyperCore WebSocket is a one-line change — the subscribe/unsubscribe message format is the same.

|                      | Public Hyperliquid             | Uniblock                                |
| -------------------- | ------------------------------ | --------------------------------------- |
| **URL**              | `wss://api.hyperliquid.xyz/ws` | `wss://websocket.uniblock.dev/goldrush` |
| **Auth**             | none                           | `X-API-KEY` header or `apiKey` query    |
| **Subscription cap** | 1000 per IP                    | none                                    |
| **Message format**   | unchanged                      | unchanged                               |

```javascript theme={null}
// Before
const ws = new WebSocket("wss://api.hyperliquid.xyz/ws");

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

<Note>
  Uniblock adds GoldRush-native channels the public feed doesn't have —
  `l2BookDiff`, `l4Book`, and `liquidationFills`. Once migrated you can drop any
  logic that worked around the 1000-subscription cap.
</Note>

## 3. Keep the connection healthy

* **Keep-alive:** send a ping every 30–60 seconds to avoid idle timeouts.
* **Reconnect with backoff:** on disconnect, re-open and re-send every subscription using exponential backoff. On reconnect, discard local order book state and re-seed from the fresh snapshots rather than replaying missed updates.
* **Scope subscriptions:** subscribe per `coin` rather than the wildcard stream when you only need a few assets — wildcard is billed at a much higher rate.

## Next steps

<CardGroup cols={3}>
  <Card title="L2 Order Book" icon="layer-group" href="/guides/hyperliquid/websockets/l2-book" />

  <Card title="L2 Book Diff" icon="wave-square" href="/guides/hyperliquid/websockets/l2-book-diff" />

  <Card title="L4 Order Book" icon="list-ol" href="/guides/hyperliquid/websockets/l4-book" />
</CardGroup>