持仓量 API:跨交易所合约 OI 数据及其解读方法
简而言之
- 持仓量是合约中仍未平仓的头寸总量。以币数计算时,它反映头寸的流入;以美元计算时,它还会随价格变动。
- 每家交易所都以自己的格式和单位发布 OI。在 Genesis API 中,一次
/market/open-interest调用即可覆盖 13+ 家交易所:合计在total中,明细在exchanges中,OI 和价格在 5、15、30 分钟及 1 小时内的变化在所有套餐中都有。 - 结合价格和资金费率阅读,OI 能显示谁在建仓、谁在为持仓付费。它不能预测价格;决策和交易所里的下单仍由你自己负责。
持仓量 API 会为每个币种返回未平仓合约头寸的规模,以币和美元计,分交易所并给出合计,同时附带最近几分钟和几小时内的变化。交易所通过各自的 API 发布自家合约的 OI,格式因交易所而异。在 Genesis API 中,完整快照来自对 /market/open-interest 的一次调用:13+ 家合约交易所,包括 Binance、Bybit、OKX、Bitget 和 Gate,OI 和价格在 5、15、30 分钟及 1 小时内的变化在所有套餐中都有,从每月 20 美元的 Trial 起。
什么是持仓量
持仓量(OI)是某个合约上已开仓、尚未平仓的头寸总和。每份合约有多空两方,OI 只计其中一方:一位交易者买入 1 BTC 多单,另一位卖出 1 BTC 空单,持仓量增加 1 BTC。
交易双方都开仓时 OI 上升,双方都平仓时 OI 下降,头寸从一位交易者转到另一位时 OI 不变。因此,OI 上升表示有新头寸进入,OI 下降表示头寸被主动或被迫平掉。
以币计和以美元计的 OI
交易所以合约张数、币数或直接以美元报告 OI,币数按价格换算成美元。在 Genesis API 的示例响应中,ByBit 上 GRAM 的 oi_usd 等于 oi_tokens 乘以 price:16,159,003.8 × 1.6609 = 26,838,489.41。
美元数值便于比较不同币种和交易所,但它会随价格变动。示例(仅作说明):某交易所有 2,000,000 个币的未平仓头寸,价格为 1.50 美元,OI 为 2,000,000 × 1.50 美元 = 3,000,000 美元。一小时后头寸不变,价格为 1.65 美元,美元计 OI 已是 2,000,000 × 1.65 美元 = 3,300,000 美元,在没有任何新头寸的情况下增加了 10%。
总 OI 与分交易所明细
某个币的总 OI 是上线其合约的各交易所 OI 之和,显示市场在头寸中持有多少资金。明细则显示这些资金在哪里:在同一响应中,ByBit 持有 GRAM 美元 OI 的 26,838,489.41 / 96,544,685.3 × 100 = 27.8%。
| 指标 | 显示什么 | 注意点 |
|---|---|---|
| 以币计的 OI | 有多少头寸未平仓 | 各交易所合约面值不同 |
| 以美元计的 OI | 头寸中有多少资金 | 随价格变动 |
| 总 OI | 全市场的头寸 | 取决于汇总了哪些交易所 |
| 分交易所 OI | 头寸在哪里建立 | 各交易所口径不同 |
Binance、Bybit、OKX 和 Hyperliquid 的 API 返回什么
每家交易所通过自己的 API 发布合约的 OI。以下是官方文档的说明:
| 交易所 | 当前 OI | OI 历史 | 注意事项 |
|---|---|---|---|
| Binance | GET /fapi/v1/openInterest,每次请求一个 symbol | GET /futures/data/openInterestHist | 历史只覆盖最近一个月 |
| Bybit | GET /v5/market/tickers,一次请求返回所有交易对 | GET /v5/market/open-interest,步长从 5min 到 1d | openInterest 统计双方,singleOpenInterest 统计单方 |
| OKX | GET /api/v5/public/open-interest | GET /api/v5/rubik/stat/contracts/open-interest-history | oi 以合约张数计,oiCcy 以币数计,oiUsd 以美元计 |
| Hyperliquid | POST /info,类型 metaAndAssetCtxs | 文档中没有 | 一次请求返回永续合约的 OI |
详情见 Binance、Bybit、OKX 和 Hyperliquid 的文档。Binance 历史以 sumOpenInterest 和 sumOpenInterestValue 返回,OKX 则返回最近 1,440 条记录,步长最小 5 分钟。Hyperliquid 接受发往 https://api.hyperliquid.xyz/info、请求体为 {"type": "metaAndAssetCtxs"} 的请求,并为每个永续合约返回 openInterest,同时附带 markPx 和 funding。
口径差异可能达到两倍。在 Bybit 的 /v5/market/open-interest 示例响应中,openInterest 为 63,910,691,singleOpenInterest 为 31,955,346,正好是一半:前者统计双方,后者统计单方,与上文的 OI 定义一致。
自己构建一份快照,意味着要按各家规则轮询每个交易所,把合约张数换算成币、再把币换算成美元,并遵守每家的限制。在 Binance 上,这需要为每份合约单独发一次请求。
Genesis API 中的持仓量:/market/open-interest
/market/open-interest endpoint 返回的数据与网站上的 OI 追踪表格相同:每个币的总 OI 在 total 中,分交易所明细在 exchanges 中。不带参数时返回所有币;coin 只保留一个币,exchange 只保留所选交易所,多个交易所用逗号分隔。
curl -G "https://api.genesisarbitrage.com/v1/market/open-interest" \
-d coin=GRAM \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
响应是一个 data 数组。下面是文档中的其中一个元素,部分字段已省略:
{
"coin": "GRAM",
"total": {
"oi_usd": 96544685.3,
"oi_tokens": 58105803.3,
"avg_price": 1.661224,
"volume_24h": 47010004.63,
"oi_change_5m": 0.0196,
"oi_change_1h": 0.3185,
"price_change_5m": -0.0228,
"price_change_1h": -0.1929,
…
},
"exchanges": {
"ByBit": {
"price": 1.6609,
"oi_usd": 26838489.41,
"oi_tokens": 16159003.8,
"oi_change_1h": -0.097,
"price_change_1h": -0.1683,
"trade_url": "https://www.bybit.com/trade/usdt/GRAMUSDT",
…
}
}
}
| 字段 | 含义 |
|---|---|
total.oi_usd / total.oi_tokens | 以美元和以币数计的总 OI |
total.avg_price | 各交易所的平均币价 |
total.volume_24h | 24 小时成交量,USD |
total.oi_change_5m/15m/30m/1h | OI 在 5、15、30 分钟及 1 小时内的变化,% |
total.price_change_5m/15m/30m/1h | 相同区间内的价格变化,% |
exchanges{} | 按交易所的相同指标:用 price 代替 avg_price,另有 trade_url |
变化值为百分数:0.3185 表示 0.3185%。空值以 null 返回,请跳过。新鲜度取决于套餐:Trial 为 60 秒,Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒,因此轮询频率高于 meta.freshness_sec 没有意义。
不带过滤条件的响应带有 ETag 头。把它放进 If-None-Match 回传,快照未变化时会返回 304,不消耗你的配额;机制见 ETag 和 If-None-Match。exchange 过滤只会缩小 exchanges:total 仍然按所有交易所计算。
字段、参数和“在线试用”表单见文档的“OI 追踪”部分。所有市场 endpoint 的示例讲解见 Genesis API 市场数据指南。
结合价格解读 OI:四种情形
OI 上升说明有头寸在开,但不能说明是哪一方在推动。同一区间内的价格可以给出线索。
| 价格 | OI | 常见解读 | 需要核对 |
|---|---|---|---|
| 上涨 | 上升 | 顺着走势有新头寸进入,上涨有资金支撑 | 资金费率:明显为正说明多头拥挤 |
| 下跌 | 上升 | 空头在建仓,或多头在下跌中买入 | 资金费率:明显为负说明存在轧空风险 |
| 上涨 | 下降 | 上涨靠空头回补推动,没有新资金 | 每家交易所的 OI 是否都在下降 |
| 下跌 | 下降 | 多头在平仓,无论主动还是被迫 | 5 分钟内 OI 骤降指向强平 |
在文档示例中,GRAM 的总 OI 一小时内上升 0.32%,价格下跌 0.19%,形式上属于第二行。不过每小时零点几个百分点属于正常噪声:请在明显的走势和 OI 较大的币种上使用这些情形。
OI 与资金费率:谁持仓、谁买单
资金费率显示永续合约中哪一方向另一方付费,OI 显示有多少头寸未平仓。两者结合,既能看出市场偏向哪一边,也能看出杠杆有多重。
OI 和价格上升而费率明显为正,说明多头在加仓,并向空头付费以持有头寸。如果价格转向,他们的强平会加速下跌。OI 和价格上升而费率为负,说明空头在逆势建仓,一轮急涨可能迫使他们平仓。
资金费率、OI 和价格的各种组合见资金费率作为市场指标。在 Genesis API 中,/funding/rates 返回每家交易所的费率,同样在所有套餐中提供:每个结算周期的费率(funding_pct)和归一化到 8 小时的费率(funding_8h_pct)。资金费率 endpoint 和已结算的资金费率历史见资金费率 API,字段说明见文档。
Python:价格上涨时 OI 一小时增长超过 5%
脚本一次调用拉取完整快照,保留总 OI 一小时内增长超过 5%、价格同时上涨、且 OI 本身不低于 500 万美元的币。对每个币,它会打印分交易所明细:该交易所的 OI 占比,以及一小时内的 OI 和价格变化。密钥取自环境变量 GENESIS_API_KEY;遇到 429 和 503 时,脚本等待 Retry-After 秒后重试。
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
MIN_OI_USD = 5_000_000 # OI 很小时,一个头寸就能让它大幅波动
def get(path, **params):
while True:
r = requests.get(API + path, headers=HEADERS,
params=params, timeout=15)
if r.status_code in (429, 503): # 限流或数据正在重建
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
return r.json()["data"]
def passes(t):
oi, px = t.get("oi_change_1h"), t.get("price_change_1h")
if oi is None or px is None:
return False
return (t.get("oi_usd") or 0) >= MIN_OI_USD and oi > 5 and px > 0
def pct(v):
return "n/a" if v is None else f"{v:+.1f}%"
hits = [r for r in get("/market/open-interest") if passes(r["total"])]
for row in hits:
t = row["total"]
print(f"{row['coin']}:1 小时 OI {pct(t['oi_change_1h'])},"
f"价格 {pct(t['price_change_1h'])},"
f"合计 ${t['oi_usd'] / 1e6:.1f}M")
exs = sorted(row["exchanges"].items(), reverse=True,
key=lambda kv: kv[1].get("oi_usd") or 0)
for name, m in exs:
share = (m.get("oi_usd") or 0) / t["oi_usd"] * 100
print(f" {name:<8} 占比 {share:4.1f}%,"
f"OI {pct(m.get('oi_change_1h'))},"
f"价格 {pct(m.get('price_change_1h'))}")
币种 XYZ 的示例输出(仅作说明):一小时内 OI +6.2%,价格 +3.0%,总 OI 为 4,810 万美元。
| 交易所 | OI 占比 | OI 1 小时 | 价格 1 小时 |
|---|---|---|---|
| Binance | 46.2% | +8.0% | +3.0% |
| ByBit | 27.0% | +5.0% | +3.1% |
| OKX | 17.5% | +2.0% | +2.9% |
| Bitget | 9.3% | +9.0% | +3.2% |
增长是普遍的:四家交易所的 OI 都上升了,其中三家上升 5% 或更多。如果同样的 +6.2% 只来自一小时前持有该币 10% OI 的某一家交易所,那么它的 OI 必须增长 62%:0.10 × 62 = 6.2。单一交易所上的突增更常意味着某个大户,据此对市场下结论还为时过早。
第二部分加入资金费率:对所有币调用一次 /funding/rates,并对找到的每个币给出各交易所中最低和最高的 8 小时费率,以及有多少家交易所的费率为正。
# 每家交易所的资金费率:一次调用覆盖所有币
rates = {row["coin"]: row["exchanges"]
for row in get("/funding/rates")}
for row in hits:
fr = sorted((e["funding_8h_pct"], e["exchange"])
for e in rates.get(row["coin"], [])
if e.get("funding_8h_pct") is not None)
if not fr:
print(f"{row['coin']}:没有资金费率")
continue
(lo, lo_ex), (hi, hi_ex) = fr[0], fr[-1]
plus = sum(1 for rate, _ in fr if rate > 0)
print(f"{row['coin']}:8 小时资金费率 {lo:+.4f}%({lo_ex})"
f"至 {hi:+.4f}%({hi_ex}),{len(fr)} 家中有 {plus} 家为正")
脚本发起两次调用。每分钟运行一次,30 天内就是 2 × 60 × 24 × 30 = 86,400 次调用,不到 Trial 套餐 50 万配额的五分之一。若要循环轮询而不在未变化的数据上消耗配额,请加上 ETag 和 If-None-Match:方法见如何轮询 API 而不触及限额,配额和每秒请求数见 Genesis API 限额指南。
注意事项:什么会扭曲持仓量
- 各交易所口径不同。Bybit 有两个相差一倍的 OI 字段,OKX 的
oi以交易所设定面值的合约张数计,同一个币的代码也可能不同:PEPE 在一家交易所,1000PEPE 在另一家。跨交易所比较时,百分比变化更稳妥:只要每家交易所前后两次读数的统计方式一致,它就不依赖单位。 - 美元数值依赖价格。每家交易所的
oi_usd是其以币计的 OI 乘以自己的价格,所以在剧烈波动时,即使头寸没有变动,美元 OI 也会变化。 - 强平会造成尖峰。在连环强平中,交易所会强制平掉头寸:价格剧烈波动的同时,OI 在几分钟内下降几个百分点。
oi_change_5m骤降并伴随price_change_5m的剧烈波动,是强平的典型特征。 - OI 很小会放大百分比。对于 OI 只有几十万美元的币,一个头寸就能使其变动几十个百分点,对
total.oi_usd设置阈值可以滤掉这类噪声。 - 总量取决于包含了哪些交易所。如果某个币在又一家交易所上线合约,总 OI 会因新增的场所而增长,而其他交易所并没有变化。请对照
exchanges明细核对总量的增长。
不写代码也可以使用同样的数据:网站上的 OI 追踪表格,其列、筛选和图表见指南。API 套餐的配额和价格见 Genesis API 价格页面。
常见问题
持仓量与成交量有什么区别?
成交量是一段时间内成交的总和;持仓量是此刻仍未平仓的头寸。每笔成交都计入成交量,但只有当双方都开仓或都平仓时,它才会改变 OI。成交量高而 OI 持平,说明头寸大多只是在换手。/market/open-interest 响应中同时有这两个数字:volume_24h 和 oi_usd。
在哪里可以获取持仓量历史?
Genesis API 没有历史:该 endpoint 返回当前快照以及 5、15、30 分钟和 1 小时内的变化,所以长序列需要你自己保存响应来构建。交易所在各自的 API 中提供历史:Binance 为最近一个月,Bybit 步长从 5 分钟到一天,OKX 为最近 1,440 条记录。在网站上,OI 追踪中的图表按钮在网站的 Pro 套餐中会打开 OI 图表。
Genesis API 中的 OI 数据多久更新一次?
新鲜度取决于 API 套餐:Trial 为 60 秒,Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒。快照的构建时间在 meta.updated_at 中,你所用套餐的延迟在 meta.freshness_sec 中。轮询得比这更快没有收益,而配合 If-None-Match,未变化的快照会以 304 返回,不消耗你的配额。
持仓量上升而价格下跌意味着什么?
通常是新的空单在开仓,或有人在逆势买入多单。如果同时资金费率转负,空头还要向多头付费来持有头寸。此时一轮急剧的向上反转可能迫使空头平仓,并加速上涨。