Order book

A live order book snapshot per pair: raw top-of-book levels, a pre-grouped depth histogram covering about 1% around the mid, and the tracked walls, all in one response refreshed every second.

GET/v1/book/{symbol}

Osiris maintains full order books server-side for every tracked crypto perpetual (they power the densities scanner). This endpoint hands you a flattened snapshot of one of them. You get three views in a single payload: the raw best levels for microstructure work, a depth histogram wide enough to chart, and the walls our tracker currently flags on the pair.

Books are flattened on demand. Your first call registers interest; the engine starts snapshotting that book within a second and keeps going for as long as you keep asking. That means the very first response for a quiet pair can carry asOf: null with empty sides: that is the warm-up, not an error. Retry within a couple of seconds and the book is there.

Request

ParameterInDescription
exchangequeryVenue whose book to read. See Exchanges. Default: Binance. Each venue's book is its own market.
levelsqueryCap on raw levels per side, 1 to 1000 (default 1000). The depth histogram is always complete regardless.
Top 25 levels of the BTCUSDT book
curl "https://osiristrader.com/api/v1/book/BTCUSDT?levels=25" \
  -H "Authorization: Bearer osk_YOUR_KEY"

Response

{
  "symbol": "BTCUSDT",
  "exchange": "binance",
  "asOf": 1794423001838,
  "bids": [[74391.4, 3.348], [74391.3, 0.028]],
  "asks": [[74391.5, 1.942], [74391.6, 0.515]],
  "depth": {
    "step": 5,
    "bids": [[74390, 5.1], [74385, 12.4]],
    "asks": [[74395, 4.8], [74400, 16.0]]
  },
  "walls": [
    { "side": "bid", "price": 74200, "qty": 41.2, "usd": 3057040, "dist": 0.26, "ratio": 312.5, "age": 840 }
  ]
}
FieldDescription
asOfSnapshot time in milliseconds. null means the book is still warming up for you; poll again.
bids / asksRaw levels as [price, qty], best-first: bids descending, asks ascending. Base-asset quantities. On a dense major, 1000 raw levels span only about 0.1% from the mid.
depthThe same book grouped server-side into price buckets covering about 1% per side. step is always 1, 2 or 5 times a power of ten, so any coarser power-of-ten grouping stays aligned. Bid buckets are floor-anchored at zero, ask buckets ceil-anchored.
wallsThe pair's tracked walls, the exact objects densities serves, saved here so one poll covers both.

Raw levels or depth: which to use

Use bids/asks when the question is about the touch: spread, top-of-book imbalance, queue sizes at the first ticks. Use depth when the question is about the shape: where liquidity sits relative to price, how lopsided the book is over a visible range, what a ladder or chart overlay should draw. Summing raw levels yourself only reproduces depth over a far thinner band, so reach for the histogram first when range matters.

Notes

  • Snapshots refresh once per second; polling faster returns identical data.
  • Books exist for crypto perpetuals only. Stock and commodity perps answer 422: the scanner does not maintain their books, so there is nothing to serve.
  • Interest expires about 15 seconds after your last call, and the engine flattens a bounded number of books at once, most recently requested first. Watching many pairs simultaneously works, but a tight rotation over a huge list will see warm-ups; prefer a working set.
  • A crossed or still-syncing book is never served: you either get a consistent snapshot or the warm-up shape.
For walls alone, densities is the cheaper call: it reads a venue-wide scan that exists whether or not anyone watches the pair, with no warm-up.