Genesis Arbitrage

Genesis Arbitrage · · 阅读约 18 分钟

第一个 API 请求:HTTP、请求头与 JSON

简而言之

  • 发往 API 的 HTTP 请求由方法、地址(由基础 URL、路径和参数组成)以及请求头构成。Genesis API 的密钥只放在 X-API-Key 请求头中。
  • 状态码决定下一步:200 读取数据,304 没有变化,401 和 403 检查密钥和套餐,429 和 503 等待 Retry-After 秒。
  • Genesis API 的响应是由 success、data 和 meta 组成的外层结构。百分比以普通数字返回(0.01 表示 0.01%),时间为 unix 秒。
  • 新手常见错误:把密钥放进 URL、环境变量为空,以及路径或参数名拼写错误。参数名拼错不会报错:你拿到的是完整数据集,而不是筛选后的结果。

调用 API 时,你的程序发送一个由方法、地址和请求头组成的 HTTP 请求,服务器返回状态码、自己的响应头和响应体,Genesis API 的响应体是 JSON。你可以在终端里用 curl 发送请求,也可以用任何带 HTTP 客户端的语言写代码发送。下面第一个请求用 /account/usage 检查密钥,第二个请求从 /funding/rates 获取 BTC 资金费率。什么是 API,以及能用它自动化哪些事情,见第 1 课。

请求的结构

下面是 curl 为获取 BTC 资金费率发给服务器的请求,由 -v 参数以 > 开头的行显示(密钥已替换为占位符):

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
部分示例中含义
方法GET读取数据;Genesis API 的所有 endpoint 都是 GET
基础 URLhttps://api.genesisarbitrage.com/v1服务器和 API 版本
路径/funding/rates资金费率 endpoint
参数?coin=BTC筛选:只要 BTC
请求头X-API-Key服务器用它识别你的账户和套餐的密钥

参数跟在 ? 后面,写成 名称=值 的形式,多个参数用 & 连接:?coin=BTC&exchange=Binance,OKX。Genesis API 的筛选条件都是可选的,不带 coin 时同一个 endpoint 返回所有币种。小数用点,不用逗号:min_spread=0.5。

请求头是随地址一起发送的 名称: 值 行。请求头名称不区分大小写(RFC 9110,第 5.1 节):X-API-Key 和 x-api-key 是同一个请求头,curl 输出中的小写 x-request-id 就是 X-Request-Id。Genesis API 只接受放在 X-API-Key 中的密钥。

状态码

响应的第一行带有状态码,你的程序根据它决定下一步:

状态码含义怎么做
200请求已处理,数据在响应体中读取 data 和 meta
304数据自你上次响应以来没有变化继续使用之前的数据
401密钥缺失、无效、已撤销或订阅已过期检查请求头和订阅
403你的套餐不包含该 endpoint(plan_restricted)更换套餐或放弃该请求
429超出请求、下载或额度限制等待 Retry-After 秒
503数据正在重建(snapshot_not_ready)等待 Retry-After 秒后重试

只有 200 会消耗你的额度:304 和错误响应不收费,但仍计入每秒请求数限制。304 只会返回给带有 If-None-Match 请求头的请求;该请求头以及 400、404、410、500 状态码见 Genesis API 响应与错误。为什么收到 429 后重试需要暂停,见术语表条目 HTTP 429 Too Many Requests。

第一个请求:/account/usage

/account/usage 显示你的密钥状态:套餐、已用额度和限额。所有套餐都可使用,且不消耗调用次数,所以第一个请求就发到这里。先把密钥放进环境变量,再发送请求:

# 粘贴密钥后按回车:屏幕上不会显示
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

-i 参数会在响应体之前打印状态行和响应头。响应体如下,是 Trial 套餐的示意示例:

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan 是你的套餐,calls_used 相对于 calls_limit 是 30 天周期内的额度使用量。示例中显示 0,因为还没有发过其他请求,而 /account/usage 本身不消耗调用次数。rps_limit 是每秒请求数,freshness_sec 是你的套餐数据的刷新频率,period_resets_at 是额度重置的时间。各字段见文档的用量部分。

在响应头中找到 X-Request-Id,这是你向支持团队提供的请求 ID,用来代替密钥;还有 X-RateLimit-Remaining,即当前 rate limit 窗口内剩余的请求数。

用 Python 发出同样的请求

下面是 Python 3.10+ 配合 requests 库的脚本,从同一个环境变量读取密钥:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # 未设置时抛出 KeyError

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # 不设 timeout,requests 可能一直等待
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

如果变量未设置,os.environ["GENESIS_API_KEY"] 会让脚本直接停止,这比不带密钥发请求再收到 401 要好。r.headers 不区分大小写,所以即使服务器发送的是 x-request-id,也能找到 X-Request-Id。

period_resets_at 是 unix 时间:自 1970 年 1 月 1 日 00:00 UTC 起经过的秒数。datetime.fromtimestamp(ts, timezone.utc) 把它转换成日期:1796463000 是 2026 年 12 月 5 日 09:30 UTC。

第二个请求:BTC 资金费率

资金费率是永续合约中多头与空头之间的周期性支付,交易所每 8、4 或 1 小时结算一次。/funding/rates 返回所有交易所的费率,coin 参数把结果缩小到单个币种。GET /funding/rates?coin=BTC 的响应如下,是列表中两个交易所的示意示例:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

这个响应的读法:

所有字段见文档的资金费率部分。下一段代码接着上面的脚本:BASE、key 和 import 已经写好。

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests 会生成 ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # 遇到 4xx 和 5xx 时抛出异常
body = r.json()
if not body["data"]:
    raise SystemExit("coin not in the data: check the ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
          f'per {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% per 8h')

对于示例响应,脚本输出:

snapshot from 2026-11-14 17:04:21 UTC
Hyper     0.0013% per 1h,  0.0104% per 8h
Bitget      0.01% per 8h,    0.01% per 8h

尽管 Hyper 每个周期的费率低了约 7.7 倍(0.01 / 0.0013),它仍排在 Bitget 之前。如果不折算为 8 小时,这个比较就会出错。

新手常见错误

错误服务器返回如何修复
密钥放在 URL 中:?api_key=…401 和 "Missing X-API-Key header."只在 X-API-Key 请求头中发送密钥
密钥变量为空同样文本的 401:curl 会丢弃空请求头检查长度:echo ${#GENESIS_API_KEY}
路径拼写错误:/v1/funding/rate 或缺少 /v1404对照文档检查路径
参数名拼写错误:coins=BTC200 和所有币种:未知参数被忽略检查 meta.count:使用 coin=BTC 时应为 1
小数用逗号:min_spread=0,5200,但没有应用筛选用点:0.5
用交易对代替代币代码:coin=BTCUSDT200,data 为空,meta.count 为 0使用币种代码:BTC

参数拼错最隐蔽:没有任何报错,但脚本拿到的是完整数据集,而不是单个币种,还白白消耗了一次调用。添加新的筛选条件后,请把 meta.count 与预期值对照。

自己动手试试

  1. 不带密钥发送请求

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" 返回 401,响应体中有 invalid_key 和 "Missing X-API-Key header."。在响应头中找到 x-request-id。

  2. 带上密钥重试

    用 read -s 设置变量,并发送 /account/usage 部分中的请求。你会得到 200,套餐在 data.plan 中。

  3. 核对重置日期

    运行 Python 脚本,把额度重置日期与个人资料中“Genesis API”区块里的“resets …”一行对照。获取密钥的分步说明见 Genesis API 快速开始。

  4. 找出最高费率

    在脚本中加入第二段代码,找出 funding_8h_pct 最高的交易所。手动把它的 funding_pct 折算为 8 小时:费率 × 8 / 以小时计的周期。

  5. 故意把请求弄坏

    把 coin 改成 coins 并对比 meta.count,然后去掉 /funding/rates 中的 s,看看状态码。

哪些 endpoint 可用于价差、订单簿和资金费率的决策,是第 3 课的内容。

常见问题

可以在浏览器里调用 API 吗?

只能打开不需要密钥的地址:https://api.genesisarbitrage.com/health 可以在浏览器中打开,显示 {"ok":true}。地址栏无法添加 X-API-Key 请求头,所以需要密钥的请求要通过 curl、脚本或文档中的“在线试用”表单发送。切勿把密钥嵌入网站或扩展的代码:任何打开页面源码的人都能看到。

curl 中的 -i 和 -v 参数有什么区别?

-i 在响应体之前打印状态行和响应头。-v 还会显示请求本身:以 > 开头的行是发给服务器的内容,以 < 开头的行是返回的内容。

不用 Python 怎么把 unix 时间转成日期?

在 macOS 上运行 date -u -r 1796463000;在 Linux 上运行 date -u -d @1796463000。对这个数字,两者都显示 2026 年 12 月 5 日 09:30 UTC。