l2Book | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

0.5 per coin per minute

Processing

Realtime

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

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.

Note: When coin is omitted, a credit rate of 50 credits per minute subscribed is applied.

Endpoint

wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>

key

string

required

Your GoldRush API key. Passed as a query parameter at connection time - no Authorization header is used.

Send this JSON message after the connection is established:

method

string

required

Always "subscribe".

subscription

object

required

Show properties

type

string

required

Always "l2Book".

coin

string

Asset symbol - e.g. "BTC", "ETH", "@107" for spot pairs. For HIP-3 markets, include the deployer prefix. Omit to receive snapshots for all perp assets (the default; see marketTypes to include spot or outcome markets).

marketTypes

string[]

Optional. Selects which market families a wildcard subscription includes. Only valid when coin is omitted. Defaults to ["perp"] - when omitted, only perp markets stream. Spot and outcome markets require explicit opt-in.Accepted values:

"perp" (default) - vanilla perps and HIP-3 deployer-perps (e.g. BTC, ETH, HYPE, SOL, cash, abcd, USA500).
"spot" - @<index> spot markets and legacy spot pairs (e.g. @1, @107 for HYPE spot, PURR/USDC). Not included by default.
"outcome" - HIP-4 prediction-market outcomes (e.g. #700, #710, #741). Not included by default.
"*" - every current type ("perp" + "spot" + "outcome") and auto-opt-in to any future types the server adds.

Mix and match in one subscription, e.g. ["perp", "outcome"]. A second subscribe with a different marketTypes value replaces the previous filter rather than coexisting with it.

nSigFigs

int

Significant figures used for price aggregation. One of 2, 3, 4, 5, or null for full precision. Defaults to null.

mantissa

int

When nSigFigs is 5, controls the mantissa rounding. One of 1, 2, or 5. Not allowed for other nSigFigs values.

Example

Pick the subscription shape that matches the coverage you want:

Subscribe with	What you receive
`{"type":"l2Book","coin":"BTC"}`	L2 snapshots for BTC only
`{"type":"l2Book"}`	L2 snapshots for every perp coin (default: `marketTypes: ["perp"]`)
`{"type":"l2Book","marketTypes":["spot"]}`	L2 snapshots for every spot coin
`{"type":"l2Book","marketTypes":["outcome"]}`	L2 snapshots for every HIP-4 outcome market
`{"type":"l2Book","marketTypes":["perp","spot"]}`	L2 snapshots for perps + spot
`{"type":"l2Book","marketTypes":["*"]}`	L2 snapshots for every coin (perp + spot + outcome, plus future types)

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

Send the same subscription body with method: "unsubscribe":

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

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".You cannot unsubscribe a partial set of coins from an existing multi-coin subscription. To narrow the set, unsubscribe the original coin array in full, then resubscribe with the smaller list:

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

Streamed message

Each message has channel: "l2Book" and a data payload with the current book snapshot for the subscribed coin.

{
  "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 }
      ]
    ]
  }
}

channel

string

Always "l2Book".

data

object

Show properties

coin

string

Asset symbol the snapshot belongs to.

time

int

HyperCore block timestamp in milliseconds.

block_height

int

HyperCore block height the snapshot was taken at.

levels

array<array<object>>

Tuple [bids, asks]. Each side is an array of price levels in best-first order.

Show level properties

string

Price for this level (decimal string).

string

Aggregate size resting at this level (decimal string, base units).

int

Number of orders aggregated into this level.

l2BookDiff

Subscribe to real-time L2 order book (initial snapshot + diffs) for all Hyperliquid assets over WebSocket.

Last reviewed: 2026-06-16

Foundational API

Streaming API

Pipeline API

Hyperliquid API

JSON-RPC

l2Book | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed message

l2BookDiff

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Related endpoints

l2BookDiff

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Related endpoints