Hyperliquid WebSocket Streams

Eight streams, all on one connection. Almost every subscribe message uses the same envelope:

{ "method": "subscribe", "subscription": { "type": "STREAM_NAME", "coin": "BTC" } }

The two exceptions are allMids, which covers every market and takes no coin, and orderUpdates, which follows an address rather than a market.

l2Book

The whole book, aggregated by price level.

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

A frame:

{ "channel": "l2Book",
  "data": { "coin": "BTC", "time": 1787495871629, "nLevels": 20,
            "levels": [ [ {"px":"77488.0","sz":"18.36223","n":1} ],
                        [ {"px":"77492.0","sz":"0.51","n":2} ] ] } }

Depth. nLevels is optional and defaults to 20. The maximum is 1000.

l2Diff

The same book as l2Book, same parameters, sent as one snapshot and then only the levels that changed. At 1000 levels that is about 113× less traffic, and the rebuilt book is identical level for level. Use it whenever you want depth.

{ "method": "subscribe", "subscription": { "type": "l2Diff", "coin": "BTC", "nLevels": 1000 } }

data holds either a Snapshot (the whole book, shaped like l2Book) or Updates (per side, upd as [px, sz, n] triples and del as bare prices). If an update's prevHeight does not match the last height you applied, you missed a frame: resubscribe to get a fresh snapshot.

Frame formats, continuity rules and the traffic measurements are on their own page: l2Diff: the incremental book.

bbo

Best bid and best offer only, pushed as the top of the book changes. The lightest stream here — use it when you need a price, not a book.

{ "method": "subscribe", "subscription": { "type": "bbo", "coin": "BTC" } }

A frame:

{ "channel": "bbo",
  "data": { "coin": "BTC", "time": 1788944430011,
            "bid": {"px":"79613","sz":"1.90375","n":6},
            "ask": {"px":"79614","sz":"13.83401","n":54} } }

bid and ask are single objects, not lists, in the same px / sz / n shape as a level of l2Book.

trades

Executed trades as they are matched.

{ "method": "subscribe", "subscription": { "type": "trades", "coin": "BTC" } }

A frame:

{ "channel": "trades",
  "data": [ { "coin": "BTC", "side": "B", "px": "79614.0", "sz": "0.00035",
              "hash": "0xe28cff12f5267aeae406044403fac902054d00f890...",
              "time": 1788944433313, "tid": 1066813006098562,
              "users": ["0x807e5727654ec56e3c7bb3f3779a7a7787ada4cd",
                        "0x2cffce91b4e0c81df18726ff66b31b2b1545e1ad"] } ] }

l4Book

The book order by order rather than aggregated by price: every resting order with its price, size, id and the address that owns it. This is the deepest view of the market that exists.

{ "method": "subscribe", "subscription": { "type": "l4Book", "coin": "BTC" } }

The first message is a full snapshot, then changes stream on every block. There is no depth parameter here — nLevels does not apply to l4Book, which always carries the whole book order by order.

A snapshot, cut down to one order per side — a real one carries hundreds or thousands:

{ "channel": "l4Book",
  "data": { "Snapshot": { "coin": "LTC", "time": 1788944447014, "height": 1141111700,
    "levels": [
      [ {"user":"0x4e60e3a4...","coin":"LTC","side":"B","limitPx":"54.717","sz":"7.31",
         "oid":540105017942,"timestamp":1788944446488,"orderType":"Limit","tif":"Alo",
         "origSz":"7.31","cloid":"0xf80bd700...","reduceOnly":false,
         "isTrigger":false,"triggerPx":"0.0","triggerCondition":"N/A",
         "isPositionTpsl":false,"children":[]} ],
      [ {"user":"0x4e60e3a4...","coin":"LTC","side":"A","limitPx":"54.723","sz":"7.31",
         "oid":540105019037,"timestamp":1788944446690,"orderType":"Limit","tif":"Alo",
         "origSz":"7.31","cloid":"0x0e0cd700...","reduceOnly":false,
         "isTrigger":false,"triggerPx":"0.0","triggerCondition":"N/A",
         "isPositionTpsl":false,"children":[]} ] ] } } }

levels[0] is bids and levels[1] is asks, the same way round as l2Book. Each order carries who placed it (user), its id (oid) and client id (cloid), price and size (limitPx, sz, origSz), when it was placed, its type and time-in-force, and its trigger fields.

An update:

{ "channel": "l4Book",
  "data": { "Updates": { "time": 1788944447092, "height": 1141111701,
    "order_statuses": [],
    "book_diffs": [ { "user": "0xdf83170d...", "oid": 540105022216,
                      "px": "54.742", "coin": "LTC",
                      "raw_book_diff": { "new": { "sz": "54.8" } } } ] } } }

Like l2Diff, data holds either a Snapshot or Updates, and both carry a height.

bookDiffs

The raw book diffs the node itself produces, before any aggregation.

{ "method": "subscribe", "subscription": { "type": "bookDiffs", "coin": "BTC" } }

orderUpdates

Status changes of orders — placed, filled, cancelled. This stream follows an address, not a market, so there is no coin here.

{ "method": "subscribe", "subscription": { "type": "orderUpdates", "user": "0xYOUR_ADDRESS" } }

allMids

One frame carrying the mid price of every market, so you do not need a subscription per coin.

{ "method": "subscribe", "subscription": { "type": "allMids" } }

Field types

Spot markets

Spot works the same way as perpetuals: put @<index> from spotMeta where the symbol goes. The book, the incremental channel, best bid and offer, trades and the per-order book all take spot markets.

Several markets on one connection

Send one subscribe message per market. Each market streams as its own frame, and the coin field tells you which is which. There is no need to open a connection per market.

Next steps

External references

• Hyperliquid WebSocket subscriptions