Genesis API 资金费率接口:费率、价差与资金费率历史分析
简而言之
/funding/rates和/funding/spread所有 API 套餐都可用:各交易所按结算周期和按 8 小时的费率、下次结算时间,以及价差最大的最佳交易所组合。- 已结算资金费率分析由四个
/funding/analytics/…接口组成,覆盖 13 家交易所、最长一年的历史,适用于 Pro 和 Max 套餐。 - 完整的 summary、recent 和 daily 下载 gzip 后最大约 12 MB,每 60–300 秒只能请求一次:请使用
coin切片,或带If-None-Match重复请求。
Genesis API 的资金费率接口是一组端点,提供各交易所永续合约的资金费率、按资金费率价差排序的最佳交易所组合,以及已结算资金费率的历史。当前费率和价差所有 API 套餐都可用;13 家交易所的历史分析在 Pro 和 Max 套餐中。网站在 Funding Arbitrage 中展示同样的数据,参见指南。
资金费率接口与套餐
| 接口 | 返回内容 | API 套餐 |
|---|---|---|
/funding/rates | 每个币种在各交易所的费率 | Trial、Start、Pro、Max |
/funding/spread | 价差最大的最佳交易所组合及其他交易所 | Trial、Start、Pro、Max |
/funding/analytics/summary | 1 天到一年各周期的汇总 | Pro、Max |
/funding/analytics/recent | 7 天内的每一笔结算 | Pro、Max |
/funding/analytics/daily | 365 天的每日合计 | Pro、Max |
/funding/analytics/top | 币种组合与交易所组合筛选器 | Pro、Max |
参数和字段见文档中的资金费率、资金费率价差和资金费率分析部分。在 Trial 和 Start 套餐中,分析接口返回 403 plan_restricted。关于资金费率数据 API 的概览,请看资金费率 API一文。下面的响应示例展示的是精简后的 data 字段。
费率与 8 小时标准化
/funding/rates 为每个币种返回一个带有当前费率的交易所列表。coin 和 exchange 过滤参数(多个交易所用逗号分隔)均为可选。
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=TON" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"coin": "TON",
"exchanges": [
{
"exchange": "MEXC",
"funding_pct": 0.02,
"funding_8h_pct": 0.04,
"next_payout": "00:00",
"interval": "4h",
"price": 2.184,
"trade_url": "https://futures.mexc.com/exchange/TON_USDT"
}
]
}
| 字段 | 含义 |
|---|---|
funding_pct | 每个结算周期的费率,% |
funding_8h_pct | 标准化为 8 小时的费率,% |
interval | 结算周期,例如 8h;null 表示无数据 |
next_payout | 下次结算时间,HH:MM UTC;null 表示无数据 |
price, trade_url | 价格和交易所交易终端的链接 |
假设的例子:每小时 0.005% 的费率折合 8 小时为 0.005 × 8 / 1 = 0.04%,与 MEXC 相同,区别只是要结算八次,而且下一小时可能变化。
不计复利年化时,8 小时费率 × 3 × 365 即为 APR。假设的例子:每 8 小时 0.01%,只要费率不变,一年就是 0.01 × 3 × 365 = 10.95%。费率对市场意味着什么,见资金费率作为市场指标。
资金费率价差:最佳交易所组合
/funding/spread 为每个币种返回资金费率价差最大的交易所组合(best)和其他交易所(others)。过滤参数:coin 和 min_spread,即以 % 计的最小价差。
{
"coin": "BTC",
"spread_pct": 0.01,
"best": {
"exchange_1": "Hyper",
"exchange_2": "CoinEx",
"funding_1_pct": 0.0,
"funding_2_pct": 0.0,
"next_payout_1": null,
"next_payout_2": "08:00",
"interval_1": "1h",
"interval_2": "8h",
"trade_url_1": "https://app.hyperliquid.xyz/trade/BTC",
"trade_url_2": "https://www.coinex.com/futures/BTC-usdt"
},
"others": [ … ]
}
spread_pct 是最佳组合的价差,%。funding_1_pct 和 funding_2_pct 是各自结算周期(interval_1、interval_2)内的费率:手动比较时,请先把两者都标准化为 8 小时。费率较高的一侧做空,较低的一侧做多。响应中 Hyperliquid 显示为 Hyper。
下面的 Python 脚本会输出 spread_pct 最高的十个币种(从 0.05% 起)以及组合的结算周期。遇到 429 和 503 时,脚本等待 Retry-After 秒;在循环中,每个 meta.freshness_sec 内最多重复请求一次。
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
for _ in range(3):
r = requests.get(URL, headers=HEADERS,
params={"min_spread": 0.05}, timeout=15)
if r.status_code not in (429, 503):
break
# rate limit or data being rebuilt: wait and retry
time.sleep(int(r.headers.get("Retry-After", "5")))
r.raise_for_status()
rows = sorted(r.json()["data"], key=lambda x: x["spread_pct"],
reverse=True)
for row in rows[:10]:
b = row["best"]
print(f'{row["coin"]:<10} {row["spread_pct"]:>8.4f}% '
f'{b["exchange_1"]} {b["interval_1"]} / '
f'{b["exchange_2"]} {b["interval_2"]}')
已结算资金费率分析
四个 /funding/analytics/… 接口返回 13 家交易所已结算的资金费率历史,与 Funding Arbitrage 中“分析”标签页的数据相同。费率为每个结算周期的百分比,时间戳为 UTC epoch 秒。
| 接口 | 内容 | 完整数据 | 不带 coin 时最多 |
|---|---|---|---|
/funding/analytics/summary | 7 个周期的合计、平均费率、APR 和覆盖率 | ~600 KB gzip | 每 60 秒一次 |
/funding/analytics/recent | 7 天内的每一笔结算 | ~1 MB gzip | 每 60 秒一次 |
/funding/analytics/daily | 365 天的每日合计 | 最大约 12 MB gzip | 每 300 秒一次 |
/funding/analytics/top | 每个周期前 50 个币种组合和前 50 个交易所组合 | — | 无限制 |
在时间窗口结束前再次完整下载,会收到带 Retry-After 的 429。ETag 和压缩规则见响应格式与错误指南。
curl --compressed -i \
"https://api.genesisarbitrage.com/v1/funding/analytics/summary" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-H "If-None-Match: <ETag from the previous response>"
--compressed 请求压缩响应并自动解压,-i 输出响应头,其中包括 ETag。第一次请求不要带 If-None-Match。
summary 与 m 数组
summary 中每个“币种×交易所”组合都有 m:键是周期(1d、3d、7d、30d、90d、180d、365d),值是按 metric_order 排列的 14 个数字。某个周期完全没有数据时,m 中不会出现该周期。
{
"metric_order": ["sum", "avg8h", "apr", "n", "pos", "neg", "zero",
"min", "max", "cov", "med8h", "pos_streak",
"neg_streak", "flips"],
"coins": {
"BTC": {
"canon": "BTC",
"mult": 1,
"exchanges": {
"Binance": {
"interval_h": 8.0,
"data_since": 1568102400,
"last8h": 0.004123,
"m": {
"7d": [0.12802, 0.006298, 6.896, 21, 21, 0, 0,
0.000125, 0.01, 1.0, 0.00588, 7, 0, 0]
}
}
}
}
}
}
| 指标 | 索引 | 含义 |
|---|---|---|
sum | 0 | 周期内累计,% |
avg8h | 1 | 按 8 小时折算的平均费率,% |
apr | 2 | 年化,% |
n | 3 | 结算次数 |
pos, neg, zero | 4–6 | 正、负和零值结算的次数 |
min, max | 7–8 | 最小和最大的一次结算,% |
cov | 9 | 周期覆盖率,0 到 1 |
med8h | 10 | 按 8 小时折算的中位数,% |
pos_streak, neg_streak | 11–12 | 连续为正和连续为负的天数 |
flips | 13 | 正负号变化次数 |
1d 和 3d 周期的索引 10–13 为 null。cov < 0.9 时,数据只覆盖周期的一部分,请对这类数值加以标注。示例中,Binance 上 BTC 的 7 天数据:21 次结算,全部为正,cov 为 1.0,apr 等于 avg8h × 3 × 365:0.006298 × 1095 ≈ 6.896。
如果 avg8h 明显高于 med8h,说明某次尖峰拉高了平均值:中位数、pos_streak 和 flips 更能反映稳定性。该组合的其他字段:
data_since— 数据的起始时间;不要在此日期之前补零。last8h— 按 8 小时折算的最新费率,用于“当前与常态”的对比。interval_h— 结算周期:CEX 上为 8 或 4 小时,Hyperliquid 和 Lighter 上为 1 小时。canon和mult— 合并代码变体的名称(1000PEPE→PEPE)和合约乘数;mult从不用于费率。
7 天结算与每日合计
在 /funding/analytics/recent 中,每家交易所有一个按时间升序排列、形如 ts:rate;ts:rate;… 的字符串 s,以及以小时计的周期 i。在 /funding/analytics/daily 中,字符串 day_ts:sum:pos:neg;… 包含 UTC 零点、当天合计,以及正负结算的次数。
def parse_recent(s):
# "ts:rate;ts:rate;…" → [(ts, rate), …]
return [(int(t), float(v)) for t, v in
(p.split(":") for p in s.split(";") if p)]
def parse_daily(s):
# "day_ts:sum:pos:neg;…" → [(day, sum, positive, negative), …]
out = []
for p in filter(None, s.split(";")):
d, total, pos, neg = p.split(":")
out.append((int(d), float(total), int(pos), int(neg)))
return out
组合筛选器
/funding/analytics/top 是一个无需参数的现成筛选器:对每个周期,按累计资金费率给出前 50 个“币种×交易所”组合,以及前 50 个做空/做多组合。组合的两条腿始终在不同交易所,覆盖率至少 0.9,net ≤ 0 的行不会出现。
by_net_apr— 按净收益排序。by_stable—win_rate≥ 0.7,且回撤不超过 gross 的一半。by_live—live_8h> 0 且trend_1d> 0。by_sum_pos,by_sum_neg— 按累计资金费率排序的单交易所榜单,仅限cov≥ 0.5。
| 组合字段 | 含义 |
|---|---|
gross, fees, net | 资金费率毛收益、按 taker_fees 计算的四笔交易手续费,以及 net = gross − fees |
apr_net, apr_capital | 按单腿名义价值年化,以及按两条腿资金计算的 apr_net / 2 |
win_rate, max_dd | 盈利天数占比(0..1)和累计结果的最大回撤 |
worst_streak, risk_days | 最长连续亏损天数,以及计算风险所用的天数,最多 90 |
live_8h, trend_1d, trend_7d | 按 8 小时计的当前费率差,以及最近一天和一周的毛价差 |
price_div | 两条腿之间当前的价格差;无价格时为 null |
short_sym, long_sym | 交易所上实际的两条腿代码,可能不同:PEPE 和 1000PEPE |
文档示例中,PEPE 组合在 HTX 做空、在 Hyperliquid 做多,7 天的 gross 为 1.51504%。手续费为:HTX 开仓和平仓各 0.05%,Hyperliquid 各 0.045%:0.05 × 2 + 0.045 × 2 = 0.19。
因此 net = 1.51504 − 0.19 = 1.32504%,apr_net = 1.32504 × 365 / 7 ≈ 69.09%,apr_capital = 69.09 / 2 ≈ 34.55%。两条腿之间的价格差、滑点和保证金未计入。
如何搭建资金费率监控
找出候选币种
请求
/funding/spread并带上min_spread(任何 API 套餐),再按spread_pct排序。核对费率与结算时间
请求
/funding/rates并带上coin:查看两家交易所的interval、next_payout和funding_8h_pct。仓位必须在结算时刻持有。查看历史
在 Pro 和 Max 上,请求
/funding/analytics/summary并带上coin:7d 和 30d 的sum、apr、cov和flips能说明费率差是否持续。整体评估组合
在
/funding/analytics/top中比较net、apr_capital、win_rate、max_dd和当前的price_div。自行开仓
trade_url链接指向交易所终端;可在价差计算器中把手续费算进组合。
常见问题
如何把资金费率标准化为 8 小时?
把每个周期的费率乘以 8,再除以以小时计的周期长度。/funding/rates 已在 funding_8h_pct 字段中替你算好。
在哪里获取资金费率历史?
/funding/analytics/recent 提供 7 天内的每一笔结算,/funding/analytics/daily 提供一年的每日合计,/funding/analytics/summary 提供各周期的汇总。三者都在 API 的 Pro 和 Max 套餐中。
为什么完整的分析数据返回 429?
不带 coin 的完整下载有频率限制:summary 和 recent 每个密钥每 60 秒一次,daily 每 300 秒一次。币种切片和针对 If-None-Match 的 304 响应不受限制。