Genesis API order book endpoints: execution price, Order-book Δ, book, history and DEX
In short
- Six order book endpoints on the API Pro and Max plans return the same data the site shows in the "Δ by orders" column, the "Order book" window and Genesis Charts.
- The execution price is the average price of a market trade for $500, $1,000, $2,500, $5,000 or $10,000;
nullmeans the book is too thin for that volume. - Books lag the exchange by 5–20 seconds: check
age_secandstale, and look at the book in the exchange terminal before you trade.
The order book API in Genesis API is six endpoints that show how much of a spread survives a trade of a given size. They return execution prices for a volume, Order-book Δ for arbitrage rows, an order book with its depth, slippage history and DEX slippage — the same data as the "Δ by orders" column and Genesis Charts on the site.
Six order book endpoints
| Endpoint | Returns | Required | Docs |
|---|---|---|---|
/orderbooks/exec | Buy and sell prices for a volume on every market | volume | Execution prices |
/orderbooks/spreads/{dataset} | Order-book Δ for one coin's rows in an arbitrage dataset | coin | Order-book Δ |
/orderbooks/book | One market's book: 10 levels, walls, depth, age | exchange, market, coin | Market order book |
/orderbooks/coin/{coin} | A coin's books on every exchange and market | coin in the path | Coin order books |
/orderbooks/exec-history | Slippage history, up to 8 markets per request | keys, interval | Execution history |
/orderbooks/dex-slippage | Slippage, taxes and the honeypot flag per contract | — | DEX slippage |
All six are part of the API plans Pro ($100 a month) and Max ($200); on Trial and Start they return 403 plan_restricted. In /orderbooks/exec and in the history keys parameter a market is written as Exchange|market|COIN, for example Binance|spot|BTC. The response examples below show the data field, shortened.
For an overview of order book data, see the article on the order book API.
Execution price for a volume
The execution price is the average price at which a market order of a given size walks the book: a buy takes the asks, a sell hits the bids, so it is the VWAP of the orders the trade consumes. /orderbooks/exec returns it for every market at one volume from the grid.
| Parameter | Type | What it does |
|---|---|---|
volume | number | Volume in USD: 500, 1000, 2500, 5000 or 10000, required |
exchange | string | Filter by exchange; comma-separated for several |
market | string | spot or futures |
coin | string | Coin ticker, e.g. BTC |
curl "https://api.genesisarbitrage.com/v1/orderbooks/exec?volume=1000" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"volume": 1000,
"markets": {
"Binance|spot|BTC": [96021.5, 96010.2],
"ByBit|futures|BTC": [96030.1, 96018.7],
"Ourbit|spot|SHELL": [0.10418, null],
…
}
}
The value for each market key is [buy price, sell price]. null instead of a price means the book is too thin for that volume: in the example the SHELL bids on Ourbit cannot absorb a $1,000 sell. Without filters the response holds every market, so pass coin when you need one coin.
Order-book Δ: the spread after walking the book
Order-book Δ is an arbitrage row's spread recomputed through the order books for a given volume. /orderbooks/spreads/{dataset} takes every row of one coin in the chosen dataset and adds an order_delta object to each, using the same formulas as the column on the site.
| Parameter | Type | What it does |
|---|---|---|
{dataset} | string, in the path | spot-spot, spot-futures, futures-futures, dex-spot or dex-futures |
coin | string | Coin ticker, required |
volume | number | 0 by default — best book prices; or 500, 1000, 2500, 5000, 10000 |
For CEX pairs the buy goes through the asks of exchange_buy and the sell into the bids of exchange_sell. order_delta carries buy_price and sell_price, and the result never exceeds the row's spread_pct.
For DEX rows the sign of the spread sets the CEX side: with spread_pct ≥ 0 the token is sold into the CEX bids, with a negative spread it is bought from the asks. order_delta carries side and cex_price, the CEX execution price; if the sign flips after walking the book, Δ is 0.
The status field: ok — computed, no_book — no book, exhausted — the book did not fill the volume.
A hypothetical example: coin XYZ, buy on MEXC at 2.000, sell on Gate at 2.016, row spread 0.8%. An Order-book Δ request for $5,000:
curl -G \
"https://api.genesisarbitrage.com/v1/orderbooks/spreads/spot-spot" \
-d coin=XYZ -d volume=5000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"coin": "XYZ",
"exchange_buy": "MEXC",
"exchange_sell": "Gate",
"market_buy": "spot",
"market_sell": "spot",
"price_buy": 2.0,
"price_sell": 2.016,
"ask_buy": 2.001,
"bid_sell": 2.015,
"spread_pct": 0.8,
"order_delta": {
"volume": 5000,
"buy_price": 2.004,
"sell_price": 2.01,
"spread_pct": 0.2994,
"status": "ok"
}
}
The row's other fields are as in /arbitrage/spot-spot. Row spread: (2.016 − 2.000) / 2.000 × 100 = 0.8%.
For $5,000, buying through the MEXC book averages 2.004 and selling into the Gate book gets 2.010: (2.010 − 2.004) / 2.004 × 100 ≈ 0.2994%. Of the 0.8%, about 0.3% survives at this size — roughly $15 before fees and the transfer: 5,000 × 0.002994 ≈ 14.97.
Python example: spread before and after the book
The script prints the row spread next to the spread after the book for BTC in the Spot – Spot dataset at $5,000. The key comes from the GENESIS_API_KEY environment variable; on 429 and 503 the script waits Retry-After seconds.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
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):
# rate limit or data being rebuilt
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("API is busy, try again later")
rows = get("/orderbooks/spreads/spot-spot",
{"coin": "BTC", "volume": 5000})
for row in rows:
od = row["order_delta"]
if od["status"] == "ok":
after = f'{od["spread_pct"]:.4f}%'
else:
after = od["status"] # no_book or exhausted
print(f'{row["exchange_buy"]} → {row["exchange_sell"]}: '
f'{row["spread_pct"]}% → {after}')
In a loop, poll no more often than once per meta.freshness_sec seconds: 10 s on Pro, 5 s on Max. Quota and limits are covered in the Genesis API limits guide.
Market order book and coin order books
/orderbooks/book returns one market's book, like the "Order book" window on the site. Three required parameters define the market: exchange (case-insensitive), market (spot or futures) and coin. /orderbooks/coin/{coin} returns an array of the same objects for every exchange and market of the coin.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/book" \
-d exchange=Binance -d market=spot -d coin=BTC \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"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,
"best_bid": 96015.9,
"best_ask": 96016,
"bids": [[96015.9, 412300.5], [96015.8, 51020.3], …],
"asks": [[96016, 388120.2], [96016.1, 20410.7], …],
"walls_bid": [[95900, 2410000]],
"walls_ask": [[96500, 1980000]],
"depth_bid_usd": 61234567,
"depth_ask_usd": 58765432
}
| Field | Meaning |
|---|---|
best_bid, best_ask | Best bid and ask |
bids, asks | Top 10 levels: [price, USD amount] |
walls_bid, walls_ask | Largest walls: [price, USD amount] |
depth_bid_usd, depth_ask_usd | Side depth within ±50% of the best price, USD |
book_ts, age_sec, stale | Book time and its age in seconds; stale — older than 30 s |
source, depth_limited | Book source (ws or rest) and the limited-depth flag |
Market depth in depth_bid_usd and depth_ask_usd is how many dollars of orders sit on one side of the book: in the example, about $58.8M of asks for BTC on Binance within +50% of the best ask.
With depth_limited: true the exchange publishes a partial book, and a large volume may not fill. If there is no book for that exchange, market and coin, you get 404.
Execution history
/orderbooks/exec-history is the slippage history from Genesis Charts: what execution cost at each grid volume, in basis points from the book mid (1 bp = 0.01%). One request takes up to 8 markets in keys, comma-separated; interval is required.
interval | Point step | 360 points cover |
|---|---|---|
1m | 1 minute | 6 hours |
15m | 15 minutes | 3.75 days |
1h | 1 hour | 15 days |
1d | 1 day | about a year |
Data has been collected since 6 September 2026, so the daily series is filled only from that date.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/exec-history" \
--data-urlencode "keys=Binance|spot|BTC,ByBit|futures|BTC" \
-d interval=1h \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"interval": "1h",
"step_sec": 3600,
"points": 360,
"volumes_usd": [500, 1000, 2500, 5000, 10000],
"last_bucket_ts": 1794672000,
"series": {
"Binance|spot|BTC": {
"buy": [[1, 1, 2, …], [1, 2, 2, …], [2, 3, 4, …],
[3, 4, 6, …], [5, 7, 9, …]],
"sell": [[-1, -1, -2, …], …]
},
"ByBit|futures|BTC": { … }
}
}
buy and sell each hold five series, one per volume in volumes_usd, each with 360 values from oldest to newest. The last point belongs to last_bucket_ts, and point i to last_bucket_ts − (points − 1 − i) × step_sec. Buy values are positive and sell values negative: the average trade price sits above and below the book mid.
The [5, 7, 9, …] series is a $10,000 buy: its first points cost 5–9 bp, or 0.05–0.09% over the mid. null in a series means no data or the book did not fill; null instead of a market object means an unknown key.
DEX slippage
/orderbooks/dex-slippage describes the DEX leg of a setup: buy and sell slippage for $100 to $100,000, token taxes and the honeypot flag per contract — the same as the DEX table columns on the site. Filters: contract (comma-separated for several) and network.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/dex-slippage" \
-d contract=0x6982508145454ce325ddbe47a25d4ec3d2311933 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"sizes_usd": [100, 500, 1000, 2500, 5000, 10000, 20000, 50000,
100000],
"contracts": [
{
"contract": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"network": "ETH",
"tax_buy_pct": 0,
"tax_sell_pct": 0,
"honeypot": "no",
"slippage_buy_pct": [0.31, 0.33, 0.36, 0.44, 0.58, 0.86,
1.41, 3.12, 6.05],
"slippage_sell_pct": [0.31, 0.34, 0.37, 0.46, 0.61, 0.9,
1.5, 3.3, 6.4],
"updated_at": 1794671040
}
]
}
The slippage arrays follow the sizes_usd grid: in the example a $5,000 buy slips 0.58% and a $100,000 buy 6.05%. null in an array means the pool lacks liquidity for that size.
tax_buy_pct and tax_sell_pct are the token's buy and sell tax, %; null means there is no source, not 0%. honeypot: no; suspect — sources disagree; yes — selling may be impossible.
How to check a setup against the books
Take an arbitrage row
Find a setup in
/arbitrage/spot-spotor another dataset — see Arbitrage endpoints. Note the coin, the exchanges andspread_pct.Recompute the spread through the books
Request
/orderbooks/spreads/spot-spotwith that coin and your trade size and comparespread_pctwithorder_delta.spread_pct.Check freshness and depth
Call
/orderbooks/bookfor both legs:age_sec,staleanddepth_limitedtell you whether to trust the numbers, and the walls show where the price may stall.Compare with history
/orderbooks/exec-historyshows whether this slippage is normal for the market:1mcovers 6 hours,1hcovers 15 days.Check taxes on the DEX leg
For DEX – Spot and DEX – Futures setups, request
/orderbooks/dex-slippagefor the row's contract: slippage, taxes andhoneypot.
Questions and answers
How is Order-book Δ different from the regular spread?
A row's spread_pct uses the exchanges' last prices; Order-book Δ uses the average prices of market trades at the given volume. The difference between them is what the book takes.
Why do I get null instead of a price?
In /orderbooks/exec the book has too few orders for that volume; in Order-book Δ the same case is the exhausted status. In execution history null means no data for the point, and in DEX slippage it means the pool lacks liquidity.
Can I compute execution above $10,000?
The /orderbooks/exec and Order-book Δ grid is fixed at $500 to $10,000. For larger sizes, look at depth and walls in /orderbooks/book; for the DEX leg, /orderbooks/dex-slippage goes up to $100,000.