Genesis Arbitrage

Genesis Arbitrage · · 阅读约 21 分钟

持仓量 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。以下是官方文档的说明:

交易所当前 OIOI 历史注意事项
BinanceGET /fapi/v1/openInterest,每次请求一个 symbolGET /futures/data/openInterestHist历史只覆盖最近一个月
BybitGET /v5/market/tickers,一次请求返回所有交易对GET /v5/market/open-interest,步长从 5min 到 1dopenInterest 统计双方,singleOpenInterest 统计单方
OKXGET /api/v5/public/open-interestGET /api/v5/rubik/stat/contracts/open-interest-historyoi 以合约张数计,oiCcy 以币数计,oiUsd 以美元计
HyperliquidPOST /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_24h24 小时成交量,USD
total.oi_change_5m/15m/30m/1hOI 在 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 小时
Binance46.2%+8.0%+3.0%
ByBit27.0%+5.0%+3.1%
OKX17.5%+2.0%+2.9%
Bitget9.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 限额指南。

注意事项:什么会扭曲持仓量

不写代码也可以使用同样的数据:网站上的 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 返回,不消耗你的配额。

持仓量上升而价格下跌意味着什么?

通常是新的空单在开仓,或有人在逆势买入多单。如果同时资金费率转负,空头还要向多头付费来持有头寸。此时一轮急剧的向上反转可能迫使空头平仓,并加速上涨。