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","sz":"18.36223","n":1} ],
                        [ {"px":"77492","sz":"0.51","n":2} ] ] } }

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

l2Diff

The same book, sent as one snapshot followed by changes. This is the channel to use when you want depth: at 1000 levels the incremental stream carries the same book for a fraction of the bytes of a full frame on every block.

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

data always holds exactly one of two keys:

• Snapshot — the whole book, arranged as one levels list of two halves exactly like l2Book. It arrives first, and again whenever the feed needs to restart your view.
• Updates — what changed since the previous state, plus a prevHeight.

Inside Updates, changes come separately for bids and asks. Each side has upd for levels that changed and del for levels that are gone.

An update, with one level removed on the ask side:

{ "channel": "l2Diff",
  "data": { "Updates": { "coin": "BTC", "time": 1788944469884,
    "height": 1141112013, "prevHeight": 1141112009, "nLevels": 5,
    "bids": { "upd": [["79626","6.55144",24], ["79625","0.02308",4]], "del": [] },
    "asks": { "upd": [["79627","3.61784",13], ["79632","1.31325",2]], "del": ["79628"] } } } }

The rule for the client: if prevHeight does not match the height of the last update you applied, your copy of the book is wrong. Stop applying updates and wait for the next snapshot.

A snapshot can also arrive in the middle of a stream, on the same connection. Treat it as a fresh start: throw away the book you were keeping and rebuild from it.

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