Genesis Arbitrage

Genesis Arbitrage · · 阅读约 18 分钟

Genesis API 响应与错误:JSON 格式、ETag 与 304、HTTP 状态码

简而言之

  • Genesis API 的成功响应是由 success、data 和 meta 组成的封装;错误响应是 success: false 加一个带错误码和消息的 error 对象。
  • 在 If-None-Match 中带上上一次的 ETag,数据未变化时返回无响应体的 304,且 304 不消耗配额。
  • 429 和 503 在 Retry-After 等待后重试。重试无法解决 400、401、403、404 或 410,需要修改请求、密钥或套餐。

Genesis API 对每个请求都以 JSON 响应,这是一种由键值对象和数组构成的文本数据格式。成功的响应始终使用同一个封装,包含 success、data 和 meta;出错时则返回 HTTP 状态码和 error 对象。状态码会告诉你的程序下一步该做什么:使用数据、等待 Retry-After 秒后重试,或修正请求。

响应封装:success、data 和 meta

文档中 GET /arbitrage/spot-spot 响应的精简版(该端点在所有套餐中可用):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
字段类型内容
successbooleantrue 表示请求成功,false 表示出错
data数组或对象端点的数据
meta.countintdata 中的条目数
meta.updated_atint数据生成时的 Unix 时间
meta.freshness_secint你的套餐的数据延迟,单位为秒
meta.planstring你的套餐,示例中为 pro

例外是资金费率分析:其 meta 包含 count、updated_at 和 schema_version,没有 freshness_sec 和 plan。封装格式见文档的 响应格式 部分,data 的字段见各端点的页面。

以下三条约定适用于所有端点:

data:行数组或对象

data 的形状在各端点的说明中给出。GET /arbitrage/spot-spot 返回数组:每个套利交易对对应一项,相当于网站表格中的一行。GET /account/usage 返回单个对象,内容是你的密钥状态:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage 在所有套餐中可用,显示你的套餐、配额用量和 freshness_sec:比这更频繁地轮询没有收益。字段说明见 用量,首个请求的完整流程见 快速入门。需要处理多个端点的代码应明确检查数据形状:Python 中用 isinstance(data, list)。

过滤参数:可选,不带参数时返回完整数据集

所有过滤参数都是可选的:不带参数的请求会返回该端点的完整数据集。在 exchange 中用逗号分隔多个交易所,在 coin 中用代币代码指定币种:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

-G 参数会把 -d 参数转换为查询字符串:?coin=BTC&exchange=Binance,OKX&min_spread=0.5。交易所名称请按响应字段中返回的写法填写:ByBit、Gate、MEXC。套利端点的参数见 套利端点指南。

配额按响应计数,而不是按行数:带过滤或不带过滤的请求都算一次调用。过滤会缩小响应体,从而减少流量和下载限额的占用。所有限制见 Genesis API 限制指南。

gzip 压缩

当客户端发送 Accept-Encoding: gzip 请求头时,Genesis API 会以 gzip 压缩方式发送完整数据集和较大的响应(RFC 9110,第 12.5.3 节)。较小的响应可能不压缩。

Python 的 requests 会自动发送该请求头并解压响应。curl 在没有 --compressed 参数时不会请求压缩;加上该参数后,它会请求并自动解压。

下载限额按压缩后的数据计算:每个密钥每 10 秒最多 60 MB,小于 64 KB 的响应不计入。超出限额会返回 429 download_limited。

ETag 与 304:跳过未变化的数据

ETag 是一个响应头,包含数据的版本标签。客户端在 If-None-Match 请求头中把该标签发回。数据未变化时,服务器返回无响应体的 304 Not Modified;数据已变化时,返回正常的 200,带新数据和新的 ETag。

# 完整数据集,不带过滤:只打印响应头
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# 带上第一次响应中的 ETag 重复请求(示例值)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

ETag 随不带过滤的请求的响应返回,并随每个新的数据快照而变化。带过滤的请求的响应是为该请求单独生成的,不带 ETag;此时由过滤本身节省流量。ETag 对变化缓慢的数据最有用:资金费率分析 汇总的 ETag 大约每 15 分钟变化一次,304 响应不计入它的完整下载限额。

304 响应不消耗配额,但会计入每秒请求数限制。请原样发回标签:根据 RFC 9110,标签是带引号的字符串,W/ 前缀表示弱标签。

错误码与处理方式

出错时,Genesis API 会返回对应的 HTTP 状态码,以及带 success: false 的响应体:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code 是机器可读的错误码,你的程序可以据此分支处理。error.message 是给人看的说明:400 时给出原因,410 时给出替代地址。

HTTPerror.code含义处理方式
400bad_request请求参数无效,例如 /orderbooks/exec 上的 volume=700按 message 修正参数:同样的请求还会失败
401invalid_key密钥缺失、无效或已吊销,或 API 订阅已过期检查 X-API-Key 请求头和个人资料中的订阅状态
403plan_restricted你的套餐不包含该端点升级到包含它的 套餐,或放弃该请求
404not_found找不到端点或资源:数据集、板块、币种、订单簿对照文档检查路径和参数
410gone该端点已下线改用 message 中给出的地址
429rate_limited超出每秒请求数限制,或周期配额已用完等待 Retry-After 秒并放慢速度;配额用完则等待重置或升级套餐
429download_limited下载量超限:每个密钥每 10 秒 60 MB 压缩数据等待 Retry-After,通过过滤、coin 和 If-None-Match 减少流量
500internal_error内部错误稍后重试;若持续出现,请携带 X-Request-Id 联系支持
503snapshot_not_ready数据正在重建,或其数据源正在重启Retry-After 秒后重试

Retry-After 响应头随 429 和 503 返回,内容是需要等待的秒数:通常是几秒,但周期配额用完时,它是距离配额重置的时间,可能长达数天。4xx 和 5xx 错误不消耗配额,但会计入每秒请求数限制,因此过早重试多半会得到同样的错误。术语表:HTTP 429 和 rate limit。

X-Request-Id:发给支持团队的信息

每个 Genesis API 响应,无论成功与否,都带有包含请求标识符的 X-Request-Id 响应头。如果错误反复出现,或数据看起来不对,请发给支持团队:

不要发送你的密钥。如果密钥出现在聊天记录、日志或他人可见的代码中,请在个人资料中重新生成:旧密钥会立即失效。

响应处理顺序

  1. 检查状态码

    200:读取 data 和 meta,如果返回了 ETag 就保存下来。304:使用上一次响应中的数据。

  2. 处理临时错误

    等待时间较短的 429 和 503:等待 Retry-After 秒后重试,连续最多三次。500:稍后重试。

  3. 请求类错误直接停止

    400、401、403、404、410,以及等待时间长达数小时或数天的 429:修正参数、密钥或套餐,或等待配额重置。

  4. 检查数据时效

    把 meta.updated_at 与当前时间比较:基于旧快照操作的机器人看到的价差可能早已消失。

  5. 安排下一次请求

    至少间隔 meta.freshness_sec 秒,不带过滤的请求使用 If-None-Match。

Python 中的 get_json 函数

该函数把上述规则整合在一起:为每个地址保存最近的 ETag,304 时返回上一次的数据;遇到 429 和 503 时等待 Retry-After 并最多重试三次,但不会等待超过一分钟的停顿。其他错误会抛出异常,包含状态码、消息和 X-Request-Id。密钥取自环境变量 GENESIS_API_KEY。

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (path, params) -> (ETag, data)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # 一次请求加最多 3 次重试
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # 数据未变化
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # 不等待数小时或数天
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "不是 JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # 仅限不带过滤的响应
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

timeout=15 参数必不可少:没有超时的话,requests 会一直等待响应。

按套餐的间隔轮询:完整数据集带 ETag,行在代码中过滤。4xx 错误会终止程序;服务器故障则等待下一个周期。

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # 完整数据集
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "个价差不低于 1% 的交易对")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx:请求、密钥、套餐或配额
        print("服务器错误,下一个周期重试:", e)
    time.sleep(pause)

常见问题

304 响应会消耗配额吗?

不会。只有 200 响应消耗配额。304 响应以及 4xx 和 5xx 错误是免费的,但会计入每秒请求数限制。

收到 410 后该怎么办?

该端点已下线,替代地址在 error.message 中。例如,GET /arbitrage/predictions 已于 2026 年 11 月 15 日下线,其 message 指向 /predictions/arbitrage。请更新代码中的路径。

没有报错,为什么 data 是空的?

过滤条件剔除了所有行:例如 min_spread 高于当前所有价差。这样的响应中 meta.count 等于 0,请放宽过滤条件。

为什么响应中没有 ETag?

ETag 随不带过滤的请求的响应返回。带有 coin、exchange、min_spread 或其他过滤参数的请求,其响应是为该请求单独生成的,不带标签,因此 If-None-Match 不适用于它。