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

<CodeGroup>
  ```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"}}
  ```
</CodeGroup>

### JavaScript / TypeScript

<CodeGroup>
  ```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()));
  });
  ```
</CodeGroup>

### Python

<CodeGroup>
  ```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())
  ```
</CodeGroup>

## 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](/goldrush-hyperliquid/websocket-api/limits#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](/goldrush-hyperliquid/websocket-api/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](/goldrush-foundational-api/authentication), the [Streaming API](/goldrush-streaming-api/authentication), the [Pipeline API](/goldrush-pipeline-api/authentication), and the [Info API](/goldrush-hyperliquid/info-api/overview). 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 Streaming, Pipeline, the Info API, and HyperEVM via the Foundational API.