Skip to content
Alchemy Logo

l2BookDiff stream

Beta

HyperCore APIs are in beta. Message fields, limits, and behavior may change, including breaking changes. To request access, contact [email protected].

A snapshot of aggregated price levels, then only the levels that change.

{
  "method": "subscribe",
  "subscriptionId": "diff_01",
  "subscription": {
    "type": "l2BookDiff",
    "coins": [
      "BTC",
      "ETH"
    ],
    "nLevels": 20
  }
}

ParameterTypeRequiredDescription
coinsstring[]NoMarkets to include, up to 200. Omit, or send [], for every market (one unfiltered subscription per stream per connection). Unknown coins stay subscribed and return empty data until the market exists.
nSigFigsintegerNoGroup prices to 2–5 significant figures. Omit for exact prices.
mantissaintegerNo1, 2, or 5. Only with nSigFigs: 5; default 1.
nLevelsintegerNoLevels per side: 1, 10, 20 (default), or 50.

{
  "channel": "subscriptionResponse",
  "subscriptionId": "diff_01",
  "data": {
    "type": "l2BookDiff",
    "coins": [
      "BTC",
      "ETH"
    ],
    "nLevels": 20
  }
}

The first message is the full window for every subscribed market (isSnapshot: true). Later messages contain only the levels that changed:

{
  "seq": 2,
  "channel": "l2BookDiff",
  "subscriptionId": "diff_01",
  "data": {
    "blockNumber": 1183759644,
    "blockTime": 1791999593590,
    "isSnapshot": false,
    "books": [
      {
        "coin": "BTC",
        "levels": [
          [
            {
              "px": "81770.0",
              "sz": "0",
              "n": 0
            }
          ],
          [
            {
              "px": "81774.0",
              "sz": "1.5",
              "n": 4
            }
          ]
        ]
      }
    ]
  }
}

  1. On isSnapshot: true, replace your local book for each market in the message.
  2. For each later level: if sz is "0" (or n is 0), remove that price; otherwise set the price to the new sz and n.
  3. Keep nLevels levels per side. Levels that move into the window arrive as updates. A level pushed out of the window is sent with sz "0", even if orders still rest at that price, so applying every message keeps your book exactly nLevels deep.
  4. Check that seq increases by one. If it skips, resubscribe and start from the new snapshot.

Build the book from this stream's own snapshot. Don't seed it from a separate l2Book subscription, and keep the same nSigFigs, mantissa, and nLevels for the life of the book.

{"method":"unsubscribe","subscriptionId":"diff_01"}

Book streams have no replay. After a disconnect, or if seq skips, resubscribe; the first message is a fresh snapshot. If you receive a book_reset error, drop local state for the subscription and rebuild from the snapshot that follows. See replay and recovery.

Was this page helpful?