Genesis Arbitrage

Genesis Arbitrage · · 阅读约 19 分钟

自动化风险:数据、错误、密钥与 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 列出了对特权操作的人工介入控制:只有看到交易对、价格和数据时间的交易者回答“是”之后,订单才会发出。

上线前检查清单

  1. 密钥保存在服务器的 GENESIS_API_KEY 中,代码、请求 URL、浏览器、日志和提示词里都没有。
  2. 每个请求都有 timeout。
  3. 只有 429、503、其他 5xx 错误和网络故障才重试,每次有间隔,最多三次。
  4. 400、401、403、404、410 以及超过一分钟的 Retry-After 会让机器人带着消息停止。
  5. 两次轮询之间的间隔不少于 meta.freshness_sec,并且在循环的每条路径上都会执行。
  6. 任何提醒之前都先检查快照时效,对于订单簿还要检查 stale 和 order_delta.status。
  7. “没有数据”和“没有交易对”是两种独立状态,连续三个周期没有数据就触发故障消息。
  8. 用 None 检查 null,用零检查分母,并按 UTC 处理时间。
  9. 交易对要通过最优报价处的价差、共用合约、withdraw_enabled_buy 和 deposit_enabled_sell 的检查。
  10. 数字由代码填入消息,外部文本以数据形式交给模型,每一笔订单都由人确认。

课程总结:接下来去哪里

本课程共有五课:概念、第一个请求、用于决策的数据、Python 监控程序及其风险;基础内容见第 1 课。每一步的详细说明:

动手试试

  1. 查看你的套餐新鲜度

    调用 /account/usage,记下 freshness_sec 和 calls_used:这个请求不计入调用次数。

  2. 测量快照时效

    通过 fetch 获取 /arbitrage/spot-spot,打印 time.time() - meta["updated_at"],并与 3 × freshness_sec 的阈值比较。

  3. 比较两种价差

    对五行数据打印 spread_pct 和 quote_spread(row),数一数有多少个交易对在最优报价处仍为正。

  4. 测试错误路径

    用占位符 GENESIS_API_KEY=gns_live_XXXXXXXXXXXXXXXX 运行机器人:401 invalid_key 响应应当让它带着清楚的消息停止。

  5. 逐项过一遍检查清单

    在让机器人全天候运行之前,补上你的代码缺少的部分。