用 Python 搭建加密货币套利机器人:从价差 API 到 Telegram 提醒
简而言之
- 套利机器人由四个环节组成:价差数据、可执行交易对的筛选、提醒和人工决策。代码负责前三个环节,交易由你自己在交易所完成。
- 套利最难的是执行:转移币、手续费、滑点和时间。因此机器人只保留充值和提币都开放的交易对,在 Pro 和 Max 套餐上还会按 $1,000 的订单簿重新计算价差。
- 机器人调用 Genesis API 的频率不高于
meta.freshness_sec,遇到429和503会等待Retry-After,同一个交易对每 15 分钟最多提醒一次。基础版可以在每月 $20 的 Trial 套餐上运行。
加密货币套利机器人是一个按固定间隔拉取交易所之间 价差(同一种币的价格差,以百分比表示)的程序:它保留你真正能执行的交易对,并向你发出提醒。决策和下单由人来完成。用于现货跨交易所套利的这类机器人大约需要 140 行 Python:价差来自 Genesis API,消息通过 Telegram Bot API 发送。
套利机器人由什么组成
每个套利机器人都由四个环节构成:
| 环节 | 作用 | 在这个机器人中 |
|---|---|---|
| 数据 | 拉取各交易所的价格和价差 | Genesis API GET /arbitrage/spot-spot |
| 筛选 | 保留可以执行的交易对 | 充值和提币状态、$1,000 的订单簿 Δ |
| 提醒 | 通知交易对 | Telegram Bot API 的 sendMessage 方法 |
| 决策和交易 | 核对交易对并下单 | 交易所上的人 |
自己写数据采集器是最慢的一环:每个交易所都有自己的 API、自己的交易对和网络名称、自己的充值和提币状态,还要全部合并成统一格式。Genesis API 返回 20 多家 CEX 交易所的现成交易对,包括 Binance、OKX、Bybit、Bitget、MEXC 和 Gate,带有价格、价差、网络、合约、充值和提币状态以及成交量。每个套利端点的字段见 Genesis API 套利端点 指南,数据源的选择见 加密货币 API:类型与选择方法。
为什么交易仍由人来做
找到价差是套利中容易的部分,难的是执行:从 API 响应里的一行数据到你账户里的钱,中间隔着四道障碍。
- 转移币:提币和充值需要几分钟到几小时,交易所也可能随时暂停充值或提币。
- 手续费:两个交易所都收交易手续费,而提币手续费通常是固定数量的币,在小额交易中会吃掉价差。
- 滑点:价差按最新成交价计算,而市价单会吃掉 订单簿 的多个档位,所以买入成交在最优卖价之上,卖出成交在最优买价之下。
- 时间:数据按你的套餐延迟到达,Trial 最长 60 秒,其他交易者看到同样的价差并把它抹平。
假设示例:机器人发来一个价差 1.2% 的交易对,即 $1,000 对应 $12。按 $1,000 吃穿订单簿后剩下 0.8%,即 $8。买入和卖出各 0.1% 的 taker 手续费约 $2,提币要 $3。
自动买入并提币的代码会把这些失误中的每一个变成无人核对的交易。所以这个机器人只发信号:提币、充值和订单簿之后的价差由它自己检查,合约、手续费和划转路径则由人在交易前核实。Genesis API 本来也不能交易:它只读取数据,不下单。逐步手动核对交易对的方法见 跨交易所加密货币套利。
你需要准备什么
- Python 3.10 或更高版本,以及
requests库。 - 任意套餐的 Genesis API 密钥:在个人资料中点击“获取密钥”,保存
gns_live_…密钥,它只显示一次。保存和重新生成见 Genesis API 密钥 指南。 - Telegram 机器人令牌:向 @BotFather 发送
/newbot,选择名称和用户名,BotFather 会回复类似123456:ABC-DEF…的令牌。 chat_id,即你与机器人聊天的 ID。机器人不能先给你发消息(Telegram 文档):先向它发送/start,再调用getUpdates;"chat":{"id":…}中的数字就是你的chat_id。更新最多保存 24 小时。
python3 --version # 需要 Python 3.10 或更高版本
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
export TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
# 在机器人聊天中发送 /start 后,在返回结果里找到 "chat":{"id":...}
curl "https://api.telegram.org/bot$TG_BOT_TOKEN/getUpdates"
export TG_CHAT_ID="123456789"
用 export 设置的变量在关闭终端前一直有效。按 Telegram 文档,令牌可以完全控制机器人,密钥则能访问你的套餐,所以两者只放在环境变量里:不要写进代码,也不要提交到仓库。
机器人代码分步讲解
下面的七个代码块就是完整的 bot.py:按顺序保存到同一个文件。设置里的阈值只是占位值,请按你的手续费和交易规模调整。
1. 设置
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
TG = "https://api.telegram.org/bot" + os.environ["TG_BOT_TOKEN"]
CHAT_ID = os.environ["TG_CHAT_ID"]
MIN_SPREAD = 1.0 # 行价差不低于 1%
MIN_VOLUME = 50_000 # 两个交易所的 24 小时成交量均不低于 $50,000
MIN_EXEC = 0.5 # $1,000 订单簿之后的价差不低于 0.5%
TOP = 5 # 每轮最多处理的交易对数
REPEAT_SEC = 15 * 60 # 同一个交易对每 15 分钟最多提醒一次
RECHECK_SEC = 5 * 60 # 被订单簿吃掉价差的交易对等待 5 分钟
api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # 请求 -> (ETag, 响应)
wait_until = {} # 交易对 -> 保持静默直到的时间
密钥通过 api 会话放在每个请求的 X-API-Key 请求头里,从不进入 URL。MIN_VOLUME 会剔除任一交易所 24 小时成交量低于 $50,000 的交易对。cache 保存响应的 ETag,wait_until 保存机器人对某个交易对保持静默的截止时间。
2. 调用 Genesis API:Retry-After 和 ETag
def get(path, params=None):
"""带 Retry-After 重试和 ETag 的 Genesis API GET 请求。"""
key = (path, tuple(sorted((params or {}).items())))
for _ in range(4): # 一次请求加最多三次重试
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = api.get(API + path, params=params, headers=hdr,
timeout=15)
if r.status_code == 304: # 快照未变化
return cache[key][1]
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # 额度用尽时就是这个样子
raise SystemExit(f"额度已用尽:请等待 {wait} 秒")
time.sleep(wait)
continue
r.raise_for_status() # 400、401、403:重试没有用
body = r.json()
if "ETag" in r.headers: # 只有完整数据集才带 ETag
cache[key] = (r.headers["ETag"], body)
return body
raise RuntimeError("Genesis API 繁忙,下一轮再试")
超出每秒 速率限制 或下载量时返回 429,数据重建期间返回 503。两者都带有 Retry-After,get 会按服务器要求等待相应秒数。额度用尽时同样返回 429,但 Retry-After 是重置时间,有时要几天,所以机器人会停止。400、401 和 403 重试也不会消失,因此由 raise_for_status 抛出。全部限额见 Genesis API 限额 指南。
3. 价差和交易对筛选
def candidates():
"""币确实可以转移的 Spot – Spot 交易对。"""
body = get("/arbitrage/spot-spot",
{"min_spread": MIN_SPREAD, "min_volume": MIN_VOLUME})
# 买入一侧开放提币,卖出一侧开放充值
rows = [x for x in body["data"]
if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows, body["meta"]["freshness_sec"]
min_spread 和 min_volume 在服务器上筛选行。充值和提币标记没有对应参数,所以由代码检查:买入交易所开放提币(withdraw_enabled_buy)并且卖出交易所开放充值(deposit_enabled_sell),币才能转移。来自 Spot — Spot 文档的一行中,机器人用到的字段如下:
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"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",
"trade_url_sell": "https://www.gate.io/trade/FUEL_USDT",
…
}
这一行过不了机器人的筛选:价差只有 0.11%,成交量也低于 $50,000。机器人会把网络和合约写进消息,方便你与两个交易所的提币和充值页面核对。
4. $1,000 订单簿检查
def exec_spread(row):
"""按 $1,000 订单簿计算的价差。仅限 Pro 和 Max。"""
body = get("/orderbooks/spreads/spot-spot",
{"coin": row["coin"], "volume": 1000})
for x in body["data"]:
od = x["order_delta"]
if (x["exchange_buy"] == row["exchange_buy"]
and x["exchange_sell"] == row["exchange_sell"]
and od["status"] == "ok"):
return od["spread_pct"]
return None # no_book、exhausted,或者该交易对已经消失
这个端点返回该币在 Spot – Spot 数据集中的行,并附带 order_delta 对象,即订单簿 Δ:吃穿订单簿之后的价差,也就是按买入交易所的卖单(ask)买入、再向卖出交易所的买单(bid)卖出。函数会取交易所相同的那一行,在 status 为 ok 时返回其 order_delta.spread_pct;no_book 表示没有订单簿,exhausted 表示订单簿在 $1,000 之前就已吃完。订单簿比交易所滞后 5–20 秒;字段见 订单簿 Δ 文档和 订单簿端点 指南。
这一步只有 Pro 和 Max 才有;在 Trial 和 Start 上,端点返回 403 plan_restricted。机器人启动时会读取你的套餐,并在这些套餐上跳过检查:消息里会注明订单簿未检查,深度请你自己在交易所终端查看。
5. Telegram 消息
def message(row, ex):
buy, sell = row["exchange_buy"], row["exchange_sell"]
if ex is None:
book = "订单簿未检查(Trial 或 Start)"
else:
book = f"按 $1,000 订单簿计算:{ex:.2f}%"
return "\n".join([
f'{row["coin"]}: {buy} → {sell}',
f'价差 {row["spread_pct"]}%,{book}',
f'网络 {row["network"]},合约 {row["contract"] or "—"}',
f'买入:{row["trade_url_buy"]}',
f'卖出:{row["trade_url_sell"]}',
])
def send(text):
"""Telegram Bot API sendMessage;遇到 429 就等待 retry_after。"""
for _ in range(3):
r = requests.post(TG + "/sendMessage", timeout=15, json={
"chat_id": CHAT_ID, "text": text,
"link_preview_options": {"is_disabled": True}})
if r.status_code != 429:
r.raise_for_status() # 400 或 401:聊天或令牌错误
return
wait = r.json().get("parameters", {}).get("retry_after", 5)
time.sleep(wait) # Telegram 的防刷屏限制
raise RuntimeError("Telegram 未接收消息")
sendMessage 接收 chat_id 和长度为 1 到 4096 个字符的 text,请求发往 https://api.telegram.org/bot<token>/sendMessage(Telegram Bot API 文档)。link_preview_options 中的 is_disabled 会关闭链接预览。触发防刷屏限制时,Telegram 返回 429,并把等待秒数放在 parameters.retry_after 中。在单个聊天里,Telegram 建议机器人每秒发送的消息不超过一条(机器人开发者常见问题)。
消息大致如下,这是一个假设示例:
XYZ: MEXC → Gate
价差 1.4%,按 $1,000 订单簿计算:0.62%
网络 ETH,合约 0x…
买入:https://…
卖出:https://…
6. 去重:同一交易对每 15 分钟一次
def scan(books):
"""一轮:价差、订单簿、消息。"""
rows, pause = candidates()
done = 0
for row in rows:
key = (row["coin"], row["exchange_buy"], row["exchange_sell"])
if time.time() < wait_until.get(key, 0):
continue # 已提醒过,或者订单簿吃掉了价差
if done == TOP:
break
done += 1
ex = exec_spread(row) if books else None
ok = not books or (ex is not None and ex >= MIN_EXEC)
if ok:
send(message(row, ex))
# 提醒后静默 15 分钟;订单簿太薄则静默 5 分钟
hold = REPEAT_SEC if ok else RECHECK_SEC
wait_until[key] = time.time() + hold
time.sleep(1) # 每秒最多一次请求和一条消息
return pause
一个交易对由币、买入交易所和卖出交易所三项组成。提醒之后,即使价差仍然存在,机器人也会对它静默 15 分钟。如果订单簿吃掉了价差,机器人 5 分钟后再回来看这个交易对,这样订单簿检查不会每轮都消耗一次调用。每一轮最多取价差最大的五个交易对,每处理完一个就停一秒:这既符合 Telegram 的建议,也低于任何套餐的每秒限制。字典存在内存里,所以重启后新的交易对可能重复出现。
7. 循环:间隔不少于 freshness_sec
def main():
usage = get("/account/usage")["data"] # 不消耗额度
books = usage["plan"] in ("pro", "max")
pause = usage["freshness_sec"]
print("套餐", usage["plan"], "| 轮询间隔", pause, "秒",
"| 订单簿:", "是" if books else "否")
while True:
try:
pause = scan(books)
except requests.HTTPError as e:
if e.response.status_code < 500:
raise # 密钥、套餐或令牌问题:重试没有用
print("服务器错误,重试:", e)
except (requests.RequestException, RuntimeError) as e:
print("无响应,重试:", e)
time.sleep(pause) # 不比 meta.freshness_sec 更频繁
if __name__ == "__main__":
main()
启动时,机器人调用 /account/usage:这个请求不消耗额度,返回你的套餐和 freshness_sec。这就是 数据新鲜度,即你的套餐获得新快照的间隔:Trial 为 60 秒,Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒。此后的间隔取自 meta.freshness_sec,因为轮询更快只会拿到同一个快照。网络故障和 5xx 错误会等到下一轮,其余 4xx 错误(密钥错误、订阅过期、套餐不含该端点、令牌或 chat_id 错误)会让机器人停止。错误码列表见 Genesis API 响应与错误;不带 Telegram 的价差监控在课程 用 Python 监控价差和资金费率 中构建。
如何运行和检查
python3 bot.py
# 套餐 trial | 轮询间隔 60 秒 | 订单簿:否
等待第一轮
当市场上出现高于你阈值的交易对时,消息就会到来。如果几分钟内一条都没有,可以暂时调低
MIN_SPREAD和MIN_VOLUME:这样能确认从 API 到 Telegram 的链路是通的。把一个交易对与表格对照
在网站上打开 Spot – Spot:同一个币和同一对交易所就在表格里。数字可能略有出入,因为 API 按你的套餐延迟提供快照。
检查去重
同一个交易对在 15 分钟内不应再次到来。
查看调用用量
查看
/account/usage中的calls_used字段,或个人资料里的“已用调用”一行:在不检查订单簿的 Trial 上,机器人每天大约用 1,440 次调用。让机器人持续运行
nohup python3 bot.py >> bot.log 2>&1 &会让机器人在后台运行;环境变量要在同一个终端会话里设置。
机器人需要哪个 Genesis API 套餐
一轮是一次 /arbitrage/spot-spot 调用,在 Pro 和 Max 上再加最多五次 /orderbooks/spreads/spot-spot 调用;只有 200 响应才消耗额度。30 天的上限:(1 + 每轮检查次数) × 86,400 / 间隔 × 30。
| 套餐 | 轮询 | $1,000 订单簿检查 | 30 天调用次数 |
|---|---|---|---|
| Trial,$20/月 | 每 60 秒 | 否 | 500,000 中的 43,200 |
| Start,$50/月 | 每 30 秒 | 否 | 200 万中的 86,400 |
| Pro,$100/月 | 每 10 秒 | 是 | 500 万中最多 1,555,200 |
| Max,$200/月 | 每 5 秒 | 是 | 1,000 万中最多 3,110,400 |
在 Trial 上是 86,400 / 60 × 30 = 43,200 次调用,占额度的 8.64%。在 Pro 上,最坏的情况是每一轮都检查五个订单簿,结果是 6 × 86,400 / 10 × 30 = 1,555,200 次调用,占额度的 31.1%。额度规则见文档中的 套餐与限额 一节。
套利机器人的风险
- 过期价格:快照每
freshness_sec刷新一次,订单簿比交易所滞后 5–20 秒,所以交易前请在交易所终端核对价格。 - 网络关闭:充值和提币标记只在快照时刻有效,你买入的同时交易所可能关闭提币。同一个代码在不同交易所可能是不同的代币,所以要核对
contract和network。 - 手续费和提币:
spread_pct不包含这些,固定的提币手续费会吃掉小额交易的全部价差。 - 薄订单簿上的虚假价差:交易稀少的币上较宽的最新成交价差会随第一笔订单消失。
min_volume和 $1,000 检查能过滤掉一部分这类交易对,但不是全部。 - 触及限额:一秒内多余的请求会得到带
Retry-After: 1的429,额度用尽则会让机器人停止到重置为止。用多个密钥或账户绕开限额违反规则;负载更大时有更高的套餐。Telegram 在防刷屏限制下同样返回429。
无需代码:Genesis Arbitrage 的 Telegram 提醒
如果你不想自己编写和运行机器人,Genesis Arbitrage 的 Telegram 提醒 会替你发送交易对。你在 @BotFather 创建机器人,把令牌粘贴到网站上,并选择 Spot - Spot、DEX - Futures、Crosschain 和资金费率套利等类别。筛选器可设置最小价差、交易所和网络、充值/提币状态和订单价差,“重复间隔(分钟)”则限制同一个交易对再次出现的频率。个人机器人在网站的 Pro 套餐上运行,与 Genesis API 套餐相互独立;设置方法见 Telegram 通知 指南。
常见问题
机器人能自己交易吗?
通过 Genesis API 不行:API 只提供数据,不下单。交易需要借助交易所自己的 API 和交易密钥来添加,那是另一套代码,风险由你自己承担:过期的价差或已关闭的提币会变成无人核对的交易。
这样的机器人要花多少钱?
代码是免费的,机器人向 Telegram 用户发消息也免费。你为数据付费:Genesis API 从 Trial 的每月 $20 起,订单簿检查从 $100 的 Pro 起。你还需要一台全天候运行的电脑或服务器。
我需要哪个 Genesis API 套餐?
基础机器人用 Trial 就够:/arbitrage/spot-spot 在所有套餐上都有,每 60 秒一个新快照。Start 每 30 秒刷新一次数据。$1,000 的订单簿 Δ 检查只在 Pro 和 Max 上可用。
为什么机器人发来的交易对在交易所里已经没有价差了?
数据按你的套餐延迟到达,其他交易者也会把价差抹平。此外,行价差按最新成交价计算,而你只能按卖价(ask)买入、按买价(bid)卖出。交易前请在交易所终端核对价格和订单簿。
我可以把机器人放到 GitHub 上吗?
可以:条款允许你基于 Genesis API 构建自己的机器人,唯一的限制是不得原样转售原始数据。不要把密钥和令牌放进仓库。如果密钥进入了公开代码,请在个人资料中点击“重新生成”;@BotFather 的 /token 命令则可以更换机器人令牌。