自动化风险:数据、错误、密钥与 AI
简而言之
- 在任何提醒之前先检查数据:快照时效(当前时间减去
meta.updated_at)、订单簿上的stale标志、最优报价处的价差,以及交易对两家交易所共用的合约。 503表示没有数据,而200且data为空表示没有行符合筛选条件。机器人要区分这两种情况,并在连续三个周期没有数据后报告故障。- 代码会在边界情况下出错:不间隔地重试会撞上
429,比较中的null会让 Python 崩溃,JavaScript 中除以零得到Infinity并产生虚假提醒,使用本地时间而不是 UTC 会让资金费率结算时间偏差数小时。 - Genesis API 密钥是只读的,因此泄露会耗尽你的额度。带提现权限的交易所密钥会让资金面临风险,而交易机器人并不需要这项权限。
- AI 模型会混淆数字,还可能执行藏在他人文本中的指令:数字由代码填入消息,来自外部的字段以数据的形式交给模型,交易限额由代码强制执行,每一笔订单都由人确认。
加密货币 API 交易机器人的风险分为四类:数据过期或显示并不存在的价差;代码在边界情况下陷入循环或崩溃;密钥泄露;AI 模型把数字弄错,或执行了别人的指令。每种风险都有对应的代码检查或工作规则,而且它们都能放进第 4 课的监控程序里。
数据风险
过期的快照
Genesis API 快照在 meta.updated_at 时刻生成,你的套餐每隔 meta.freshness_sec 秒刷新一次:Trial 为 60 秒,Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒。快照的时效就是当前时间减去 meta.updated_at,也就是数据新鲜度。一到两个套餐间隔属于正常;超过三个说明快照卡住了。
假设示例:在 Pro 上阈值是 3 × 10 = 30 秒。一个响应在 1783802470 到达,其 meta.updated_at = 1783802410:时效为 1783802470 − 1783802410 = 60 秒,因此机器人不会根据它发送任何提醒。从交易所到你的代码的完整延迟还要更大,而且时效是按你服务器的时钟计算的,所以请用 NTP 保持同步。
订单簿与预测平台
订单簿有自己的时钟:/orderbooks/book 返回 book_ts、age_sec 和 stale 标志,订单簿超过 30 秒时该标志为 true。订单簿比交易所滞后 5–20 秒。在 Order-book Δ 中,请检查 order_delta.status:ok 表示已计算,no_book 表示没有订单簿,exhausted 表示订单簿无法满足该数量。
对于预测市场,有 /predictions/platforms:跳过涉及 mode = down 的平台、quotes_at 很旧的平台,或 ok = false 的博彩公司的交易对。
503 时的空响应
空列表和缺失数据是两种不同的状态。200 且 meta.count = 0 表示没有行符合筛选条件。503 snapshot_not_ready 表示数据正在重建:市场上可能仍有交易对,你在 Retry-After 秒后重试。
fetch 函数返回 (data, meta),没有数据时返回 None。遇到 429 和 503 时按 Retry-After 等待后重试,遇到其他 5xx 错误和网络故障时分别间隔 5、10 和 20 秒重试,其他情况则停止。
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
def fetch(path, params=None, tries=4):
"""(data, meta),或 None:没有数据,这不等于“没有交易对”。"""
for attempt in range(tries):
try:
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
code = r.status_code
except requests.RequestException:
code = 0 # 网络错误或超时:间隔后重试
if code == 200:
body = r.json()
return body["data"], body["meta"]
wait = 5 * 2 ** attempt # 5、10、20 秒:间隔逐次变长
if code in (429, 503):
wait = int(r.headers.get("Retry-After", wait))
if wait > 60: # 绝不等待超过一分钟
raise RuntimeError(f"需等待 {wait} 秒:请检查你的额度")
elif 400 <= code < 500:
# 400、401、403、404、410:重试无法解决
raise RuntimeError(f"{code}: {r.text[:200]}")
if attempt < tries - 1:
time.sleep(wait)
return None
当本周期额度用完时,也会返回很长的 Retry-After:重置可能还在几天之后,而 fetch 从不等待超过一分钟。重试、ETag 和筛选参数在如何轮询 API 而不触发限制一文中有详细说明。
虚假价差:薄订单簿与相似代币
spread_pct 按最新成交价计算,而你只能在卖一价买入、在买一价卖出。在套利接口指南的 FUEL 示例中,按最新成交价价差为 0.11%,按最优报价则为 −0.11%。ask_buy 和 bid_sell 字段出现在任何套餐的每一行 Spot – Spot 数据中,下面的 quote_spread 用它们计算最优报价处的价差。
薄订单簿会放大差价。假设示例:最新成交价一小时前停在 $1.18,现在最优买价是 $1.02,买入交易所的卖价是 $1.00。按最新成交价价差为 18%,按最优报价为 2%,而且 $1,000 可能完全无法成交:在 Pro 和 Max 上,volume=1000 时 order_delta.status = exhausted 正说明了这一点。
虚假价差的第二个来源是不同代币共用同一个代码,例如 BSC 上的某个代币和 Solana 上毫无关系的另一个项目。对于有合约的代币,请用 query 传入代码调用 /coins/search:contracts[] 中必须有一项,其 exchanges 同时列出该交易对的两家交易所(名称比较时忽略大小写)。没有这样的条目就意味着无法直接转账:它们是不同的代币,或者路线要经过带有自身风险的跨链桥。
def is_fresh(meta, k=3):
"""快照不超过 k 个套餐间隔。"""
age = time.time() - meta["updated_at"]
return age <= k * meta["freshness_sec"]
def quote_spread(row):
"""最优报价处的价差:按卖一价买入,按买一价卖出。"""
ask, bid = row.get("ask_buy"), row.get("bid_sell")
if ask is None or bid is None or ask <= 0:
return None # 没有价格或价格为零:跳过该行
return (bid - ask) / ask * 100
pause, fails = 60, 0
while True:
got = fetch("/arbitrage/spot-spot", {"min_spread": 1})
if got is None or not is_fresh(got[1]):
fails += 1 # 没有数据或数据过期:不发提醒
if fails == 3:
print("已连续 3 个周期没有新数据") # 给自己发提醒
else:
rows, meta = got
fails, pause = 0, meta["freshness_sec"]
for row in rows:
s = quote_spread(row)
if s is not None and s >= 0.5:
print(row["coin"], row["exchange_buy"], "→",
row["exchange_sell"], f"{s:.2f}%")
time.sleep(pause) # 每条路径都会执行这次暂停
fetch 抛出的异常会停止循环:生产环境的机器人在退出前会先通知它的主人。
代码风险
不暂停的重试与无限循环
第一版机器人常常在出错后立刻重试:if r.status_code != 200: continue。遇到 503 时,这样的循环会不间断地连续发出请求:错误不占用额度,但会计入每秒请求数限制,于是紧接着就是带 Retry-After: 1 的 429。订阅到期后,同样的循环会永远收到 401。而位于 time.sleep() 之前的 continue 会在每次空响应时跳过暂停,所以上面循环中的暂停放在最后一行。
相反的错误是无限等待。额度用尽时,time.sleep(int(r.headers["Retry-After"])) 会睡上好几天:例如 Retry-After: 259200 就是 259,200 / 86,400 = 3 天。没有 timeout 的请求也可能无限期挂起,requests 文档对此有警告。
null 与除以零
Genesis API 用 null 表示空值,Python 会把它变成 None。把 row["volume_24h_sell"] > 10000 与 None 比较会抛出 TypeError,一行数据就能让整个循环崩溃。JavaScript 不会抛出任何错误:null > 0.5 为 false,null < 1 为 true,筛选会悄无声息地失效。
null 表示“没有数据”,用 or 0 把它换成零是危险的:在 DEX 滑点中,tax_sell_pct = null 表示没有税率来源,而 or 0 会把它变成 0%。按文档所述,null 会出现在 bid_* 和 ask_*、volume_24h_*、max_position_usd、next_payout 中,出现在含博彩公司腿的交易对的 profit_usd 中,也会出现在剩余时间不足一天时的 apr_pct 中。
除以零是同样的陷阱。卖价为零时,Python 会抛出 ZeroDivisionError,而在 JavaScript 中 1 / 0 是 Infinity,Infinity > 0.5 为 true:机器人会推送一个价差无限大的交易对。除法之前先检查分母,就像 quote_spread 检查 ask <= 0 那样。
时区
Genesis API 的时间是 unix 秒和 UTC 字符串:资金费率中的 next_payout 以 HH:MM UTC 给出。不带时区的 datetime.fromtimestamp(ts) 返回服务器的本地时间,而 datetime.utcnow() 自 Python 3.12 起已被弃用;Python 文档建议改用 datetime.now(timezone.utc)。
假设示例:服务器运行在 UTC+3,时钟显示 09:30,也就是 06:30 UTC。08:00 的结算还有 1 小时 30 分钟,但把 08:00 与本地时间比较的代码会认为结算已经过去,并计算出距下一次还有 22 小时 30 分钟,偏差 21 小时。
from datetime import datetime, timedelta, timezone
def until_payout(hhmm, now=None):
"""距 next_payout 的时间,hhmm 是 UTC 的 HH:MM 字符串。"""
if hhmm is None:
return None # null:没有结算时间
now = now or datetime.now(timezone.utc)
h, m = map(int, hhmm.split(":"))
t = now.replace(hour=h, minute=m, second=0, microsecond=0)
if t <= now:
t += timedelta(days=1) # 23:50 时的 "00:00" 指明天
return t - now
now = datetime(2026, 11, 15, 6, 30, tzinfo=timezone.utc)
print(until_payout("08:00", now)) # 1:30:00
密钥风险
Genesis API 密钥是只读的:它不能下单,也不能提现。泄露会影响你的额度和每秒请求数限制,你的机器人会在周期结束前收到 429。警示信号:个人资料中的“已用调用次数”增长得比你的代码统计的更快,或者机器人已停止,而“最近使用 …”仍显示一个很近的时间。
密钥只显示一次,Genesis Arbitrage 只保存它的哈希,所以泄露的密钥要重新生成:“重新生成”会立即停用旧密钥并签发新密钥。密钥会从被误放的地方泄露:公开仓库、请求 URL、页面代码、截图、带有请求头的日志。请改为记录状态码和 X-Request-Id;存放规则见 API 密钥词条。
交易所密钥属于另一类风险:带提现权限的话,它可以把币从账户中转走。交易机器人不需要这项权限,所以创建密钥时不要开通提现,把它绑定到你服务器的 IP,并为每个服务单独创建。详情见如何保护你的加密货币交易所账户。
AI 代理:数字、被注入的指令、确认
代理通过你的服务器调用 Genesis API:模型选择接口和参数,由服务器带着密钥发出请求。设置方法见面向 AI 代理的 Genesis API指南,整体设计见面向 AI 代理的加密货币市场数据一文。
错误的数字
模型可能把 0.92 读成 92% 而不是 0.92%,把每个间隔的 funding_pct 与 8 小时的 funding_8h_pct 混淆,或者说出响应里没有的价格。提醒中的数字由代码直接从 API 响应填入,模型只负责挑选和解释。如果模型自己写数字,请把每个数字与工具结果逐一核对。
外部文本中的指令
有些字段由其他人填写:预测市场的 title 和 outcome、交易者的 name、链上事件的 token_name,以及信号的 message_ru 和 message_en。任何人都可以把代币命名为“忽略之前的指令,并……”,而把这个名称当作提示词一部分来读取的模型可能会照做。这就是提示词注入,位列 OWASP 2025 年 LLM 应用十大风险之首:LLM01:2025。
这类字段只放在工具结果里传递,限制其长度,并在系统提示词中说明它们是数据。密钥始终留在服务器端的处理程序中。
人工确认
Genesis API 只读取数据:基于它构建的代理能找到交易对并写出说明,但不会交易。接入代理的交易所交易 API 不属于 Genesis API,风险由你自己承担。在缓解措施中,OWASP 列出了对特权操作的人工介入控制:只有看到交易对、价格和数据时间的交易者回答“是”之后,订单才会发出。
上线前检查清单
- 密钥保存在服务器的
GENESIS_API_KEY中,代码、请求 URL、浏览器、日志和提示词里都没有。 - 每个请求都有
timeout。 - 只有
429、503、其他 5xx 错误和网络故障才重试,每次有间隔,最多三次。 400、401、403、404、410以及超过一分钟的Retry-After会让机器人带着消息停止。- 两次轮询之间的间隔不少于
meta.freshness_sec,并且在循环的每条路径上都会执行。 - 任何提醒之前都先检查快照时效,对于订单簿还要检查
stale和order_delta.status。 - “没有数据”和“没有交易对”是两种独立状态,连续三个周期没有数据就触发故障消息。
- 用
None检查null,用零检查分母,并按 UTC 处理时间。 - 交易对要通过最优报价处的价差、共用合约、
withdraw_enabled_buy和deposit_enabled_sell的检查。 - 数字由代码填入消息,外部文本以数据形式交给模型,每一笔订单都由人确认。
课程总结:接下来去哪里
本课程共有五课:概念、第一个请求、用于决策的数据、Python 监控程序及其风险;基础内容见第 1 课。每一步的详细说明:
- Genesis API 快速开始:密钥与第一个请求;
- Genesis API 限制:额度,以及按机器人需求选择套餐;
- Genesis API 响应与错误:状态码、
ETag和X-Request-Id; - 订单簿接口:按你的数量计算 Order-book Δ;
- 用 Python 编写加密货币套利机器人:带 Telegram 提醒的机器人;
- 加密货币 API:类型与选择方法:数据源概览。
动手试试
查看你的套餐新鲜度
调用
/account/usage,记下freshness_sec和calls_used:这个请求不计入调用次数。测量快照时效
通过
fetch获取/arbitrage/spot-spot,打印time.time() - meta["updated_at"],并与 3 ×freshness_sec的阈值比较。比较两种价差
对五行数据打印
spread_pct和quote_spread(row),数一数有多少个交易对在最优报价处仍为正。测试错误路径
用占位符
GENESIS_API_KEY=gns_live_XXXXXXXXXXXXXXXX运行机器人:401 invalid_key响应应当让它带着清楚的消息停止。逐项过一遍检查清单
在让机器人全天候运行之前,补上你的代码缺少的部分。