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

# SDK Compatibility

> Use existing Hyperliquid SDKs (nomeida/hyperliquid for JS, hyperliquid-python-sdk for Python) against the GoldRush WebSocket API by overriding the WebSocket URL.

The most popular Hyperliquid SDKs work against the GoldRush WebSocket API after a one-line URL override. Authentication is a `key` query parameter on the connection URL - no header injection is needed.

## JavaScript / TypeScript: [`nomeida/hyperliquid`](https://github.com/nomeida/hyperliquid)

### Install

<CodeGroup>
  ```bash npm theme={null}
  npm install hyperliquid
  ```

  ```bash yarn theme={null}
  yarn add hyperliquid
  ```
</CodeGroup>

### Configure

```typescript theme={null}
import { Hyperliquid } from "hyperliquid";

const sdk = new Hyperliquid({
  // Point at GoldRush - REST and WebSocket
  baseUrl: "https://hypercore.goldrushdata.com",
  wsUrl: `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
  // REST still needs the Authorization header
  headers: {
    Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`,
  },
});

// Existing subscription methods work unchanged
sdk.subscriptions.subscribeToL2Book("BTC", (book) => {
  console.log(book.coin, book.time, book.levels[0][0]);
});

sdk.subscriptions.subscribeToL2Book("ETH", (book) => {
  console.log(book.coin, book.time, book.levels[0][0]);
});
```

<Note>
  If your SDK version doesn't expose a `wsUrl` option, instantiate the WebSocket client manually and pass it to the SDK, or patch the constant the SDK uses. See the override fallback below.
</Note>

### Manual WebSocket fallback

When the SDK doesn't expose a `wsUrl` knob, bypass it and drive the raw socket yourself:

```typescript 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) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "l2Book") {
    // Hand off to your application
  }
});
```

## Python: [`hyperliquid-dex/hyperliquid-python-sdk`](https://github.com/hyperliquid-dex/hyperliquid-python-sdk)

### Install

```bash theme={null}
pip install hyperliquid-python-sdk
```

### Configure

```python theme={null}
import os
from hyperliquid.info import Info

# Point Info at GoldRush. skip_ws=False opens the WebSocket on init.
info = Info(
    base_url="https://hypercore.goldrushdata.com",
    skip_ws=False,
)

# Override the WebSocket URL on the underlying client so it includes the key
info.ws_manager.ws_url = (
    f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
)

# Inject the Authorization header for REST calls
info.session.headers.update({
    "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"
})

# Existing subscription methods work unchanged
def on_book(msg):
    print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1])

info.subscribe({"type": "l2Book", "coin": "BTC"}, on_book)
```

<Tip>
  The SDK's `Info` class manages both REST and WebSocket. If you only need WebSocket, you can skip the `session.headers.update(...)` line. If you only need REST, pass `skip_ws=True` instead.
</Tip>

## Verification

After cutover, confirm everything is wired correctly:

1. **Diff a known subscription** - subscribe to `l2Book` for the same coin against both endpoints; the streamed `channel` and `data` shape (keys, nesting, types) should match exactly.
2. **Confirm auth** - remove the `key` query parameter and confirm the WebSocket upgrade fails with HTTP `401`. If the socket opens, your request isn't reaching GoldRush.
3. **Confirm wildcard** - subscribe to `l2Book` **without** a `coin` and confirm you receive book snapshots for multiple assets. This call would be rejected on the public Hyperliquid WebSocket.

## Other SDKs

The pattern is the same for any WebSocket client: override the connection URL to `wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>`. If you run into a specific SDK that doesn't expose a URL override, [email us](mailto:support@covalenthq.com) - we'll publish a recipe.