Order Book: Snapshots vs Deltas

Dime Trades sends you the whole order book, every time. There is no delta feed, no incremental patch format, and no sequence number to reconcile against. This is the single most important thing to get right when integrating: a client built to merge incremental updates — the pattern most exchange APIs use — will accumulate phantom liquidity that never goes away.

The three carriers

Order book state reaches you through three channels. All three carry the identical payload shape, so one parser handles all of them.

Carrier	Transport	Payload	When
`GET /orderbook/orderbook`	REST	Full snapshot	On request
`initial_orderbooks`	WebSocket	Full snapshot, keyed by market id	Once, right after `SUBSCRIBE_MARKET`
`ORDERBOOK_DEPTH`	WebSocket	Full snapshot	Whenever the book changes (≤1/sec)

A fourth event, MARKET_UPDATE, reaches subscribed markets too — but it carries status transitions only and never any book data. A client that subscribes and listens only for MARKET_UPDATE will sit silent until a market halts or resumes.

Replace, never merge

Every ORDERBOOK_DEPTH message supersedes the previous one entirely. Assign it over your local book. Do not merge it in.

The reason is that a price level which has been fully consumed is omitted from the arrays. It is not sent with quantity 0, and there is no “removed levels” field. Absence is the only signal.

// ✅ Correct — the message IS the book
socket.on("ORDERBOOK_DEPTH", (msg) => {
  books.set(msg.marketId, msg);
});

// ❌ Wrong — 62¢ never disappears once it has been seen
socket.on("ORDERBOOK_DEPTH", (msg) => {
  const book = books.get(msg.marketId);
  for (const [price, qty] of msg.yes_bids) {
    book.yes_bids[price] = qty;   // consumed levels are never cleared
  }
});

Concretely: you hold yes_bids: [[63, 120], [62, 340]], the 62¢ level trades out, and the next message is yes_bids: [[63, 120]]. Replacing gives you the truth. Merging leaves 340 contracts resting at 62¢ in your UI forever.

Why throttling is safe

Depth is coalesced to at most one update per second per market. Within each window the server keeps only the newest state and discards the intermediate ones outright — they are never sent, and never resent later. That is lossless precisely because every message is a full snapshot. The update you receive already reflects everything the dropped ones would have told you. This is also why there is no sequence number and nothing to request a replay of: there is no gap to detect. If you can see the latest snapshot, you are fully caught up. The trade-off is that you cannot reconstruct the path the book took between updates. If you need every intermediate state, the trade feed (NEW_TRADE) is the event-by-event record; the depth feed is a sampled view of state.

subscriptionType: "realtime" is accepted and acknowledged, but a realtime subscriber currently receives no ORDERBOOK_DEPTH messages — only the one-off initial_orderbooks snapshot and MARKET_UPDATE events. Subscribe as throttled (the default) until this is addressed.

Seeding a book

Because REST and initial_orderbooks return the same shape, either can seed you. Prefer the WebSocket path — it removes the race between fetching a snapshot and the first push arriving:

socket.emit("SUBSCRIBE_MARKET", "40996686,40996685", "throttled");

socket.on("initial_orderbooks", (books) => {
  // { "40996686": { marketId, yes_bids, no_bids, ... }, ... }
  for (const [marketId, book] of Object.entries(books)) {
    localBooks.set(marketId, book);
  }
});

socket.on("ORDERBOOK_DEPTH", (msg) => {
  localBooks.set(msg.marketId, msg);   // same shape, same handling
});

Use GET /orderbook/orderbook when you want depth without holding a connection — a server-side valuation job, say. Note it is cached for 60 seconds, so it is not a substitute for the live feed.

initial_orderbooks is only emitted when at least one book resolved. If none of your ids resolve, the event never fires — so do not block your render on it. Check missingMarkets on the subscribed event instead.

Confirming what you subscribed to

The subscribed acknowledgement is not a validity check. The server joins a room for every id it is handed, valid or not, and echoes them all back in marketIds. A typo looks exactly like a real market.

socket.on("subscribed", ({ marketIds, rooms, missingMarkets }) => {
  if (missingMarkets.length) {
    console.warn("These ids never resolved:", missingMarkets);
  }
});

missingMarkets is the only failure signal. Without checking it you will wait indefinitely for depth on a market that does not exist.

Reading the payload

{
  "marketId": "40996686",
  "yes_bids": [[63, 120], [62, 340]],
  "no_bids":  [[37, 90],  [36, 210]],
  "bestYesBid": 63,
  "bestNoBid": 37,
  "tradedVolume": 18420,
  "liquidity": 760,
  "timestamp": 1753776000000
}

yes_bids / no_bids are [price, quantity] pairs, best price first.
Prices are cents, 1–99. YES and NO are complementary — a YES bid at 63 and a NO bid at 37 price the same contract at 100.
bestYesBid / bestNoBid are conveniences derived from yes_bids[0][0] and no_bids[0][0]. They are null when that side is empty; an empty side is [], not null.
timestamp is unix milliseconds at snapshot generation. Over REST on a cache hit this is the age of the cached copy, not of your request.

There is no ask side. In a prediction market, selling YES is buying NO, so resting sell interest already appears as bids on the opposite side.

Getting started

Reference

Events & markets

Webhooks

External Wallet

WebSockets

The three carriers

Replace, never merge

Why throttling is safe

Seeding a book

Confirming what you subscribed to

Reading the payload

​The three carriers

​Replace, never merge

​Why throttling is safe

​Seeding a book

​Confirming what you subscribed to

​Reading the payload

The three carriers

Replace, never merge

Why throttling is safe

Seeding a book

Confirming what you subscribed to

Reading the payload