第一个 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 |
| 基础 URL | https://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"
}
}
这个响应的读法:
- 外层结构:
success为true,数据在data中,服务字段在meta中;meta.count是data中的条目数,coin=BTC时是一个币种,其中包含exchanges数组; - 百分比以普通数字返回:
"funding_pct": 0.01表示每个周期 0.01%,而不是 1%;对 $10,000 的仓位,按这个费率一次支付是 10,000 × 0.01 / 100 = $1; funding_8h_pct把费率折算为 8 小时,使不同结算周期的交易所可以直接比较:Hyper 每小时结算一次,0.0013 × 8 = 每 8 小时 0.0104%;next_payout是下次支付时间,以 UTC 的 "HH:MM" 字符串表示,null表示没有数据,而不是零;meta.updated_at是快照生成时的 unix 时间:1794675861 是 2026 年 11 月 14 日 17:04:21 UTC;在 Trial 套餐上快照每 60 秒刷新一次。
所有字段见文档的资金费率部分。下一段代码接着上面的脚本: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 或缺少 /v1 | 404 | 对照文档检查路径 |
参数名拼写错误:coins=BTC | 200 和所有币种:未知参数被忽略 | 检查 meta.count:使用 coin=BTC 时应为 1 |
小数用逗号:min_spread=0,5 | 200,但没有应用筛选 | 用点:0.5 |
用交易对代替代币代码:coin=BTCUSDT | 200,data 为空,meta.count 为 0 | 使用币种代码:BTC |
参数拼错最隐蔽:没有任何报错,但脚本拿到的是完整数据集,而不是单个币种,还白白消耗了一次调用。添加新的筛选条件后,请把 meta.count 与预期值对照。
自己动手试试
不带密钥发送请求
curl -i "https://api.genesisarbitrage.com/v1/account/usage"返回401,响应体中有invalid_key和 "Missing X-API-Key header."。在响应头中找到x-request-id。带上密钥重试
用
read -s设置变量,并发送/account/usage部分中的请求。你会得到200,套餐在data.plan中。核对重置日期
运行 Python 脚本,把额度重置日期与个人资料中“Genesis API”区块里的“resets …”一行对照。获取密钥的分步说明见 Genesis API 快速开始。
找出最高费率
在脚本中加入第二段代码,找出
funding_8h_pct最高的交易所。手动把它的funding_pct折算为 8 小时:费率 × 8 / 以小时计的周期。故意把请求弄坏
把
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。