Genesis Arbitrage

Genesis Arbitrage · · 阅读约 20 分钟

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 个点覆盖
1m1 分钟6 小时
15m15 分钟3.75 天
1h1 小时15 天
1d1 天约一年

数据自 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——可能无法卖出。

如何用订单簿核对一个机会

  1. 选取一条套利行

    在 /arbitrage/spot-spot 或其他数据集中找到一个机会——参见 套利接口。记下币种、交易所和 spread_pct。

  2. 通过订单簿重新计算价差

    用该币种和您的交易规模请求 /orderbooks/spreads/spot-spot,并比较 spread_pct 与 order_delta.spread_pct。

  3. 检查时效与深度

    对两条腿分别调用 /orderbooks/book:age_sec、stale 和 depth_limited 告诉您数字是否可信,挂单墙则显示价格可能停滞的位置。

  4. 与历史对比

    /orderbooks/exec-history 显示这个滑点对该市场是否正常:1m 覆盖 6 小时,1h 覆盖 15 天。

  5. 检查 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。