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

# WebSocket API Migration Guide

> Move from the public Hyperliquid WebSocket to GoldRush by changing one URL. Step-by-step examples in wscat, JavaScript, and Python.

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

1. **URL** - replace `wss://api.hyperliquid.xyz/ws` with `wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_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

```bash Public Hyperliquid theme={null}
wscat -c wss://api.hyperliquid.xyz/ws

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

```bash GoldRush theme={null}
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

### JavaScript / TypeScript

```typescript Public Hyperliquid theme={null}
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()));
});
```

```typescript GoldRush theme={null}
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

```python Public Hyperliquid theme={null}
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())
```

```python GoldRush theme={null}
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](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/limits.md#wildcard-subscriptions).

### 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=<GOLDRUSH_API_KEY>` and the rest of the SDK works unchanged. See [SDK compatibility](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/sdk-compatibility.md) 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](https://goldrush.dev/docs/goldrush-foundational-api/authentication.md) and the [Info API](https://goldrush.dev/docs/goldrush-hyperliquid/info-api/overview.md). If you don't have one yet, [sign up here](https://goldrush.dev/platform/auth/register/).

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 the Info API and HyperEVM via the Foundational API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.