Genesis API 套利接口:CEX、DEX、跨链与股票
简而言之
- 七个接口返回网站表格中的交易对:三个 CEX 数据集所有套餐可用,股票从 Start 起,DEX – Spot、DEX – Futures 和 Cross-chain 仅限 Pro 与 Max。
- 一条 CEX 数据包含两家交易所的价格和最优报价、网络、合约、充值与提现状态以及成交量——用来挑选真正可以执行的交易对。
- 响应中的价差是快照时刻的价格差:手续费、转账和滑点不会从中扣除。
Genesis API 套利接口返回的交易对与 Genesis Arbitrage 表格一致:CEX 现货与合约市场之间、DEX 与 CEX 之间、不同网络之间以及代币化股票的价差。每个 data 元素就是一个交易对:在哪里买入、在哪里卖出、价差(以百分比表示的价格差),以及用来核实它的字段:充值与提现状态、成交量、流动性和链接。七个接口都是 GET 请求,密钥放在 X-API-Key 请求头中。
七个接口与套餐
| 接口 | 返回内容 | 套餐 |
|---|---|---|
/arbitrage/spot-spot | CEX 现货市场之间的价差 | Trial、Start、Pro、Max |
/arbitrage/spot-futures | CEX 上的现货与合约 | Trial、Start、Pro、Max |
/arbitrage/futures-futures | CEX 交易所之间的合约 | Trial、Start、Pro、Max |
/arbitrage/dex-spot | DEX 价格与 CEX 现货 | Pro、Max |
/arbitrage/dex-futures | DEX 价格与 CEX 合约 | Pro、Max |
/arbitrage/crosschain | 同一代币在不同网络的 DEX 价格 | Pro、Max |
/arbitrage/stocks | CEX 上的代币化股票、金属、指数和大宗商品 | Start、Pro、Max |
超出套餐范围的接口会返回 403 plan_restricted;错误代码见 Genesis API 响应与错误,价格见 Genesis API 价格页面。
CEX:Spot – Spot、Spot – Futures、Futures – Futures
三个 CEX 接口参数相同,返回的行格式也相同。market_buy 和 market_sell 字段表示买卖两侧的市场:spot 与 spot、spot 与 futures,或 futures 与 futures。
| 参数 | 类型 | 作用 | 示例 |
|---|---|---|---|
coin | string | 按币种代码筛选 | coin=BTC |
exchange | string | 按交易所筛选;多个用逗号分隔 | exchange=Binance,OKX |
min_spread | number | 最小价差,% | min_spread=1 |
min_volume | number | 两侧最小 24 小时成交量,USD | min_volume=50000 |
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-d min_spread=1 -d min_volume=50000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-futures" \
-d coin=BTC -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/futures-futures" \
-d exchange=Binance,OKX -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
来自 Spot — Spot 文档的响应行(节选):
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"market_buy": "spot",
"market_sell": "spot",
"price_buy": 0.0007029,
"price_sell": 0.0007037,
"ask_buy": 0.0007029,
"bid_sell": 0.0007021,
"spread_pct": 0.11,
"network": "ETH",
"contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
"withdraw_enabled_buy": true,
"deposit_enabled_sell": true,
"volume_24h_buy": 17652.64,
"volume_24h_sell": 12512.51,
"trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
…
}
| 字段 | 类型 | 内容 |
|---|---|---|
exchange_buy, exchange_sell | string | 买入交易所和卖出交易所 |
market_buy, market_sell | string | 该侧的市场:spot 或 futures |
price_buy, price_sell | number | 计算价差所用的价格 |
bid_*, ask_* | number 或 null | 每侧的最优买价和卖价 |
spread_pct | number | 价差,% |
network, contract | string;string 或 null | 代币网络和合约地址 |
deposit_enabled_*, withdraw_enabled_* | boolean | 各交易所是否开放充值和提现 |
volume_24h_buy, volume_24h_sell | number 或 null | 24 小时成交量,USD |
trade_url_buy, trade_url_sell | string | 交易终端链接 |
spread_pct 由 price_buy 和 price_sell 计算得出,即网站上的“价格”列,也就是最新成交价。实际成交要经过订单簿:以 ask_buy 买入,以 bid_sell 卖出。示例中 bid_sell 低于 ask_buy,因此按最优报价计算,该交易对为负:
(0.0007021 − 0.0007029) / 0.0007029 × 100 ≈ −0.11%
你的下单规模对应的精确价差来自 Order-book Δ,即 GET /orderbooks/spreads/{dataset},详见订单簿接口指南。
可转移的 Spot – Spot 交易对
跨交易所现货交易对只有在币可以转移时才成立:在一家交易所买入,提现,再在另一家到账。这要求买入交易所开放提现(withdraw_enabled_buy),卖出交易所开放充值(deposit_enabled_sell)。请求中没有针对这些标志的参数,因此需要在代码中筛选,而 min_volume 在服务端剔除流动性差的币。
import os
import requests
r = requests.get(
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot",
headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
params={"min_spread": 1, "min_volume": 50000},
timeout=15,
)
r.raise_for_status()
rows = r.json()["data"]
# 只有买入交易所开放提现、
# 卖出交易所开放充值时,转移才可行
ok = [x for x in rows
if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
ok.sort(key=lambda x: x["spread_pct"], reverse=True)
for x in ok[:10]:
print(f'{x["coin"]:<8} {x["exchange_buy"]} → '
f'{x["exchange_sell"]} {x["spread_pct"]}% '
f'网络 {x["network"]}')
429 和 503 的重试使用 Genesis API 响应与错误中的 get_json 函数。把这些交易对推送到 Telegram 的机器人,见 Python 套利机器人一文。
DEX – Spot 与 DEX – Futures
DEX 数据集把代币在 DEX(去中心化交易所)上的价格与在 CEX 上的价格比较:DEX – Spot 对照现货,DEX – Futures 对照合约。两个接口都在 Pro 和 Max 套餐中。
| 参数 | 类型 | 作用 | 示例 |
|---|---|---|---|
coin | string | 按币种代码筛选 | coin=SCR |
exchange | string | CEX 交易所;多个用逗号分隔 | exchange=MEXC |
min_spread | number | 最小价差,% | min_spread=2 |
min_liquidity | number | 最小流动性,USD | min_liquidity=50000 |
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/dex-spot" \
-d min_spread=2 -d min_liquidity=50000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/dex-futures" \
-d min_spread=1 -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
来自文档的 DEX – Spot 行(节选):
{
"coin": "SCR",
"exchange": "MEXC",
"cex_price": 0.02691,
"dex_price": 0.02679,
"spread_pct": 0.45,
"network": "SCROLL",
"liquidity_usd": 10544.15,
"market_cap": 5091835.0,
"deposit_enabled": true,
"withdraw_enabled": true,
"dexscreener_url": "https://dexscreener.com/scroll/0xd296…",
"dextools_url": null,
"gmgn_url": null,
…
}
MEXC 的价格高于池子价格,所以价差为正。spread_pct 的正负决定方向:正数表示代币在 DEX 上更便宜,在那里买入、在 CEX 卖出;负数则相反。
| 字段 | 类型 | 内容 |
|---|---|---|
exchange | string | CEX 交易所 |
cex_price, dex_price | number | CEX 和 DEX 上的价格 |
liquidity_usd | number | 池子流动性,USD |
market_cap, dex_volume_24h | number 或 null | 市值和 24 小时 DEX 成交量(DEX – Spot) |
ticker, max_position_usd | string;number 或 null | 交易所交易对和最大持仓,USD(DEX – Futures) |
deposit_enabled, withdraw_enabled | boolean | CEX 是否开放充值和提现 |
dexscreener_url, dextools_url, gmgn_url | string 或 null | DexScreener、DEXTools 和 GMGN 链接 |
示例中的池子只有 $10,544 的流动性,大额买入会推动其价格。规模从 $100 到 $100,000 的滑点、代币税,以及每个合约的貔貅盘标记,可在 Pro 和 Max 套餐中通过 GET /orderbooks/dex-slippage 获取。
Cross-chain:同一代币跨网络
GET /arbitrage/crosschain 比较同一代币在不同区块链上的 DEX 价格,适用于 Pro 和 Max 套餐。一行包含 coin、spread_pct 和两个字段相同的对象:buy 是代币更便宜的一侧,sell 是更贵的一侧。代币通过跨链桥在网络之间转移。
| 参数 | 类型 | 作用 | 示例 |
|---|---|---|---|
coin | string | 按代币代码筛选 | coin=WLD |
chain | string | 按网络筛选 | chain=ethereum |
min_spread | number | 最小价差,% | min_spread=1 |
min_liquidity | number | 最小流动性,USD | min_liquidity=20000 |
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/crosschain" \
-d coin=WLD -d min_liquidity=20000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
来自 Cross-chain 文档的一行(节选):
{
"coin": "WLD",
"spread_pct": 0.59,
"buy": {
"chain": "optimism",
"pair": "WLD/USDC",
"price_usd": 0.4048,
"liquidity_usd": 48747,
"volume_24h_usd": 2484,
"pool_created_at": "2023-07-24 08:44:19 UTC",
…
},
"sell": {
"chain": "ethereum",
"pair": "WLD/WETH",
"price_usd": 0.4072,
"liquidity_usd": 421426,
…
}
}
| 字段 | 类型 | 内容 |
|---|---|---|
buy.chain | string | 该侧的网络 |
buy.pair | string | DEX 交易对,如 WLD/USDC |
buy.contract | string | 该网络上的合约地址 |
buy.price_usd, buy.liquidity_usd, buy.volume_24h_usd | number | 价格、池子流动性和 24 小时成交量,USD |
buy.pool_created_at | string 或 null | 池子创建日期 |
buy.dexscreener_url, dextools_url, gmgn_url | string 或 null | DexScreener、DEXTools 和 GMGN 链接 |
sell 的字段相同。pool_created_at 是 UTC 日期字符串,不像 API 中大多数时间戳那样是 Unix 秒,并且可能为 null。几天前才创建的池子,是核对两侧合约的理由:在新网络上,同一个代码背后可能是另一个代币。
股票套利:股票、金属、指数、大宗商品
GET /arbitrage/stocks 返回 CEX 交易所之间代币化股票、金属、指数和大宗商品的价差,从 Start 套餐起可用。
| 参数 | 类型 | 作用 | 示例 |
|---|---|---|---|
symbol | string | 按标的代码筛选 | symbol=BRENT |
category | string | 类别:Stock、Metal、Index 或 Commodity | category=Commodity |
exchange | string | 按交易所筛选;多个用逗号分隔 | exchange=MEXC |
min_spread | number | 最小价差,% | min_spread=0.3 |
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/stocks" \
-d category=Commodity -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
来自股票套利文档的一行(节选):
{
"symbol": "BRENT",
"category": "Commodity",
"exchange_buy": "MEXC",
"exchange_sell": "Ourbit",
"symbol_on_buy": "UKOIL",
"symbol_on_sell": "BRENTOIL",
"price_buy": 76.68,
"price_sell": 76.82,
"spread_pct": 0.18,
…
}
symbol 是标的的通用代码,而 symbol_on_buy 和 symbol_on_sell 是它在各交易所的名称:示例中,布伦特原油在 MEXC 上是 UKOIL,在 Ourbit 上是 BRENTOIL。请按 symbol_on_* 在交易所查找该标的。这一行没有网络、合约或充值字段:在 CEX 上,这些标的以永续合约形式交易,交易对通过 Long 和 Short 持仓开立(表格指南)。
API 响应与网站表格
网站表格的各列在指南中有说明:
| 接口 | 网站表格及其指南 |
|---|---|
/arbitrage/spot-spot | Spot – Spot |
/arbitrage/spot-futures | Spot – Futures |
/arbitrage/futures-futures | Futures Arbitrage |
/arbitrage/dex-spot | DEX – Spot |
/arbitrage/dex-futures | DEX – Futures |
/arbitrage/crosschain | Crosschain |
/arbitrage/stocks | Stock Arbitrage |
如何搭建交易对监控
按套餐选择接口
对照上面的套餐表:DEX 数据集和 Cross-chain 仅限 Pro 和 Max。
在服务端缩小范围
将
min_spread设为高于你的各项手续费之和,并用min_volume或min_liquidity剔除流动性差的币。在代码中保留可执行的行
Spot – Spot 看
withdraw_enabled_buy和deposit_enabled_sell。价差为正的 DEX – Spot 看deposit_enabled,价差为负的看withdraw_enabled。股票按symbol_on_buy和symbol_on_sell查找。核对代币和订单簿
比对
contract和network,并用订单簿接口计算你的下单规模下的实际成交。按套餐的节奏轮询
频率不要高于
meta.freshness_sec。机器人发送提醒,交易由你自己在交易所下单。
常见问题
这些接口能下单吗?
不能。Genesis API 只提供数据,不下任何订单。基于 Genesis API 的机器人会找出交易对并向你发送提醒,交易由你自己在交易所开立。
为什么行里没有 Book 或 Ord. 列?
两者都由订单簿计算,需要单独获取:Order-book Δ 来自 GET /orderbooks/spreads/{dataset},某个市场的订单簿来自 GET /orderbooks/book,均在 Pro 和 Max 套餐中。
DEX 和 Cross-chain 需要哪个套餐?
Pro 或 Max。Trial 涵盖三个 CEX 数据集,Start 增加股票套利。