Crypto order book API: depth, execution price and slippage across exchanges
In short
- An order book API returns bid and ask levels — the price and size at each — as a REST snapshot or a WebSocket stream of changes. The best bid and ask only describe the first dollars of a trade.
- Depth sets the price of a large order. In a hypothetical example a $10,000 buy walks five levels, its average price lands 25 basis points above the book mid, and the cross-exchange spread shrinks from 1.20% to 0.70%.
- On the Pro and Max plans Genesis API returns ready-made execution prices for $500–$10,000, Order-book Δ for arbitrage rows, book age and depth, slippage history and a DEX slippage ladder. REST only; books lag the exchange by 5–20 seconds.
A crypto order book API returns the current buy and sell orders for a trading pair, grouped by price level: each level carries a price and the size resting at it. From those levels you compute the execution price of an order of a given size, its slippage and the market depth, and from two exchanges' books, how much of a spread survives an actual trade.
An exchange serves its own book as a REST snapshot or a WebSocket stream, while Genesis API on the Pro and Max plans serves ready-made execution prices, depth and Order-book Δ for many exchanges at once.
What an order book API returns
An order book is the list of resting limit orders for one pair. Buy orders (bids) are sorted from the highest price down, sell orders (asks) from the lowest price up. A level is one price and the total size at it; the gap between the best ask and the best bid is the book's spread.
A REST snapshot is the response to a single request: the levels at that moment. The Binance order book endpoint is public and needs no API key; here is a request for the top five BTC/USDT levels and a response (the numbers are hypothetical):
curl "https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=5"
{
"lastUpdateId": 81273645120,
"bids": [["96015.90000000", "1.25000000"], …],
"asks": [["96016.00000000", "0.84100000"], …]
}
Each level arrives as a pair of strings [price, quantity], with the quantity in coins: the best bid holds 1.25 × 96,015.9 = $120,019.88. The limit parameter defaults to 100 and goes up to 5,000 levels per side (Binance docs).
A WebSocket stream is pushed by the exchange over a persistent connection. Binance has two kinds of book streams: btcusdt@depth5, btcusdt@depth10 and btcusdt@depth20 push the top 5, 10 or 20 levels, while btcusdt@depth pushes only changes. Both update every 1000 ms, or every 100 ms with the @100ms suffix (Binance WebSocket streams).
A full local book is built from a snapshot plus the diff stream, matching the snapshot's lastUpdateId against the event update IDs; if an event is missed, the book is rebuilt from scratch.
| Method | What you get | Use it for |
|---|---|---|
| REST snapshot | Levels at request time, up to 5,000 per side on Binance | One-off checks, infrequent polling |
| WebSocket stream | Top levels or changes every 100–1000 ms | A local book in memory, a trading bot |
| Genesis API over REST | Levels as [price, USD amount], execution price, depth and book age | Comparing exchanges, checking a setup |
Why the best bid and ask mislead at size
The best ask is the price of the first level only. A market buy larger than that level takes the next, more expensive ones, and the average fill price climbs — that is slippage.
A hypothetical example: token ABC on exchange A, best bid 0.9996, best ask 1.0004, book mid 1.0000. A $10,000 market buy walks five ask levels:
| Ask price | In the book, $ | Taken, $ | Coins |
|---|---|---|---|
| 1.0004 | 1,100 | 1,100 | 1,099.56 |
| 1.0010 | 1,400 | 1,400 | 1,398.60 |
| 1.0018 | 2,600 | 2,600 | 2,595.33 |
| 1.0030 | 3,000 | 3,000 | 2,991.03 |
| 1.0050 | 6,000 | 1,900 | 1,890.55 |
The order buys 9,975.07 coins in total. The average fill price is the VWAP, the volume-weighted average price: 10,000 / 9,975.07 ≈ 1.0025.
Slippage from the best ask: (1.0025 − 1.0004) / 1.0004 × 100 ≈ 0.21%. From the book mid: (1.0025 − 1.0000) / 1.0000 × 10,000 = 25 basis points. Four of them are half the book spread, which every market buy pays; the other 21 come from depth.
Market depth within ±X% and walls
Market depth is the total size of orders within a given distance of the best price. In the example, asks within +0.2% of the best one, up to 1.0024, add up to 1,100 + 1,400 + 2,600 = $5,100, and within +0.5%, up to 1.0054, to $14,100.
Read depth as capacity: an order larger than the depth within +0.2% will fill at levels beyond that boundary. On exchange A a $5,000 buy fits inside it, and a $10,000 buy does not.
A wall is a large order on a single level, noticeably bigger than its neighbours: $6,000 at 1.0050 in the example. While a wall stands it holds the price, but it can be pulled a second before your order reaches it, and the buy then fills on the levels behind it.
In Genesis API depth comes from /orderbooks/book, one market's book, and /orderbooks/coin/{coin}, a coin's books on every exchange and market at once (Market order book, Coin order books). The response carries the top 10 bids and asks as [price, USD amount], the largest walls in walls_bid and walls_ask, and the whole side's depth within ±50% of the best price in depth_bid_usd and depth_ask_usd. A ±50% corridor is wide, so for a specific size look at the levels or the ready-made execution price.
Book age: stale books and limited depth
Every book snapshot has an age. If one exchange's book is 15 seconds older than the other's, part of the spread between them may be a timing gap: the price on the older book has already moved.
In Genesis API books lag the exchange by 5–20 seconds, and each one carries its age. The beginning of an /orderbooks/book response from the docs:
{
"exchange": "Binance",
"market": "spot",
"coin": "BTC",
"book_ts": 1794675858,
"age_sec": 6,
"stale": false,
"source": "ws",
"depth_limited": false,
"levels_bid": 500,
"levels_ask": 500,
…
}
book_ts is the book's time in unix seconds, age_sec its age in seconds, and stale: true marks a book older than 30 seconds. source shows how the book was taken from the exchange: over WebSocket (ws) or by REST requests (rest).
depth_limited: true means the exchange publishes limited depth: the totals are partial, and a large order may not fill. When the orders run out, /orderbooks/exec returns null instead of a price, and Order-book Δ returns the exhausted status.
Executable spread between exchanges: Order-book Δ
Back to the hypothetical example. On exchange B the last trade printed at 1.0120, the best bid is 1.0116 and the ask 1.0124. B's bids hold $1,100 at 1.0116, $1,300 at 1.0110, $2,800 at 1.0102, $2,900 at 1.0090 and $5,000 at 1.0070.
Selling $10,000 into those bids gives a VWAP of 1.0095 by the same formula. That is (1.0120 − 1.0095) / 1.0120 × 10,000 ≈ 24.7 basis points below B's book mid.
| How the spread is computed | Buy on A → sell on B | Spread |
|---|---|---|
| Last trades, as in a table row | 1.0000 → 1.0120 | 1.20% |
| Best book prices | 1.0004 → 1.0116 | 1.12% |
| After executing $10,000 | 1.0025 → 1.0095 | 0.70% |
Row spread: (1.0120 − 1.0000) / 1.0000 × 100 = 1.20%. After execution: (1.0095 − 1.0025) / 1.0025 × 100 ≈ 0.70%. The row promises $120 on $10,000, and about $70 is left after the books: 10,000 × 0.006983 ≈ 69.83.
Of the 50 basis points lost, 8 went to the gap between the last trade and the best orders, and the other 42 to the depth of the two books.
Order-book Δ is what Genesis Arbitrage calls a row's spread recomputed through the order books for a given size; on the site it is the "Δ by orders" column of the arbitrage tables, for example Spot – Futures. In the API it comes from /orderbooks/spreads/{dataset}: every row of one coin in the spot-spot, spot-futures, futures-futures, dex-spot or dex-futures dataset gets an order_delta object (Order-book Δ).
order_delta carries buy_price and sell_price for the chosen size, the post-execution spread_pct and a status: ok, no_book (no book) or exhausted (the book did not fill). The volume is 0 (best book prices) or 500, 1000, 2500, 5000, 10000, and the result never exceeds the row's spread. DEX rows carry side and cex_price instead of a price pair: the CEX side and its execution price.
The execution prices themselves, for every market at once, come from /orderbooks/exec: a [buy price, sell price] pair under a key like Binance|spot|BTC, with null where the book is too thin (Execution prices).
The full setup, with the coin transfer and network checks, is covered in Cross-exchange crypto arbitrage.
Python example: row spread vs spread after execution
The script takes Spot – Spot setups with a spread of at least 0.5%, requests Order-book Δ at $5,000 for the ten coins with the widest spreads and prints how many basis points the books ate. The key comes from the GENESIS_API_KEY environment variable. On 429 and 503 the script waits Retry-After seconds, and if the wait is longer than a minute — the monthly quota is used up — it stops.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
VOLUME = 5000 # dollars per leg
MIN_SPREAD = 0.5 # row spread, %
def get(path, params):
for _ in range(3):
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # the monthly quota is used up
break
time.sleep(wait)
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("API did not answer, try again later")
rows = get("/arbitrage/spot-spot", {"min_spread": MIN_SPREAD})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
coins = list(dict.fromkeys(x["coin"] for x in rows))[:10]
for coin in coins:
data = get("/orderbooks/spreads/spot-spot",
{"coin": coin, "volume": VOLUME})
for row in data:
od = row["order_delta"]
if row["spread_pct"] < MIN_SPREAD or od["status"] != "ok":
continue # no_book or exhausted: the size will not fill
lost = (row["spread_pct"] - od["spread_pct"]) * 100
print(f'{coin} {row["exchange_buy"]}→{row["exchange_sell"]}'
f' {row["spread_pct"]:.2f}% → {od["spread_pct"]:.2f}%,'
f' the books ate {lost:.0f} bps')
time.sleep(0.25) # up to 4 requests per second: Pro allows 5
The script makes up to 11 calls with a 0.25 s pause between coins. Run it in a loop no more often than meta.freshness_sec: 10 s on Pro and 5 s on Max (Genesis API limits). To add notifications to it, see Crypto arbitrage bot in Python.
Execution cost history
A single snapshot cannot tell you whether the current slippage is normal for the market or the book is thinner than usual. /orderbooks/exec-history returns the history from Genesis Charts: how many basis points from the book mid an execution of $500, $1,000, $2,500, $5,000 and $10,000 cost, separately for buys and sells (Execution history).
Each interval has 360 points: 1m covers 6 hours, 15m 3.75 days, 1h 15 days and 1d about a year, with data since 6 September 2026. A request takes up to 8 markets in the keys parameter. Buy values are positive and sell values negative; null means no data or the book did not fill. Genesis API does not serve past snapshots of the book itself.
import os
import statistics
import requests
KEY = "Binance|spot|BTC"
r = requests.get(
"https://api.genesisarbitrage.com/v1/orderbooks/exec-history",
headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
params={"keys": KEY, "interval": "1h"}, # 360 hours, 15 days
timeout=15,
)
r.raise_for_status()
data = r.json()["data"]
series = data["series"][KEY]
if series is None:
raise SystemExit("market not found: " + KEY)
i = data["volumes_usd"].index(10000) # the $10,000 buy series
buy = series["buy"][i]
known = [x for x in buy if x is not None]
if not known:
raise SystemExit("no data for the period")
print("15-day median, bps:", statistics.median(known))
print("latest point, bps:", buy[-1])
Hypothetically, if the 15-day median is 12 basis points and the latest point is 25, execution now costs twice the usual, and it makes sense to raise the spread threshold for this coin.
DEX: slippage ladder, token taxes and honeypots
A DEX pool has no order book: the swap price comes from the pool's formula, and the larger the trade relative to liquidity, the further the price moves. That is why a DEX leg is assessed with a ladder — slippage at a series of sizes.
/orderbooks/dex-slippage returns, per contract, buy and sell slippage at $100, $500, $1,000, $2,500, $5,000, $10,000, $20,000, $50,000 and $100,000, token taxes and the honeypot flag, the same as the DEX table columns on the site (DEX slippage). In the docs' sample response, buy slippage is 0.86% at $10,000, 3.12% at $50,000 and 6.05% at $100,000.
That sets the limit of a setup: a 2% DEX – CEX spread survives the pool's slippage at $10,000 but not at $50,000, even before fees. null in the ladder means the pool lacks liquidity for that size, and network gas is not in the response, so budget for it separately.
tax_buy_pct and tax_sell_pct are the token's buy and sell tax in %; null means there is no source and must not be read as zero. honeypot: no — no signs, suspect — sources disagree, yes — selling the token may be impossible.
For a manual token check, see How to check a token before buying; for DEX prices and liquidity next to CEX, see DEX API.
Order books in Genesis API: endpoints and plans
| Task | Endpoint |
|---|---|
| Execution price for $500–$10,000 on every market | /orderbooks/exec |
| A row's spread after execution | /orderbooks/spreads/{dataset} |
| 10 levels, walls, depth and book age | /orderbooks/book |
| A coin's books on every exchange | /orderbooks/coin/{coin} |
| Execution cost history | /orderbooks/exec-history |
| DEX slippage, taxes and the honeypot flag | /orderbooks/dex-slippage |
All six are part of the Pro and Max API plans. Pro costs $100 a month: 5M calls, 5 requests per second, 10 s freshness. Max costs $200: 10M calls, 15 requests per second, 5 s; on Trial and Start the order book endpoints return 403 plan_restricted.
Parameters and response examples are in the order book endpoints guide; for an overview of the API's data, see Crypto API and the lesson API data for arbitrage.
Questions and answers
Why is the spread in the table bigger than what I get in a trade?
The row spread comes from last trades, while a market order fills against the book, and the larger the size, the further its average price drifts from the best one. Fees and the price move during the transfer come on top. Order-book Δ shows how much of the spread is left at your size.
How often do order books update?
A book changes with every new order and cancellation; the Binance stream pushes changes every 100 or 1000 ms. In Genesis API books lag the exchange by 5–20 seconds (the age is in age_sec), and responses refresh every 10 seconds on Pro and every 5 seconds on Max.
Does Genesis API have a WebSocket for order books?
No. Genesis API is REST only: an HTTP GET request and a JSON response. Real-time book streams come from the exchanges' own WebSockets, and that is what a bot placing orders through an exchange's trading API needs.
Is there a free order book API?
Exchanges have public endpoints: the Binance book at /api/v3/depth answers without a key, but it covers one exchange, and you compute the execution price yourself. Genesis API has no free plan; order books are included in Pro at $100 a month and Max at $200.