Genesis Arbitrage

Genesis Arbitrage · · 阅读约 14 分钟

Genesis API 限额:调用额度、每秒请求数、数据时效与 429 错误

简而言之

  • 套餐决定每 30 天的调用额度(Trial 为 50 万次,Max 为 1,000 万次)、每秒请求数上限(1 到 15)和数据时效(60 到 5 秒)。
  • 只有 200 响应占用额度。304 响应和错误不扣额度,但仍占用每秒请求数的名额;超出限制时服务器返回 429,不扣任何额度。
  • 轮询频率高于 meta.freshness_sec 拿不到新数据:套餐每个间隔只生成一次新快照,而 If-None-Match 可把多余的轮询变成免费的 304 响应。

Genesis API 的限额是每个密钥的四项上限:30 天周期的调用额度、以每秒请求数计的限流、数据时效和下载量。前三项由套餐决定;下载量对所有人相同:每 10 秒 60 MB 压缩数据。任何一项超限,服务器都会返回 429 错误,并且不扣任何额度。

各套餐限额

套餐每 30 天调用次数每秒请求数数据时效
Trial,$20/月500,000160 秒
Start,$50/月2,000,000230 秒
Pro,$100/月5,000,000510 秒
Max,$200/月10,000,000155 秒

数据时效是套餐获得新快照的间隔:Trial 每 60 秒一次,Max 每 5 秒一次。响应中的 meta.freshness_sec 字段给出该值。一次付 3 个月可省 10%,付 6 个月可省 20%。套餐对比见 Genesis API 价格页面,规则见文档中的套餐与限额一节。

什么会占用额度

一次调用即一个 200 响应。304 响应(数据未修改)以及 4xx、5xx 错误不占用额度,但会计入每秒请求数限制。请求 /account/usage 不占用调用次数。

额度按 30 天周期计算,而不是自然月。重置时间见 X-Quota-Reset 请求头、period_resets_at 字段,以及个人资料中的“重置于 …”一行。额度用完后,服务器返回 429 rate_limited,Retry-After 给出距离重置的秒数,可能长达数天。

限流请求头

数据端点的响应会带上你的限额状态(以下为示例值):

请求头示例含义
X-RateLimit-Limit5套餐的每秒请求数上限
X-RateLimit-Remaining4当前窗口剩余请求数
X-RateLimit-Reset1785200001窗口重置的 Unix 时间
X-Quota-Limit500000030 天周期的调用额度
X-Quota-Remaining4815799本周期剩余调用次数
X-Quota-Reset1786492800额度重置的 Unix 时间
Retry-After1出现 429 和 503 时,重试前需等待的秒数

每秒请求数的窗口为一秒,因此正常响应里的 X-RateLimit-Reset 指向下一秒的起点。示例中的剩余额度:5,000,000 − 184,201 = 4,815,799 次调用,与 /account/usage 返回的数字一致。

/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": { … }
}
字段类型含义
planstring套餐:trial、start、pro 或 max
calls_usedint当前周期已用调用次数
calls_limitint每周期调用额度
rps_limitint每秒请求数上限
freshness_secint数据延迟,单位为秒
period_resets_atint额度重置的 Unix 时间

该端点所有套餐都可用,说明见用量一节。机器人启动时调用一次,在开始轮询前确认套餐和剩余额度。

429 错误:rate_limited 与 download_limited

响应何时出现怎么办
429 rate_limited每秒请求数超出套餐允许值等待 Retry-After,并拉开请求间隔
429 rate_limited本周期额度已用完等待重置或更换套餐
429 rate_limited资金费率分析完整下载的间隔短于允许值用 coin 取一部分,或发送 If-None-Match
429 download_limited10 秒内超过 60 MB 压缩数据等待 Retry-After,用过滤参数缩小请求范围

429 Too Many Requests 状态码定义在 RFC 6585 中,其中 Retry-After 是可选的。Genesis API 在每个 429 响应中都会附带它,单位始终是秒。

小于 64 KB 的响应不计入下载量,按套餐时效轮询所有数据集,远在限制之内。不带 coin 的资金费率分析完整下载有单独限制:/funding/analytics/summary 和 /funding/analytics/recent 每 60 秒一次,/funding/analytics/daily 每个密钥每 300 秒一次。带 coin 的请求和 304 响应不受限;详情见资金费率分析一节。

套餐权限与 403 plan_restricted

套餐开放内容
TrialCEX 套利(Spot – Spot、Spot – Futures、Futures – Futures)、资金费率和资金费率价差、Fair – Last、CEX Pumps – Dumps、持仓量、AI 信号、币种搜索、/account/usage
StartTrial 的全部内容,外加股票 /arbitrage/stocks、链上板块 /onchain/{section}、exact 和 dutch 模式的预测套利、平台状态
Pro 和 Max所有端点:DEX – Spot、DEX – Futures、Crosschain、DEX Dumps、订单簿、资金费率分析、预测市场分析、smart money、成交、交易者、llm 和 sport 模式、DEX swap、OnChain 分析和币种

访问套餐之外的端点会返回 403;Start 套餐向 /predictions/arbitrage 发送 mode=sport 请求也一样:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

403 不占用额度。重试没有意义:只有升级套餐才能开通权限。

如何按负载选择套餐

示例:某机器人全天每 10 秒轮询三个端点,/arbitrage/spot-spot、/funding/spread 和 /market/open-interest。

同一机器人按各套餐的时效轮询:

时效与轮询间隔每 30 天调用次数套餐占额度比例
每 60 秒129,600Trial26%
每 30 秒259,200Start13%
每 10 秒777,600Pro16%
每 5 秒1,555,200Max16%

每 10 秒轮询一次,从 Pro 起才合适:777,600 / 5,000,000 = 15.552% 的额度,每秒 5 次的上限也足够三个请求同时发出。如果机器人能接受 30 秒前的数据,Start 每 30 秒轮询一次只占 259,200 / 2,000,000 = 12.96% 的额度。

不浪费调用的轮询:ETag 与 Retry-After

套餐每 meta.freshness_sec 秒获得一次新快照,轮询得更快只会返回同一份快照,meta.updated_at 也相同。不带 If-None-Match 请求头时,这样的响应是 200,会占用一次调用。带上它,服务器返回不含正文的 304:额度不受影响,但仍占用每秒限制中的一个名额。

ETag 并非每个响应都有。完整数据集会返回它,也就是不带过滤参数的请求,例如下面示例中的 /funding/spread。带过滤参数(coin、min_spread 等)的响应没有 ETag,每次轮询都占用一次调用:过滤参数节省流量,ETag 节省额度。重试和压缩见如何高效轮询 API以及响应与错误指南。

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # 额度已用完,到此为止
            raise SystemExit(f"额度已用完,{wait} 秒后重置")
        time.sleep(wait)
        continue
    r.raise_for_status()  # 重试无法解决 401 或 403
    left = r.headers.get("X-Quota-Remaining")  # 可能不存在
    if left is not None and int(left) < 10_000:
        print("额度即将用完:", left)
    if r.status_code == 200:  # 304 时数据未变化
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "个币种在响应中")
    time.sleep(pause)

更换与续费套餐

如何获取和保管密钥,见 Genesis API 密钥指南。

常见问题

额度提前用完会怎样?

在额度重置前,服务器会返回带 Retry-After 的 429 rate_limited,且不扣任何费用。等待新周期,或升级到更高套餐:升级立即生效,并获得全新额度。

304 响应和错误会计入限制吗?

不计入额度:只有 200 占用额度。但它们会计入每秒请求数限制:304 响应和错误会占用每秒窗口中的名额。

如何不消耗调用就查看剩余额度?

读取数据响应里的 X-Quota-Remaining,或调用 /account/usage:该请求不占用调用次数。个人资料中的“已用调用”一行也会显示用量。

用多个密钥能绕过限额吗?

不能。每个账户只有一个密钥,限额按密钥计算,更换 IP 地址也不会改变。开设多个账户来规避限额违反规则;如果需要更多,请升级到更高套餐。