Genesis Arbitrage

Genesis Arbitrage · · 阅读约 25 分钟

如何轮询加密货币行情 API 而不触发限频:ETag、gzip、过滤参数与 429 后重试

简而言之

  • API 通常有三类限制:每秒请求数、周期内的调用配额和下载量。Genesis API 的限制是每秒 1 到 15 次请求、每 30 天 500K 到 10M 次调用,以及每个密钥每 10 秒 60 MB 压缩数据。
  • 按 meta.freshness_sec 设定轮询间隔:轮询得更快,只会拿到同一份快照。If-None-Match 把重复请求变成免费的 304,gzip 和过滤参数减少流量,一次拉取完整数据集而不是逐币请求则节省调用次数。
  • 遇到 429 和 503,按 Retry-After 给出的秒数后重试;没有该响应头时,用指数退避加随机抖动。客户端令牌桶让请求速度保持在限额之下,X-RateLimit-* 和 X-Quota-* 响应头显示剩余余量。

要让 API 轮询不出现 429 错误,需要同时围绕三类限制来安排请求:每秒请求数、周期调用配额和下载的数据量。五种做法即可覆盖:间隔不短于数据刷新周期、用 ETag 发条件请求、启用 gzip 压缩、用过滤参数代替过大的下载,以及按服务器要求的停顿时间重试。下文的数字和代码针对 Genesis API,这是一个加密货币行情数据的 REST API,但这些做法适用于任何 HTTP API,包括交易所 API。

API 的三类限制:每秒请求数、配额和下载量

按秒计的限频用来拦截突发流量,也就是一次性发出的一批请求。配额限制整个周期内的平均速度,下载量限制则用来拦截那些请求不多、但数据很重的下载。

限制统计对象Genesis API超限后
每秒请求数所有请求,包括 304 和错误Trial 为 1,Start 为 2,Pro 为 5,Max 为 15429 rate_limited,Retry-After: 1
周期配额仅 200 响应每 30 天 500K、2M、5M、10M 次调用429 rate_limited,Retry-After 持续到配额重置
下载量64 KB 及以上的压缩响应所有套餐均为每个密钥每 10 秒 60 MB429 download_limited,直到窗口结束

Genesis API 从不对超限请求计费:429 不占用配额,也不产生费用。全部规则见 Genesis API 限额指南和文档中的套餐与限额部分。

交易所 API 可能更复杂。Binance 按 IP 地址统计请求权重,每个 endpoint 都有自己的权重。收到 429 后仍继续发请求的客户端,会被自动封禁 IP,状态码为 418,屡次违规者封禁时间更长(Binance 文档)。

轮询间隔:30 天会用掉多少次调用

轮询得比数据刷新更快,只会得到重复内容。Genesis Arbitrage 核心每秒刷新一次数据,而你的套餐对应的 API 输出每隔 meta.freshness_sec 秒刷新一次:Trial 为 60,Start 为 30,Pro 为 10,Max 为 5。这就是套餐的数据新鲜度,也是轮询间隔的下限。Genesis API 没有 WebSocket 或 webhook,数据通过 REST 轮询获取。

示例(仅作说明):一个使用 Start 套餐的机器人——每月 $50、2M 次调用、每秒 2 次请求、30 秒新鲜度——轮询四个 endpoint:/arbitrage/spot-spot、/arbitrage/spot-futures、/funding/spread 和 /market/open-interest。

间隔30 天调用次数占 Start 配额的比例同一快照的重复次数
60 秒172,8008.64%无
30 秒345,60017.28%无
10 秒1,036,80051.84%3 次中有 2 次
5 秒2,073,600103.68%6 次中有 5 次

每 5 秒轮询一次,配额会在第 29 天用完:每天 4 × 86,400 / 5 = 69,120 次调用,2,000,000 / 69,120 ≈ 28.9 天。每六个响应中有五个重复同一份快照,meta.updated_at 相同;没有 If-None-Match 时,每个都要消耗一次调用。

每 30 秒轮询一次时,平均速度为 4 / 30 ≈ 0.13 次请求每秒。但同时发出的四个请求落在同一秒内,其中两个会收到 429。如果需要比 30 秒更新鲜的数据,办法是换用 freshness_sec 更低的套餐:Pro 每 10 秒刷新一次快照,Max 每 5 秒一次。

条件请求:ETag、If-None-Match 与 304

ETag 是响应的版本标签。客户端保存它,并在下次请求同一 URL 时通过 If-None-Match 请求头发回;如果版本没有变化,服务器返回 304 Not Modified。按 RFC 9110,304 在响应头之后即结束,不带响应体,因此你使用自己保存的那份数据。

在 Genesis API 上,304 不占用配额,但仍占用每秒请求数限制中的一个名额。只有不带过滤参数的完整数据集才有标签。带 coin、exchange、min_spread 等过滤参数的请求,以及 /orderbooks/book 和 /orderbooks/coin/{coin},都是按请求实时生成的,不带 ETag。

当数据变化的频率低于你的请求频率时,ETag 才能节省配额。价差数据的标签每个快照都会变化,所以当你每 freshness_sec 轮询一次时,几乎每个响应都是 200。

Pro 套餐示例(仅作说明):资金费率分析的每日汇总 /funding/analytics/daily 每小时重新生成一次;积累满一年历史后,完整部分约为 12 MB gzip,不带 coin 时最多每 300 秒提供一次。每 300 秒轮询一次,30 天共 2,592,000 / 300 = 8,640 次请求。使用 If-None-Match 后,该部分只需下载 30 × 24 = 720 次,其余 8,640 − 720 = 7,920 个响应返回 304。

结果:调用次数从 8,640 降到 720,流量从约 104 GB 降到约 8.6 GB。304 响应不计入完整下载限制。

过滤参数与 coin:哪个省调用,哪个省流量

过滤参数会缩小响应,但不会减少调用次数:配额统计的是响应,带 coin=BTC 的请求与完整数据集花费相同。所以选择取决于哪一项先耗尽,是调用次数还是流量。

Start 套餐示例(仅作说明):一个机器人跟踪五个币种的资金费率。每 30 秒向 /funding/rates 发五次带 coin 的请求,30 天为 5 × 86,400 = 432,000 次调用,而且每个周期的五次请求会冲击每秒 2 次的限制。改为请求一次完整的 /funding/rates,在代码里挑出这些币种,只需 86,400 次调用,少五倍,还能拿到 ETag。

任务请求方式节省什么
从同一数据集取多个币种带 If-None-Match 的完整数据集,在代码中过滤调用次数:一次请求代替多次
从较重的部分取单个币种coin 参数流量和下载量限制
高于阈值的行min_spread、min_volume流量,但每次轮询都是一次调用
完整获取更新较慢的部分带 If-None-Match 的完整数据集调用次数和流量

最重的部分属于资金费率分析:完整汇总约 600 KB gzip,7 天结算约 1 MB,每日汇总最大 12 MB(资金费率 endpoint)。用 coin 取单币种切片不受完整下载限制约束;该限制对汇总和结算是每 60 秒一次,对每日汇总是每 300 秒一次。

gzip 压缩

压缩可以减少网络上传输的字节数。客户端通过 Accept-Encoding: gzip 请求压缩,服务器返回压缩后的响应体并附带 Content-Encoding: gzip 响应头。Python 的 requests 会在 Accept-Encoding 中加入 gzip 并自动解压响应;curl 则使用 --compressed 实现同样效果。

在 Genesis API 中,压缩与一项限制挂钩:下载量按压缩后的数据统计,每个密钥每 10 秒 60 MB,小于 64 KB 的响应不计入。完整数据集和较大的响应会在客户端请求时以 gzip 返回(Genesis API 响应与错误)。要查看网络上实际传输了多少响应体字节,可以使用 curl 的 size_download 变量:

# body bytes on the wire with and without gzip; each request is a call
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"

429 后重试:Retry-After 与带抖动的退避

HTTP 429 Too Many Requests 是服务器对超限客户端的回应。按 RFC 6585,响应可以带 Retry-After 响应头;按 RFC 9110,它的值是秒数或一个日期。Genesis API 在每个 429 和 503 中都会发送以秒为单位的 Retry-After。

不停顿的重试几乎总会得到同样的错误,还会再占用每秒窗口中的一个名额。如果有 Retry-After,就等待服务器要求的时间。如果没有,则在每次失败后按指数增加等待时间:最长 1、2、4、8 秒。

抖动是在停顿时间上加的随机量,客户端很多时尤其重要:没有它,同一秒内收到错误的所有客户端会在同一秒重试。backoff 函数在零和当前步长之间随机选一个停顿时间,并在 Retry-After 上加上不到一秒的随机量。fetch 会重试 429、500 和 503,当停顿超过 10 分钟时停止:配额耗尽就是这个样子。

import os
import random
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session()  # reuses the TCP connection, gzip is on
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # path -> (ETag, data): full datasets only


def backoff(attempt, retry_after=None, cap=60.0):
    """Pause before a retry, in seconds."""
    if retry_after and retry_after.isdigit():
        return int(retry_after) + random.uniform(0, 1)
    return random.uniform(0, min(cap, 2 ** attempt))


def fetch(path, params=None, tries=5):
    """GET from the API: returns (data, response headers)."""
    for attempt in range(tries):
        tag = None if params else cache.get(path, (None,))[0]
        try:
            r = api.get(BASE + path, params=params, timeout=15,
                        headers={"If-None-Match": tag} if tag else {})
        except (requests.ConnectionError, requests.Timeout):
            time.sleep(backoff(attempt))
            continue
        if r.status_code == 304:  # same snapshot, no quota used
            return cache[path][1], r.headers
        if r.status_code in (429, 500, 503):
            wait = backoff(attempt, r.headers.get("Retry-After"))
            if wait > 600:  # this is what an exhausted quota looks like
                raise RuntimeError(f"quota resets in {wait:.0f} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403, 404, 410: do not retry
        data = r.json()["data"]
        if not params and "ETag" in r.headers:
            cache[path] = (r.headers["ETag"], data)
        return data, r.headers
    raise RuntimeError(f"{path}: no response after {tries} tries")
响应停顿是否重试
429 rate_limited,每秒限制Retry-After: 1 再加不到一秒的随机量是
429 rate_limited,配额直到配额重置,可能长达数天否
429 download_limitedRetry-After,直到窗口结束是,请求要更窄
503 snapshot_not_readyRetry-After是
500、超时、连接中断带抖动的指数退避是
400、401、403、404、410—否,修正请求

配额耗尽与每秒限制可以通过 Retry-After 区分:前者是一秒,后者是距离重置还有数小时或数天,同时响应体中有 Monthly call quota exceeded.。错误码和响应体见文档的错误部分。

客户端限流器:令牌桶

重试处理的是已经出现的 429,客户端限流器则是预防它。令牌桶的工作方式是:令牌以每秒 rate 个的速度生成,每个请求取走一个,桶空了就要等待。容量 burst 决定了能无停顿连续发出多少个请求。

import time


class TokenBucket:
    """At most rate requests per second, up to burst back to back."""

    def __init__(self, rate, burst=1):
        self.rate, self.burst = rate, burst
        self.tokens = float(burst)
        self.last = time.monotonic()

    def take(self):
        while True:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens
                              + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return
            time.sleep((1 - self.tokens) / self.rate)

限额取自 /account/usage 的 rps_limit 字段(见用量部分),或取自 X-RateLimit-Limit 响应头。把速率设得略低于限额,例如 0.9 * rps_limit:网络延迟并不均匀,间隔半秒发出的请求可能更紧挨着到达服务器。

监控:X-RateLimit-* 与 X-Quota-* 响应头

数据响应会带上你的限额状态:X-RateLimit-Remaining 和 X-RateLimit-Reset 给出每秒窗口内的剩余次数及重置时间,X-Quota-Remaining、X-Quota-Limit 和 X-Quota-Reset 则给出剩余配额、配额总量和重置的 unix 时间。比任何单个剩余值更有用的是消耗节奏:在周期中的这一时点,配额已经用掉了多少比例。

PERIOD = 30 * 86400  # Genesis API counts quota per 30 days


def watch(h):
    """Checks limit headroom from the response headers."""
    if h.get("X-RateLimit-Remaining") == "0":  # window used up
        reset = float(h.get("X-RateLimit-Reset", 0))
        time.sleep(max(0.0, reset - time.time()))
    try:
        left = int(h["X-Quota-Remaining"])
        limit = int(h["X-Quota-Limit"])
        reset = int(h["X-Quota-Reset"])
    except (KeyError, ValueError):
        return  # 429 responses carry no X-Quota-* headers
    used = 1 - left / limit
    passed = 1 - (reset - time.time()) / PERIOD
    if used > passed + 0.05:
        print(f"quota is running ahead: {used:.0%} used"
              f" with {passed:.0%} of the period gone")

该函数在窗口额度用完时等待其重置,并在配额消耗领先日历进度超过 5 个百分点时发出警告。示例(仅作说明):到第 15 天已用掉 70% 的配额,按同样的速度,调用会在周期的第 15 / 0.7 ≈ 21.4 天耗尽。/account/usage 不需要响应头就能给出同样的数字:calls_used、calls_limit 和 period_resets_at。

多个 endpoint 的调度

有多个 endpoint 时,每个都有自己的间隔,并且把首批请求错开,避免集中发出。按任务选择间隔,但不要低于 freshness_sec:价差数据需要套餐的全速刷新,而对许多策略来说,资金费率和持仓量每分钟一次就够了。

import heapq

usage, _ = fetch("/account/usage")  # does not use a call
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])

JOBS = {  # path -> polling interval, s
    "/arbitrage/spot-spot": fresh,
    "/funding/spread": max(fresh, 60),
    "/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
         for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)

while True:
    due, path, every = heapq.heappop(queue)
    time.sleep(max(0.0, due - time.monotonic()))
    bucket.take()
    data, hdrs = fetch(path)
    watch(hdrs)
    print(path, len(data))
    heapq.heappush(queue, (due + every, path, every))

在 Start 套餐上,30 天为 86,400 + 43,200 + 43,200 = 172,800 次调用,占配额的 8.64%:价差每 30 秒一次,资金费率和持仓量每 60 秒一次。首批请求相隔 30 / 3 = 10 秒发出,之后每个 endpoint 保持自己的节奏,bucket.take() 防止请求撞在一起。基于这种轮询、带 Telegram 提醒的机器人见用 Python 写加密货币套利机器人。

遇到 503 和服务器错误怎么办

按 RFC 9110,503 Service Unavailable 表示临时过载或维护,服务器可以在 Retry-After 中建议停顿时间。在 Genesis API 上,这对应 503 snapshot_not_ready:数据正在重建,或数据源正在重启。按 Retry-After 秒数后重试;停顿通常只有几秒。

在没有新响应期间,机器人手里仍是上一次轮询的数据,而这些数据正在变旧。发出信号之前,把 meta.updated_at 与当前时间比较:一分钟前快照中的交易对,在交易所里可能已经消失。其他风险见自动化风险一课。

对 500 internal_error、超时和连接中断,用指数退避重试。如果错误持续,请联系支持团队,并提供 X-Request-Id 的值、UTC 请求时间、endpoint 和状态码。切勿发送你的密钥。

常见问题

我每秒可以向 Genesis API 发送多少次请求?

以套餐允许的为准:Trial 为 1,Start 为 2,Pro 为 5,Max 为 15。限额按密钥计算,包括 304 响应和错误。你的套餐数值在 X-RateLimit-Limit 响应头和 /account/usage 的 rps_limit 字段中。

错误和 304 响应会消耗我的配额吗?

不会。只有 200 响应会占用配额;304、429、503 和其他错误都是免费的,不产生费用。不过它们会占用每秒请求数限制中的名额,所以不停顿的重试会引发新的 429 响应。

如何保持在每 10 秒 60 MB 以下?

启用 gzip:限制统计的是压缩后的数据。对完整数据集发送 If-None-Match:304 没有响应体。对资金费率分析这类较重的部分,用 coin 切片获取,并且不要比 freshness_sec 更频繁地下载同一个完整数据集。小于 64 KB 的响应不计入,根据文档,按套餐的新鲜度间隔轮询每个数据集,完全在限制之内且有充足余量。

429 Too Many Requests 错误是什么意思?

服务器拒绝了请求,因为客户端在某个时间窗口内超出了限额。响应可以带 Retry-After,即需要等待的秒数;没有的话,每次失败后把停顿时间翻倍。在 Genesis API 中,429 会附带 rate_limited 或 download_limited 代码。