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.
/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
| Parameter | In | Description |
|---|---|---|
exchange | query | Venue whose book to read. See Exchanges. Default: Binance. Each venue's book is its own market. |
levels | query | Cap on raw levels per side, 1 to 1000 (default 1000). The depth histogram is always complete regardless. |
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 }
]
}| Field | Description |
|---|---|
asOf | Snapshot time in milliseconds. null means the book is still warming up for you; poll again. |
bids / asks | Raw 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. |
depth | The 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. |
walls | The 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.