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,000 | 1 | 60 秒 |
| Start,$50/月 | 2,000,000 | 2 | 30 秒 |
| Pro,$100/月 | 5,000,000 | 5 | 10 秒 |
| Max,$200/月 | 10,000,000 | 15 | 5 秒 |
数据时效是套餐获得新快照的间隔: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-Limit | 5 | 套餐的每秒请求数上限 |
X-RateLimit-Remaining | 4 | 当前窗口剩余请求数 |
X-RateLimit-Reset | 1785200001 | 窗口重置的 Unix 时间 |
X-Quota-Limit | 5000000 | 30 天周期的调用额度 |
X-Quota-Remaining | 4815799 | 本周期剩余调用次数 |
X-Quota-Reset | 1786492800 | 额度重置的 Unix 时间 |
Retry-After | 1 | 出现 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": { … }
}
| 字段 | 类型 | 含义 |
|---|---|---|
plan | string | 套餐:trial、start、pro 或 max |
calls_used | int | 当前周期已用调用次数 |
calls_limit | int | 每周期调用额度 |
rps_limit | int | 每秒请求数上限 |
freshness_sec | int | 数据延迟,单位为秒 |
period_resets_at | int | 额度重置的 Unix 时间 |
该端点所有套餐都可用,说明见用量一节。机器人启动时调用一次,在开始轮询前确认套餐和剩余额度。
429 错误:rate_limited 与 download_limited
| 响应 | 何时出现 | 怎么办 |
|---|---|---|
429 rate_limited | 每秒请求数超出套餐允许值 | 等待 Retry-After,并拉开请求间隔 |
429 rate_limited | 本周期额度已用完 | 等待重置或更换套餐 |
429 rate_limited | 资金费率分析完整下载的间隔短于允许值 | 用 coin 取一部分,或发送 If-None-Match |
429 download_limited | 10 秒内超过 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
| 套餐 | 开放内容 |
|---|---|
| Trial | CEX 套利(Spot – Spot、Spot – Futures、Futures – Futures)、资金费率和资金费率价差、Fair – Last、CEX Pumps – Dumps、持仓量、AI 信号、币种搜索、/account/usage |
| Start | Trial 的全部内容,外加股票 /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。
- 每秒请求数:平均 3 / 10 = 0.3。若三个请求同时发出,会落在同一秒内,Trial 和 Start 会对多出的请求返回
429。 - 每天调用次数:86,400 / 10 = 8,640 次轮询,8,640 × 3 = 25,920 次调用。
- 每 30 天调用次数:25,920 × 30 = 777,600。这超过了 Trial 的 500,000 额度;在 Start 上则是 777,600 / 2,000,000 = 38.88% 的额度。
- 数据时效:Start 的快照每 30 秒更新一次,即每天 86,400 / 30 = 2,880 次。新数据来自 2,880 × 3 × 30 = 259,200 次调用,其余 777,600 − 259,200 = 518,400 次返回的是相同内容。
同一机器人按各套餐的时效轮询:
| 时效与轮询间隔 | 每 30 天调用次数 | 套餐 | 占额度比例 |
|---|---|---|---|
| 每 60 秒 | 129,600 | Trial | 26% |
| 每 30 秒 | 259,200 | Start | 13% |
| 每 10 秒 | 777,600 | Pro | 16% |
| 每 5 秒 | 1,555,200 | Max | 16% |
每 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)
更换与续费套餐
- 新套餐在付款后立即生效:限额和时效更新,额度从零开始计算,原套餐的剩余额度作废。付款前网站会提示你。
- 续费同一套餐会延长有效期,不会重置额度:当前 30 天周期继续计算。
- 更换或续费套餐时密钥保持不变,你的程序无需更新。
- 周期折扣按月价计算:Pro 付 6 个月为 $100 × 0.8 × 6 = $480(原价 $600),付 3 个月为 $100 × 0.9 × 3 = $270。
如何获取和保管密钥,见 Genesis API 密钥指南。
常见问题
额度提前用完会怎样?
在额度重置前,服务器会返回带 Retry-After 的 429 rate_limited,且不扣任何费用。等待新周期,或升级到更高套餐:升级立即生效,并获得全新额度。
304 响应和错误会计入限制吗?
不计入额度:只有 200 占用额度。但它们会计入每秒请求数限制:304 响应和错误会占用每秒窗口中的名额。
如何不消耗调用就查看剩余额度?
读取数据响应里的 X-Quota-Remaining,或调用 /account/usage:该请求不占用调用次数。个人资料中的“已用调用”一行也会显示用量。
用多个密钥能绕过限额吗?
不能。每个账户只有一个密钥,限额按密钥计算,更换 IP 地址也不会改变。开设多个账户来规避限额违反规则;如果需要更多,请升级到更高套餐。