Genesis API 订单簿接口:成交价格、订单簿 Δ、订单簿、历史与 DEX
简而言之
- API Pro 和 Max 套餐中的六个订单簿接口,返回与站点“订单簿 Δ”列、“订单簿”窗口和 Genesis Charts 相同的数据。
- 成交价格是 $500、$1,000、$2,500、$5,000 或 $10,000 市价单的平均价格;
null表示订单簿太薄,无法满足该数量。 - 订单簿比交易所滞后 5–20 秒:请检查
age_sec和stale,交易前再到交易所终端查看订单簿。
Genesis API 的订单簿 API 由六个接口组成,用来看一笔指定金额的交易还能保留多少价差。它们返回指定数量的成交价格、套利行的订单簿 Δ、带深度的订单簿、滑点历史和 DEX 滑点——与站点的“订单簿 Δ”列和 Genesis Charts 是同一批数据。
六个订单簿接口
| 接口 | 返回内容 | 必填 | 文档 |
|---|---|---|---|
/orderbooks/exec | 每个市场在指定数量下的买入和卖出价格 | volume | 成交价格 |
/orderbooks/spreads/{dataset} | 套利数据集中某个币种各行的订单簿 Δ | coin | 订单簿 Δ |
/orderbooks/book | 单个市场的订单簿:10 档、挂单墙、深度、时效 | exchange、market、coin | 市场订单簿 |
/orderbooks/coin/{coin} | 某个币种在所有交易所和市场的订单簿 | 路径中的币种 | 币种订单簿 |
/orderbooks/exec-history | 滑点历史,每次请求最多 8 个市场 | keys、interval | 成交历史 |
/orderbooks/dex-slippage | 每个合约的滑点、税率和 honeypot 标志 | — | DEX 滑点 |
这六个接口都包含在 API 套餐 Pro(每月 $100)和 Max($200)中;Trial 和 Start 会返回 403 plan_restricted。在 /orderbooks/exec 和历史接口的 keys 参数中,市场写作 Exchange|market|COIN,例如 Binance|spot|BTC。下面的响应示例展示的是经过精简的 data 字段。
订单簿数据的整体介绍,请参阅 订单簿 API 一文。
指定数量的成交价格
成交价格是指定大小的市价单吃穿订单簿时的平均价格:买入吃卖单,卖出砸买单,因此它就是这笔交易所消耗订单的 VWAP。/orderbooks/exec 针对网格中的一个数量,返回所有市场的成交价格。
| 参数 | 类型 | 作用 |
|---|---|---|
volume | 数字 | 以 USD 计的数量:500、1000、2500、5000 或 10000,必填 |
exchange | 字符串 | 按交易所筛选;多个用逗号分隔 |
market | 字符串 | spot 或 futures |
coin | 字符串 | 币种代码,例如 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],
…
}
}
每个市场键对应的值是 [买入价, 卖出价]。用 null 代替价格,表示订单簿太薄,无法满足该数量:示例中 Ourbit 上 SHELL 的买单承接不了 $1,000 的卖出。不带筛选时,响应包含所有市场,只需要一个币种时请传 coin。
订单簿 Δ:吃穿订单簿后的价差
订单簿 Δ 是按指定数量、通过订单簿重新计算的套利行价差。/orderbooks/spreads/{dataset} 会取出所选数据集中某个币种的所有行,并为每一行添加一个 order_delta 对象,公式与站点该列相同。
| 参数 | 类型 | 作用 |
|---|---|---|
{dataset} | 字符串,位于路径中 | spot-spot、spot-futures、futures-futures、dex-spot 或 dex-futures |
coin | 字符串 | 币种代码,必填 |
volume | 数字 | 默认 0——订单簿最优价格;或 500、1000、2500、5000、10000 |
对于 CEX 配对,买入吃 exchange_buy 的卖单,卖出砸 exchange_sell 的买单。order_delta 包含 buy_price 和 sell_price,结果不会超过该行的 spread_pct。
对于 DEX 行,价差的符号决定 CEX 一侧:spread_pct ≥ 0 时,代币卖入 CEX 买单;价差为负时,从卖单买入。order_delta 包含 side 和 cex_price(CEX 成交价);如果吃穿订单簿后符号反转,Δ 为 0。
status 字段:ok——已计算,no_book——没有订单簿,exhausted——订单簿无法满足该数量。
假设的例子:币种 XYZ,在 MEXC 以 2.000 买入,在 Gate 以 2.016 卖出,行价差 0.8%。针对 $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"
}
}
该行的其他字段与 /arbitrage/spot-spot 相同。行价差:(2.016 − 2.000) / 2.000 × 100 = 0.8%。
对于 $5,000,通过 MEXC 订单簿买入的平均价为 2.004,卖入 Gate 订单簿得到 2.010:(2.010 − 2.004) / 2.004 × 100 ≈ 0.2994%。在 0.8% 中,这个大小下约有 0.3% 留得住——扣除手续费和转账前约 $15:5,000 × 0.002994 ≈ 14.97。
Python 示例:订单簿前后的价差
脚本针对 Spot – Spot 数据集中的 BTC,在 $5,000 下并排打印行价差和吃穿订单簿后的价差。密钥取自环境变量 GENESIS_API_KEY;遇到 429 和 503 时,脚本会等待 Retry-After 秒。
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}')
循环轮询时,间隔不要短于 meta.freshness_sec 秒:Pro 为 10 秒,Max 为 5 秒。配额和限制见 Genesis API 限额 指南。
市场订单簿与币种订单簿
/orderbooks/book 返回单个市场的订单簿,与站点的“订单簿”窗口一致。三个必填参数确定市场:exchange(不区分大小写)、market(spot 或 futures)和 coin。/orderbooks/coin/{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
}
| 字段 | 含义 |
|---|---|
best_bid、best_ask | 最优买价和卖价 |
bids、asks | 前 10 档:[价格, USD 金额] |
walls_bid、walls_ask | 最大挂单墙:[价格, USD 金额] |
depth_bid_usd、depth_ask_usd | 最优价 ±50% 范围内该侧的深度,USD |
book_ts、age_sec、stale | 订单簿时间及其时效(秒);stale——超过 30 秒 |
source、depth_limited | 订单簿来源(ws 或 rest)和深度受限标志 |
depth_bid_usd 和 depth_ask_usd 中的市场深度,就是订单簿一侧挂着多少美元的订单:示例中,Binance 上 BTC 在最优卖价 +50% 范围内约有 $5,880 万的卖单。
当 depth_limited: true 时,交易所只公布部分订单簿,大额数量可能无法成交。如果该交易所、市场和币种没有订单簿,会返回 404。
成交历史
/orderbooks/exec-history 是来自 Genesis Charts 的滑点历史:网格中每个数量下,成交成本偏离订单簿中间价多少个基点(1 bp = 0.01%)。一次请求的 keys 最多接受 8 个市场,用逗号分隔;interval 必填。
interval | 点间隔 | 360 个点覆盖 |
|---|---|---|
1m | 1 分钟 | 6 小时 |
15m | 15 分钟 | 3.75 天 |
1h | 1 小时 | 15 天 |
1d | 1 天 | 约一年 |
数据自 2026 年 9 月 6 日起采集,因此日线序列只从该日期开始有数据。
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 和 sell 各包含五个序列,对应 volumes_usd 中的每个数量,每个序列有 360 个值,从最旧到最新。最后一个点属于 last_bucket_ts,第 i 个点属于 last_bucket_ts − (points − 1 − i) × step_sec。买入值为正,卖出值为负:平均成交价分别高于和低于订单簿中间价。
序列 [5, 7, 9, …] 是 $10,000 的买入:前几个点的成本为 5–9 bp,即高于中间价 0.05–0.09%。序列中的 null 表示没有数据或订单簿未能成交;用 null 代替市场对象,表示键未知。
DEX 滑点
/orderbooks/dex-slippage 描述一个套利机会的 DEX 腿:$100 到 $100,000 的买入和卖出滑点、代币税,以及每个合约的 honeypot 标志——与站点 DEX 表格的列相同。筛选条件:contract(多个用逗号分隔)和 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
}
]
}
滑点数组与 sizes_usd 网格一一对应:示例中 $5,000 的买入滑点 0.58%,$100,000 的买入滑点 6.05%。数组中的 null 表示资金池在该规模下流动性不足。
tax_buy_pct 和 tax_sell_pct 是代币的买入税和卖出税,单位 %;null 表示没有数据来源,而不是 0%。honeypot:no;suspect——来源之间不一致;yes——可能无法卖出。
如何用订单簿核对一个机会
选取一条套利行
在
/arbitrage/spot-spot或其他数据集中找到一个机会——参见 套利接口。记下币种、交易所和spread_pct。通过订单簿重新计算价差
用该币种和您的交易规模请求
/orderbooks/spreads/spot-spot,并比较spread_pct与order_delta.spread_pct。检查时效与深度
对两条腿分别调用
/orderbooks/book:age_sec、stale和depth_limited告诉您数字是否可信,挂单墙则显示价格可能停滞的位置。与历史对比
/orderbooks/exec-history显示这个滑点对该市场是否正常:1m覆盖 6 小时,1h覆盖 15 天。检查 DEX 腿的税率
对于 DEX – Spot 和 DEX – Futures 机会,用该行的合约请求
/orderbooks/dex-slippage:滑点、税率和honeypot。
常见问题
订单簿 Δ 与普通价差有什么区别?
行的 spread_pct 使用交易所的最新成交价;订单簿 Δ 使用指定数量下市价单的平均价格。两者之差,就是订单簿吃掉的部分。
为什么得到的是 null 而不是价格?
在 /orderbooks/exec 中,订单簿里该数量对应的订单太少;在订单簿 Δ 中,同样的情况是 exhausted 状态。在成交历史中,null 表示该点没有数据;在 DEX 滑点中,则表示资金池流动性不足。
能计算超过 $10,000 的成交吗?
/orderbooks/exec 和订单簿 Δ 的网格固定在 $500 到 $10,000。更大的规模请查看 /orderbooks/book 中的深度和挂单墙;DEX 腿的 /orderbooks/dex-slippage 最高到 $100,000。