Genesis Arbitrage

Genesis Arbitrage · · 阅读约 4 分钟

ETag 与 If-None-Match

ETag 是一个 HTTP 响应头,携带数据的版本标签:只要资源不变,标签就不变。客户端通过 If-None-Match 头把标签发回去,如果服务器上仍是该版本,就返回不带响应体的 304 Not Modified。这两个头都定义在 RFC 9110(HTTP Semantics,2022)中。

条件请求如何工作

以标签 "a7f3c9" 为例的假设交互:

步骤请求响应
1GET /v1/funding/rates200,ETag: "a7f3c9",JSON 响应体
2同一 URL,带 If-None-Match: "a7f3c9"304 Not Modified,无响应体
3数据更新后的同一请求200,新标签和新的 JSON

按标准,304 响应到响应头为止,不能带响应体,客户端直接使用自己的副本。标签由服务器比较;客户端只需保存收到的最后一个标签,并在同一请求中发回。

import os
import requests

URL = "https://api.genesisarbitrage.com/v1/funding/rates"
cache = {"tag": None, "data": None}  # 完整数据集及其标签

def get_rates():
    headers = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
    if cache["tag"]:
        headers["If-None-Match"] = cache["tag"]
    r = requests.get(URL, headers=headers, timeout=10)
    if r.status_code == 304:
        return cache["data"]  # 数据未变,不占用额度
    r.raise_for_status()
    cache["tag"] = r.headers.get("ETag")
    cache["data"] = r.json()["data"]
    return cache["data"]

# 在本地筛选币种:带 coin 的请求不会返回 ETag
btc = [row for row in get_rates() if row["coin"] == "BTC"]

Genesis API 中的 ETag

在 Genesis API 中只有 200 响应才算一次调用:304 不占用额度,但仍计入每秒请求数限制。它没有响应体,小于 64 KB 的响应也不计入下载流量限制。不带筛选参数的完整数据集会附带标签:带 coin 或筛选参数的请求,其响应是专为该请求生成的,没有 ETag,此时靠筛选本身节省流量(套餐与限额)。

假设示例:某机器人每 60 秒获取一次完整的资金费率分析摘要 /funding/analytics/summary(Pro 和 Max 套餐)。该部分经 gzip 压缩后约 600 KB,标签大约每 15 分钟变化一次。30 天内共 30 × 24 × 60 = 43,200 次请求。使用 If-None-Match 后,其中只有 30 × 24 × 4 = 2,880 次会下载完整内容;其余 40,320 次返回无响应体的 304,也不扣额度。流量从约 26 GB 降到 1.7 GB。

另见:API 轮询、HTTP 429、数据新鲜度、Genesis API 响应格式、ETag 与错误、如何在不触发限制的情况下轮询 API。

常见问题

304 响应会占用 Genesis API 额度吗?

不会。只有 200 响应占用额度;304 和错误都免费,但仍计入每秒请求数限制。

响应里没有 ETag 怎么办?

轮询间隔不要短于 meta.freshness_sec,并把 meta.updated_at 与上一次响应比较:值相同说明快照没有更新。