​

Hyperliquid WebSocket API

​

Critical Rules

1. WebSocket URL: wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY> (note: hypercore, not hyperliquid; auth is a ?key= query parameter, not an Authorization header).
2. Wire-compatible with wss://api.hyperliquid.xyz/ws for shared subscription types (e.g. l2Book).
3. No 1000-subscription-per-IP cap. Multiplex many subscriptions on one connection.
4. l2Book - aggregated price-level snapshots {px, sz, n}. coin is optional - omit it to stream every asset over a single subscription. When coin is omitted, marketTypes defaults to ["perp"] (perps only); pass ["spot"], ["outcome"], a mix, or ["*"] to opt into spot, outcome, and any future market types.
5. l2BookDiff - GoldRush-native L2 diff transport. Same aggregated {px, sz, n} shape as l2Book, but emits one Snapshot per subscribed coin and then per-block Updates carrying only changed levels. coin accepts a single asset, an array of assets, or can be omitted for wildcard (same marketTypes default - perps only - applies when coin is omitted). Treat sz: "0" (with n: 0) as level removal. Not available on the public Hyperliquid WebSocket.
6. l4Book - GoldRush-native order-level stream with user, oid, cloid, tif, and trigger metadata per order. coin is required. Emits a single Snapshot on subscribe, then per-block Updates (order_statuses + book_diffs). Not available on the public Hyperliquid WebSocket.

​

Available Subscriptions

​

Subscribe / Unsubscribe Pattern

// Subscribe
{"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}}

// Unsubscribe (same subscription body, method swapped)
{"method":"unsubscribe","subscription":{"type":"l2Book","coin":"BTC"}}

​

When to use which channel

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

Warning: The connection URL - including the key - is visible to any client that opens the socket. Do not ship your API key (cqt_…) to a browser or mobile app. For client-side use, mint a short-lived Ephemeral Key on your backend and pass that as key=gr_ek_… instead. It’s scoped to your API key, expires in 30 minutes, and is safe to embed. See Recipe B: browser WebSocket with auto-refresh.

​

Comparison with the public Hyperliquid WebSocket

​

Available subscriptions

​

Order book

​

Wallet activity

Note: Looking for candle, trades, bbo, or allMids? These public Hyperliquid market-data channels aren’t mirrored on the GoldRush WebSocket - use the GoldRush equivalents instead:

• OHLCV candles - the Info API candleSnapshot endpoint for historical candles, or the real-time HIP-3 and HIP-4 OHLCV recipes for candles across every HIP-3/HIP-4 market.
• Trade tape - allFills streams every fill on HyperCore (the global trade tape); userFills narrows it to specific wallets.
• Best bid/offer and mids - derive top-of-book from l2Book, or read mark and mid prices for the full universe from metaAndAssetCtxs.

​

Limits

​

Billing

1. URL - replace wss://api.hyperliquid.xyz/ws with wss://hypercore.goldrushdata.com/ws?key=.

​

Side-by-side

​

wscat

wscat -c wss://api.hyperliquid.xyz/ws

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

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

​

JavaScript / TypeScript

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

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

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())

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

​

Stream payloads are byte-equal, modulo live drift

​

Auth errors close the connection

​

Filter parameters are optional on GoldRush

​

Existing SDKs work after a wsUrl override

​

Authentication

​

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.

​

JavaScript / TypeScript: nomeida/hyperliquid

​

Install

npm install hyperliquid

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

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.

​

Manual WebSocket fallback

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)

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.

​

Verification

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

​

Hyperliquid WebSocket rate limits

​

No subscription cap

• Open as many concurrent subscriptions as your client supports.
• Multiplex hundreds of l2Book subscriptions on a single connection.
• Track every active wallet, market, and asset from one process.

​

Wildcard subscriptions

​

How streaming works

​

Billing

Warning: The minimum charge is one full minute per subscription. A subscription that lives for 200 milliseconds costs exactly the same as one that lives for 60 seconds. If your client reconnects often, read Every reconnect costs a new first minute.

​

The first minute is charged up front

​

After that, every started minute is a full minute

​

Per-minute rates

​

Wallet-activity channels bill a flat per-channel rate

• One billable subscription per (connection, channel). Adding or removing addresses on a channel you are already subscribed to does not open a new billable subscription.
• Up to 1,000 addresses per connection, per channel. To track more, open additional connections. Each one bills its own 1 credit per minute per channel.

​

What counts as one subscription

• Re-sending an identical subscribe on a live session is free. It is deduplicated, produces no extra data, and adds no charge.
• An array subscription is one subscription, not N. {"type": "l2BookDiff", "coin": ["BTC", "ETH", "SOL"]} is a single billable subscription charged at the sum of its coins’ rates: 3 x 0.13 = 0.39 credits per minute.
• Overlapping subscriptions each bill. Holding coin: ["BTC", "ETH"] and coin: "BTC" at the same time gives you two independent streams, both delivering BTC frames, and you pay for both.

​

Every reconnect costs a new first minute

• Back off exponentially. Start around 1 second and cap at 30 seconds, as in the reconnect sketch below. That bounds a flapping client to roughly 2 reconnects per minute instead of 60.
• Prefer one long-lived connection. Multiplex every subscription onto it rather than opening and closing sockets per query.

​

unsubscribe must repeat the exact shape you subscribed with

subscribe    { "type": "l2BookDiff", "coin": ["BTC", "ETH"] }   // one subscription
unsubscribe  { "type": "l2BookDiff", "coin": "ETH" }            // matches nothing

​

Worked example: snapshot-only across 168 coins

​

Connection management

​

Reconnect sketch

import WebSocket from "ws";

function connect() {
  const ws = new WebSocket(
    `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
    { maxPayload: 8 * 1024 * 1024 },
  );

  ws.on("open", () => {
    ws.send(JSON.stringify({
      method: "subscribe",
      subscription: { type: "l2Book" }, // wildcard - all assets
    }));
  });

  ws.on("close", () => setTimeout(connect, Math.min(30_000, backoff *= 2)));
  ws.on("error", () => ws.close());
  ws.on("message", handle);
}

let backoff = 1_000;
connect();

import asyncio, json, os
import websockets

async def consume():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    backoff = 1
    while True:
        try:
            async with websockets.connect(uri, max_size=8 * 1024 * 1024, ping_interval=30) as ws:
                backoff = 1
                await ws.send(json.dumps({
                    "method": "subscribe",
                    "subscription": {"type": "l2Book"},  # wildcard
                }))
                async for raw in ws:
                    handle(json.loads(raw))
        except Exception:
            await asyncio.sleep(min(30, backoff))
            backoff *= 2

asyncio.run(consume())

​

Watch out for client-side limits

• OS file descriptor limits - if you’re opening many connections in parallel, raise ulimit -n.
• Reverse proxy idle timeouts - if you’re terminating WS through nginx, HAProxy, or a cloud load balancer, set the idle timeout above your heartbeat interval (typically 60 seconds minimum).
• Browser concurrency - browsers limit WebSocket connections per origin; one connection multiplexing many subscriptions is always preferable to many connections.

​

Network and TLS

• HTTP/1.1 Upgrade to WSS is supported (standard WebSocket handshake).
• TLS 1.2+ required.
• Compression (permessage-deflate) is negotiated when offered by the client.

​

Need higher guarantees?

​

WebSocket API Reference

​

allFills | Hyperliquid WebSocket API

Tip: Estimate your monthly cost for this API using the Pricing Calculator.

Note: - GoldRush-native: No wss://api.hyperliquid.xyz/ws equivalent.

• Filters coin and aggregateByTime are both optional. Omit coin to stream every market.
• Live-only: No historical snapshot on subscribe. For windowed history, use the Info API userFillsByTime.
• Same per-fill shape as userFills; channel name in messages is allFills.

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"allFills"}}

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: "allFills",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "allFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px);
    }
  }
});

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": "allFills"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "allFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"])

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": {
    "type": "allFills"
  }
}

Note: Unsubscribe matches subscriptions by exact body. A subscription created with {"type": "allFills", "coin": "BTC"} is a different subscription from a wildcard {"type": "allFills"} - they must be unsubscribed independently.

​

Streamed message

{
  "channel": "allFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}

​

Related endpoints

​

builderFills

​

liquidationFills

​

userFills

​

builderLiquidations

​

builderFills | Hyperliquid WebSocket API

Tip: Estimate your monthly cost for this API using the Pricing Calculator.

Note: - GoldRush-native: No wss://api.hyperliquid.xyz/ws equivalent.

• Pass builder (string) for a single builder or addresses (string[]) for many. aggregateByTime optional.
• Live-only: No historical snapshot on subscribe. For windowed history, use the Info API builderFillsByTime.
• Same per-fill shape as userFills, plus builder and builderFee on every entry; channel name in messages is builderFills.

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"builderFills","builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}

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: "builderFills",
      builder: "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "builderFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px, "builderFee:", fill.builderFee);
    }
  }
});

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": "builderFills",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "builderFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"], "builderFee:", fill.get("builderFee"))

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderFills",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}

Note: Unsubscribe matches subscriptions by exact body. A subscription created with builder: "0xAAA" is a different subscription from one created with addresses: ["0xAAA"], even if they target the same builder. To narrow a multi-builder set, unsubscribe the original list in full, then resubscribe with the smaller list.

​

Streamed message

{
  "channel": "builderFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null,
        "builderFee": "0.1",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
      }
    ]
  ]
}

​

Errors

{ "channel": "error", "data": "subscription builderFills requires a 'builder' field" }

​

Related endpoints

​

builderLiquidations

​

allFills

​

liquidationFills

​

userFills

​

builderLiquidations | Hyperliquid WebSocket API

Tip: Estimate your monthly cost for this API using the Pricing Calculator.

Note: - GoldRush-native. builderLiquidations is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.

• TWAP fills do not carry builder codes. If a user’s last fill before liquidation was a TWAP fill, no builder liquidation notification will be sent.

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"builderLiquidations","builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}

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: "builderLiquidations",
      builder: "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === "builderLiquidations") {
    for (const [address, fill] of msg.liquidations) {
      console.log(
        "liquidated:", fill.liquidation.liquidatedUser,
        "via", fill.liquidation.method,
        "—", fill.coin, fill.sz, "@", fill.px,
        "builder:", fill.builder,
      );
    }
  }
});

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": "builderLiquidations",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") == "builderLiquidations":
                for address, fill in msg["liquidations"]:
                    liq = fill["liquidation"]
                    print("liquidated:", liq["liquidatedUser"],
                          "via", liq["method"], "—",
                          fill["coin"], fill["sz"], "@", fill["px"],
                          "builder:", fill["builder"])

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}

​

Streamed message

{
  "type": "builderLiquidations",
  "liquidations": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",
        "sz": "1.5",
        "side": "A",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Close Long",
        "closedPnl": "-125.50",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": true,
        "fee": "2.50",
        "tid": 87654321,
        "cloid": null,
        "builderFee": null,
        "deployerFee": null,
        "feeToken": "USDC",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
        "twapId": null,
        "liquidation": {
          "liquidatedUser": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
          "markPx": "2148.00",
          "method": "market"
        },
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"
      }
    ]
  ]
}

Note: TWAP-preceded liquidations are omitted. TWAP fills do not carry builder codes, so if a user’s last fill before liquidation was a TWAP slice, GoldRush cannot attribute the liquidation to a builder and no entry is emitted on this stream. Use the global liquidationFills stream if you need every liquidation regardless of builder attribution.

​

Errors

{ "channel": "error", "data": "subscription builderLiquidations requires a 'builder' field" }

​

Related endpoints

​

builderFills

​

allFills

​

liquidationFills

​

userFills

​

l2BookDiff | Hyperliquid WebSocket API

Tip: Estimate your monthly cost for this API using the Pricing Calculator.

Note: - GoldRush-native. l2BookDiff is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.

• Snapshot, then diffs. The first message is always a Snapshot; every message thereafter is an Updates. Clients must seed local book state from the snapshot and apply diffs from there. On reconnect, drop local state and re-seed from the next snapshot.
• coin is optional. Omit it to stream the entire L2 order book across every asset on a single subscription.
• When coin is omitted, the optional marketTypes filter selects which market families to include. It defaults to ["perp"] only.
• Pass "marketTypes": ["spot"], or "marketTypes":["outcome"], or a mix (e.g. "marketTypes": ["perp","spot"]), or use the wildcard "marketTypes": ["*"] to opt into spot, perps, outcome, and any future market types.
• No 1000-subscription-per-IP cap - multiplex hundreds of l2BookDiff subscriptions on a single connection.
• For OHLCV candles instead of raw book state, use the Streaming API OHLCV streams.

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"l2BookDiff","coin":"HYPE"}}

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: "l2BookDiff", coin: "HYPE" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "l2BookDiff") return;

  if (msg.data.Snapshot) {
    const { coin, time, block_height, levels: [bids, asks] } = msg.data.Snapshot;
    console.log("snapshot", coin, time, block_height, "bids:", bids.length, "asks:", asks.length);
  } else if (msg.data.Updates) {
    const { time, block_height, book_diffs } = msg.data.Updates;
    console.log("updates", time, block_height, "coins:", book_diffs.length);
  }
});

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": "l2BookDiff", "coin": "HYPE"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l2BookDiff":
                continue
            data = msg["data"]
            if "Snapshot" in data:
                snap = data["Snapshot"]
                bids, asks = snap["levels"]
                print("snapshot", snap["coin"], snap["time"], snap["block_height"], "bids:", len(bids), "asks:", len(asks))
            elif "Updates" in data:
                upd = data["Updates"]
                print("updates", upd["time"], upd["block_height"], "coins:", len(upd["book_diffs"]))

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": { "type": "l2BookDiff", "coin": "HYPE" }
}

Note: Unsubscribe matches subscriptions by exact body. A subscription created with coin: ["BTC", "ETH"] is a different subscription from one created with coin: "BTC" or coin: "ETH".

// Drop ETH from a ["BTC","ETH"] subscription:
{ "method": "unsubscribe", "subscription": { "type": "l2BookDiff", "coin": ["BTC", "ETH"] } }
{ "method": "subscribe",   "subscription": { "type": "l2BookDiff", "coin": ["BTC"] } }

​

Streamed messages

​

Initial snapshot

{
  "channel": "l2BookDiff",
  "data": {
    "Snapshot": {
      "coin": "HYPE",
      "time": 1779220051027,
      "block_height": 1002862373,
      "levels": [
        [
          { "px": "48.601", "sz": "51.26", "n": 1 }
        ],
        [
          { "px": "48.614", "sz": "12.34", "n": 1 }
        ]
      ]
    }
  }
}

​

Incremental updates

{
  "channel": "l2BookDiff",
  "data": {
    "Updates": {
      "time": 1779220051224,
      "block_height": 1002862374,
      "book_diffs": [
        {
          "coin": "HYPE",
          "levels": [
            [
              { "px": "48.601", "sz": "60.00", "n": 2 }
            ],
            [
              { "px": "48.614", "sz": "0", "n": 0 }
            ]
          ]
        }
      ]
    }
  }
}

​

Response fields

​

Related endpoints

​

l2Book

​

l2BookDiff2

​

l4Book

​

l4BookUpdates

​

l2BookDiff2 | Hyperliquid WebSocket API

Note: - GoldRush-native. l2BookDiff2 is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.

• Diff-only — no inline snapshot. Unlike l2BookDiff, this stream never sends a Snapshot frame. Every message is an Updates batch. Seed your local book from the REST l2BookDiffSnapshot info method, then apply diffs on top — see Bootstrapping & gap detection below.
• Sequenced for gap detection. Each per-coin diff carries a monotonic seq and the prev_seq it follows; each batch carries a server epoch and a cursor. This lets a client detect a dropped message or a server reset and re-bootstrap deterministically.
• coin is optional. Omit it to stream every asset on a single subscription; use marketTypes to choose which market families are included (defaults to ["perp"]).

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

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: "l2BookDiff2", coin: "BTC" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel !== "l2BookDiff2") return;

  const { time, block_height, epoch, cursor, book_diffs } = msg.data.Updates;
  for (const d of book_diffs) {
    console.log(block_height, epoch, d.coin, "seq", d.prev_seq, "->", d.seq);
    // apply d.levels = [changedBids, changedAsks]; sz "0" removes the level
  }
});

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": "l2BookDiff2", "coin": "BTC"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") != "l2BookDiff2":
                continue
            upd = msg["data"]["Updates"]
            for d in upd["book_diffs"]:
                print(upd["block_height"], upd["epoch"], d["coin"], "seq", d["prev_seq"], "->", d["seq"])

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": { "type": "l2BookDiff2", "coin": "BTC" }
}

Note: Unsubscribe matches subscriptions by exact body. A subscription created with coin: ["BTC", "ETH"] is a different subscription from one created with coin: "BTC". To narrow a multi-coin set, unsubscribe the original coin array in full, then resubscribe with the smaller list.

​

Streamed messages

{
  "channel": "l2BookDiff2",
  "data": {
    "Updates": {
      "time": 1786379817106,
      "block_height": 1105180205,
      "epoch": "466bf60f-bb7a-4591-89a3-a2660234fef5",
      "cursor": "1105180205:1786379817106",
      "book_diffs": [
        {
          "coin": "BTC",
          "seq": 4229978,
          "prev_seq": 4229977,
          "levels": [
            [
              { "px": "57686.0", "sz": "0.09903", "n": 25 }
            ],
            [
              { "px": "64164.0", "sz": "0", "n": 0 }
            ]
          ]
        }
      ]
    }
  }
}

​

Bootstrapping & gap detection

1. Subscribe to l2BookDiff2 for your coin(s) and start buffering the incoming Updates.
2. Fetch a snapshot for each coin from the REST l2BookDiffSnapshot info method. Note its height, epoch, and per-coin seq.
3. Discard already-applied diffs. Drop any buffered batch whose block_height is ≤ the snapshot’s height (the snapshot already includes those blocks). You may equivalently discard per coin by seq - drop any diff whose seq ≤ the snapshot’s seq - for the tightest alignment.
4. Verify the epoch. Every remaining diff’s epoch must equal the snapshot’s epoch. A different epoch means the stream reset after your snapshot - re-fetch the snapshot and restart.
5. Apply in order. For each coin, the first diff you apply should have prev_seq == snapshot.seq. For each level, upsert {px, sz, n}, or remove the price when sz is "0".
6. Ongoing gap detection. Per coin, each diff’s prev_seq must equal the last seq you applied for that coin. On a mismatch (a dropped message) or an epoch change (a server reset), re-bootstrap that coin from step 2.

Tip: The seq/prev_seq are per coin, tracked within the current epoch. Compare them per coin, not globally across the batch.

​

Response fields

​

Related endpoints

​

l2Book

​

l2BookDiff

​

l4Book

​

l4BookUpdates

​

l2Book | Hyperliquid WebSocket API

Tip: Estimate your monthly cost for this API using the Pricing Calculator.

Note: - Wire-compatible with wss://api.hyperliquid.xyz/ws l2Book subscriptions - same channel name, same levels shape.

• coin is optional on GoldRush. Omit it to stream the entire L2 order book across every asset on a single subscription. The public Hyperliquid API requires coin and locks each subscription to one asset at a time.
• When coin is omitted, the optional marketTypes filter selects which market families to include. It defaults to ["perp"] only.
• Pass "marketTypes": ["spot"], or "marketTypes":["outcome"], or a mix (e.g. "marketTypes": ["perp","spot"]), or use the wildcard "marketTypes": ["*"] to opt into spot, perps, outcome, and any future market types.
• No 1000-subscription-per-IP cap - multiplex hundreds of l2Book subscriptions on a single connection.
• For OHLCV candles instead of raw book state, use the Streaming API OHLCV streams.

​

Endpoint

wss://hypercore.goldrushdata.com/ws?key=

​

Subscribe

​

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

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") {
    const { coin, time, levels: [bids, asks] } = msg.data;
    console.log(coin, time, "top bid:", bids[0], "top ask:", asks[0]);
  }
});

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:
            msg = json.loads(raw)
            if msg.get("channel") == "l2Book":
                print(msg["data"]["coin"], msg["data"]["time"], msg["data"]["levels"][0][:1])

asyncio.run(main())

​

Unsubscribe

{
  "method": "unsubscribe",
  "subscription": { "type": "l2Book", "coin": "BTC" }
}

Note: Unsubscribe matches subscriptions by exact body. A subscription created with coin: ["BTC", "ETH"] is a different subscription from one created with coin: "BTC" or coin: "ETH".

// Drop ETH from a ["BTC","ETH"] subscription:
{ "method": "unsubscribe", "subscription": { "type": "l2Book", "coin": ["BTC", "ETH"] } }
{ "method": "subscribe",   "subscription": { "type": "l2Book", "coin": ["BTC"] } }

​

Streamed message

{
  "channel": "l2Book",
  "data": {
    "coin": "BTC",
    "time": 1762450000123,
    "block_height": 996629014,
    "levels": [
      [
        { "px": "68210.0", "sz": "1.2345", "n": 3 },
        { "px": "68209.5", "sz": "4.5670", "n": 5 },
        { "px": "68209.0", "sz": "2.1100", "n": 2 }
      ],
      [
        { "px": "68215.0", "sz": "0.8900", "n": 2 },
        { "px": "68215.5", "sz": "3.4500", "n": 4 },
        { "px": "68216.0", "sz": "1.2300", "n": 1 }
      ]
    ]
  }
}

​

Related endpoints

​

l2BookDiff

​

l2BookDiff2

​

l4Book

​

l4BookUpdates

​

l4BookUpdates | Hyperliquid WebSocket API

Note: - GoldRush-native. l4BookUpdates is not exposed on wss://api.hyperliquid.xyz/ws. Pointing a client at the public endpoint with this subscription type will fail.

• Order-level (L4) diffs. Like l4Book, every change is per individual order (user, oid, side, raw_book_diff) plus the order-lifecycle order_statuses for the block — not aggregated price levels.
• Strictly block-ordered. Diffs are emitted synchronously in monotonic block_height order. This is the difference from l4Book, whose per-block broadcast can deliver adjacent blocks out of order. The l4Book channel is unchanged; l4BookUpdates is the strictly-ordered, sequenced sibling.
• Diff-only — no inline snapshot. This stream never sends a Snapshot frame; every message is an Updates batch. Seed your local book from the REST l4BookSnapshot info method, then apply diffs on top — see Bootstrapping & gap detection.
• Sequenced for gap detection. Each per-coin diff carries a monotonic seq and the prev_seq it follows; each batch carries a server epoch and a cursor. This lets a client detect a dropped message or a server reset and re-bootstrap deterministically.
• Perps only. No spot or prediction-market assets. coin is required — subscribe with a single symbol or an array of symbols; one asset per book.