> ## 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 Overview > The Hyperliquid order book API over WebSocket - stream real-time L2 and L4 order book data for every asset on one connection, plus live wallet fills, with no per-IP subscription cap. A drop-in replacement for the public Hyperliquid WebSocket on `hypercore.goldrushdata.com`. The GoldRush Hyperliquid WebSocket API is a **drop-in replacement** for `wss://api.hyperliquid.xyz/ws`. For the [channels GoldRush supports](#available-subscriptions), subscription payloads, channel names, and message shapes are byte-for-byte identical to the public Hyperliquid feed. The only difference is the connection URL - authentication is a required `key` query parameter, so no header changes are needed in your client. ## Endpoint ``` wss://hypercore.goldrushdata.com/ws?key= ``` **key** `string` *required* Your GoldRush API key. Passed as a query parameter at connection time. > [!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](https://goldrush.dev/docs/ephemeral-keys.md) 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](https://goldrush.dev/docs/ephemeral-keys.md#recipe-b-browser-websocket-with-auto-refresh). ## Comparison with the public Hyperliquid WebSocket | | Public WebSocket | GoldRush | | - | - | - | | URL | `wss://api.hyperliquid.xyz/ws` | `wss://hypercore.goldrushdata.com/ws?key=` | | Auth | None | `key` query parameter (required) | | Subscriptions per IP | 1000 | No cap | | Wire compatibility | n/a (it's the source) | Byte-for-byte | | Available channels | See [Hyperliquid Docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket) | See [Available subscriptions](#available-subscriptions) | ## Available subscriptions ### Order book Stream the Hyperliquid order book in real time - three channels, from aggregated L2 snapshots to full order-level (L4) detail. Omit `coin` on `l2Book` or `l2BookDiff` to stream **every asset on a single subscription**, which the public WebSocket's 1000-subscription-per-IP cap makes impractical. | Channel | Subscription body | Returns | | - | - | - | | [`l2Book`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l2-book) | `{"type": "l2Book", "coin": "BTC"}` | Real-time L2 order book snapshots - bids and asks aggregated by significant figures. `coin` is optional - omit it to stream every asset on one subscription. | | [`l2BookDiff`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l2-book-diff) | `{"type": "l2BookDiff", "coin": "HYPE"}` | GoldRush-native L2 diff transport - initial `Snapshot` per coin plus per-block `Updates` carrying only changed `{px, sz, n}` levels. `coin` accepts a single asset, an array of assets, or can be omitted to stream every asset. Not available on the public Hyperliquid WebSocket. | | [`l4Book`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l4-book) | `{"type": "l4Book", "coin": "BTC"}` | GoldRush-native order-level book stream - initial `Snapshot` of every resting order plus per-block `Updates` with `order_statuses` and `book_diffs`. Exposes `user`, `oid`, `cloid`, `tif`, and trigger metadata per order. `coin` is required. Not available on the public Hyperliquid WebSocket. | ### Wallet activity | Channel | Subscription body | Returns | | - | - | - | | [`userFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills) | `{"type": "userFills", "addresses": ["0x…"]}` | Live trade fills for one or more wallets, batched per block as `[address, fill]` tuples. Aliases `user` / `users` also accepted. | | [`orderUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/order-updates) | `{"type": "orderUpdates", "addresses": ["0x…"]}` | Live order lifecycle events (placements, fills, cancels, rejections) for one or more wallets, batched per block as an `updates` array of objects, each tagged with the originating `user`. Aliases `user` / `users` also accepted. | | [`liquidationFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/liquidation-fills) | `{"type": "liquidationFills"}` | Global stream of every liquidation fill on HyperCore. Same shape as `userFills` with a non-null `liquidation` object on every entry. **GoldRush-native**, no upstream equivalent. | | [`allFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/all-fills) | `{"type": "allFills"}` | Global stream of every fill on HyperCore. Optional `coin` filter narrows to a single market. Same per-fill shape as `userFills`. **GoldRush-native**, no upstream equivalent. | | [`builderFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-fills) | `{"type": "builderFills", "builder": "0x…"}` | Live attributed fills for one or more builder addresses, with `builder` and `builderFee` on every entry. Accepts `builder` (single) or `addresses` (array). **GoldRush-native**, no upstream equivalent. | | [`builderLiquidations`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-liquidations) | `{"type": "builderLiquidations", "builder": "0x…"}` | Liquidation fills whose closing order was routed through your builder code - the intersection of `liquidationFills` and `builderFills`. Requires `builder`; carries both the `liquidation` object and `builder` attribution on every entry. **GoldRush-native**, no upstream equivalent. | | [`userNonFundingLedgerUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates) | `{"type": "userNonFundingLedgerUpdates", "addresses": ["0x…"]}` | Live non-funding ledger events (deposits, withdrawals, transfers, liquidations, vault actions, staking, rewards) for one or more wallets. | > [!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`](https://goldrush.dev/docs/api-reference/hyperliquid-info/candle-snapshot) endpoint for historical candles, or the real-time [HIP-3](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip3-markets.md) and [HIP-4](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip4-markets.md) OHLCV recipes for candles across every HIP-3/HIP-4 market. > * **Trade tape** - [`allFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/all-fills) streams every fill on HyperCore (the global trade tape); [`userFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills) narrows it to specific wallets. > * **Best bid/offer and mids** - derive top-of-book from [`l2Book`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l2-book), or read mark and mid prices for the full universe from [`metaAndAssetCtxs`](https://goldrush.dev/docs/api-reference/hyperliquid-info/meta-and-asset-ctxs). ## Limits No 1000-subscription-per-IP cap. On `l2Book` and `l2BookDiff`, filter parameters are optional - omit `coin` to stream the full L2 book across every asset on a single subscription. The wildcard defaults to **perps only** (`marketTypes: ["perp"]`); pass `["spot"]`, `["outcome"]`, a mix, or `["*"]` to opt into spot, outcome, and future market types. `l2BookDiff` additionally accepts an array of coin symbols for a fixed multi-asset subscription. `l4Book` requires `coin` and is one-asset-per-subscription. See [Limits & Connections](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/limits.md) for details. ## Billing Subscriptions bill per minute, in whole minutes, with a **minimum of one full minute per subscription**. There is no proration: a subscription that lives 200 milliseconds costs the same as one that lives 60 seconds, and every reconnect starts a new subscription that pays the minimum again. See [Billing](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/limits.md#billing) for the per-minute rates, the `ceil` rounding table, and worked examples. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.