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

Install

npm

npm install hyperliquid

Configure

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]);
});

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.

Manual WebSocket fallback

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

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

Install

pip install hyperliquid-python-sdk

Configure

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)

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.

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 - we’ll publish a recipe.