WebSocket channels

Channels identify the stream you want. Symbols identify the market inside that channel’s venue family.

Examples

ws.send(JSON.stringify({
  op: "subscribe",
  channel: "orderbook",
  symbol: "BTC"
}));

ws.send(JSON.stringify({
  op: "subscribe",
  channel: "hip3_l4_diffs",
  symbol: "km:US500"
}));

ws.send(JSON.stringify({
  op: "subscribe",
  channel: "spot_orderbook",
  symbol: "HYPE-USDC"
}));

ws.send(JSON.stringify({
  op: "subscribe",
  channel: "hip4_orderbook",
  symbol: "#0"
}));

ws.send(JSON.stringify({
  op: "subscribe",
  channel: "lighter_orderbook",
  symbol: "BTC"
}));

Unsubscribe

ws.send(JSON.stringify({
  op: "unsubscribe",
  channel: "orderbook",
  symbol: "BTC"
}));

Pick the channel family and symbol format together. A HIP-3 symbol does not belong on a Lighter channel.

Channel Selection

Choose channels the same way you choose REST route families. Hyperliquid core channels are for standard perp symbols such as BTC and ETH. Spot work should use Spot-specific route and stream context when available. HIP-3 channels keep the builder prefix, HIP-4 channels keep outcome identifiers, and Lighter channels stay under the Lighter family.

Channel Family Matrix

Use this matrix to avoid treating every WebSocket channel as the same stream.

Family	Example channels	Symbol shape	Notes
Hyperliquid core	`orderbook`, `trades`, `funding`, `open_interest`, `liquidations`, `l4_diffs`, `l4_orders`	`BTC`, `ETH`	Core perp channels use bare symbols. Trade-row `user_address` and `builder_address` fields may be null depending on source; filter them client-side. L4 channels are order-level surfaces, available on every tier.
Hyperliquid Spot	`spot_orderbook`, `spot_trades`, `spot_l4_diffs`, `spot_l4_orders`, `spot_twap`	`HYPE-USDC`, `PURR-USDC`	Spot L4 channels carry order-level diff/event updates. Initialize or recover resting-book state from the documented snapshot/checkpoint routes. The separate REST Spot order-history route contains lifecycle records. Funding, open interest, and liquidations are not Spot data families.
HIP-3	`hip3_orderbook`, `hip3_trades`, `hip3_funding`, `hip3_liquidations`, `hip3_l4_diffs`, `hip3_l4_orders`	`km:US500`, `hyna:BTC`	Preserve the builder prefix and case. Do not normalize these into ordinary perp symbols.
HIP-4	`hip4_orderbook`, `hip4_trades`, `hip4_open_interest`, `hip4_l4_diffs`, `hip4_l4_orders`	`#0`, numeric side ids, or outcome-side context	Preserve outcome and side context. REST HIP-4 candles are probability-history series; WebSocket channels do not include funding, liquidation, or a dedicated candle stream.
Lighter	`lighter_orderbook`, `lighter_l3_orderbook`, `lighter_trades`, `lighter_candles`, `lighter_funding`, `lighter_open_interest`	`BTC`, `ETH`	Keep Lighter streams under the Lighter family even when the symbol text matches a Hyperliquid market. Current Lighter funding values must not be compared across venues or annualized pending normalization repair.

Native `userFills` terminology

Native Hyperliquid userFills maps to 0xArchive trades. 0xArchive has no WebSocket channel named userFills; do not subscribe to a nonexistent fill channel. Use trades and filter the returned rows client-side when attribution is needed.

Subscription Fields

Record these fields for each active subscription.

Field	Example	Why
Venue family	Hyperliquid core, HIP-3, HIP-4, Lighter	Keeps route semantics tied to the stream
Channel	`orderbook`, `hip3_l4_diffs`, `hip4_orderbook`, `lighter_orderbook`	Names the server stream
Symbol	`BTC`, `km:US500`, `#0`	Preserves family-specific symbol format
Consumer	dashboard, alert, local book, replay, export writer	Sets throughput and gap tolerance
Stop condition	unsubscribe, close, replay stop, retry budget	Prevents abandoned streams

Store the checklist with active connection state. On reconnect, restore from this checklist list. On unsubscribe, remove it from the list before trusting local subscription state.

Common Channel Mistakes

Do not send a HIP-3 symbol to a Lighter channel. Do not strip a HIP-3 prefix before subscribing. Do not treat HIP-4 outcome identifiers as ordinary perp symbols. Do not add Spot pairs to a generic perp stream; use Spot channel names such as spot_orderbook and keep dashed pair symbols visible in code.

State Handling

For order books and reconstruction workflows, treat the first snapshot as the baseline and each update as an ordered change. Store channel, symbol, timestamp, and message type with local state so a replay or reconnect can show what happened. If a gap event appears, mark the local state unsafe until it is rebuilt from a fresh snapshot or replay window.

Keep Subscriptions Bounded

Subscribe to the minimum channel and symbol set for the job, then add more only after throughput and reconnection behavior are understood. A dashboard can usually tolerate fewer channels than a backtest replay, and a backtest replay usually needs stronger gap handling than a simple monitor.

Unsubscribe And Reconnect Discipline

Subscription code should include the inverse operation. If an example subscribes, also show or link to unsubscribe behavior. Long-running clients should track active subscriptions so reconnects do not accidentally duplicate streams. Treat subscription state as application state. Expose the active channel set in debug output so stream bugs can be inspected without reproducing the whole session.

Connect

Stream

Replay

WebSocket channels

Examples

Unsubscribe

Channel Selection

Channel Family Matrix

Native `userFills` terminology

Subscription Fields

Common Channel Mistakes

State Handling

Keep Subscriptions Bounded

Unsubscribe And Reconnect Discipline

​Examples

​Unsubscribe

​Channel Selection

​Channel Family Matrix

​Native userFills terminology

​Subscription Fields

​Common Channel Mistakes

​State Handling

​Keep Subscriptions Bounded

​Unsubscribe And Reconnect Discipline

Examples

Unsubscribe

Channel Selection

Channel Family Matrix

Native `userFills` terminology

Subscription Fields

Common Channel Mistakes

State Handling

Keep Subscriptions Bounded

Unsubscribe And Reconnect Discipline