想拿 BTCUSDT 两个月前的持仓量做对照,币安的 /futures/data/openInterestHist 给不了:接口文档写明,这个接口只提供最近 1 个月的数据。今天能做的,是把接口里还在的这一个月先存下来,之后每天定时取一次接着往后存,一个月以后你手上就有了接口本身给不出的长历史。

要准备的东西不多:一台能定时运行脚本的电脑或服务器,一个 CSV 文件或一张数据库表。接口属于公开行情数据,按 IP 计权重,每天调几次远远碰不到限频。

1. 持仓量和多空比接口最多能往回查多久。

持仓量所在的这组统计类接口都有回查上限,存档时一起存省事。/fapi/v1/openInterest 只给当前值,放在最后一行作对照。

来源:币安 U 本位合约 REST API 文档 · Market Data,各项取值以 2026 年 11 月 10 日的文档为准
接口数据可查范围单次条数上限(默认)权重 / 限频timestamp 含义
/futures/data/openInterestHist持仓量统计最近 1 个月500(30)0 / 每 IP 每 5 分钟 1000 次周期结束时间
/futures/data/globalLongShortAccountRatio多空账户比最近 30 天500(30)0 / 每 IP 每 5 分钟 1000 次周期结束时间
/futures/data/takerlongshortRatio主动买卖量最近 30 天500(30)0 / 每 IP 每 5 分钟 1000 次周期开始时间
/futures/data/basis期现基差最近 30 天500(30)0周期开始时间
/fapi/v1/openInterest当前持仓量只有当前值—1字段名为 time

openInterestHist 的文档写的是「1 个月」,多空比、主动买卖量和基差写的是「30 天」。补数时按 30 天准备,不会踩到边界。

持仓量和多空比的 timestamp 是周期的结束时间,主动买卖量和基差的 timestamp 是周期的开始时间。两类数据要按时间对齐时,先把其中一边挪一个周期,不然同一行里的持仓量和买卖量其实差了一格。

period 参数可选 5m、15m、30m、1h、2h、4h、6h、12h 等档位。不传 startTime 和 endTime 时,接口返回最近的数据。

2. 第一次运行时先把接口里的一个月补齐。

📋 分段算例 · 按 30 天、单次最多 500 条计 · 按接口文档参数可复算

一次请求最多 500 条,所以一个月要分几次取,取决于你选的 period。按 30 天算:

period30 天的条数需要的请求次数
12h30 × 2 = 601
1h30 × 24 = 7202(500 + 220)
5m30 × 288 = 8,64018(8,640 ÷ 500 向上取整)

选哪一档看你以后怎么用:写周报、看日级别趋势,1h 足够;要研究盘中某一小时的仓位变化,才需要 5m。档位越细,补齐和续存的请求越多,但离限频还差得远。

具体步骤:

  1. 算时间戳。startTime 和 endTime 都是毫秒时间戳(13 位数字),拿当前时间减 30 天作为第一段的 startTime。
  2. 发第一段请求,例如 https://fapi.binance.com/futures/data/openInterestHist?symbol=BTCUSDT&period=1h&limit=500&startTime=…&endTime=…,endTime 设成 startTime 往后 500 个周期。
  3. 拿返回结果里最后一条的 timestamp,作为下一段的起点,再发一次,直到追到当前时间。
  4. 每条记录存下面这几个字段,再加一列你自己写入的抓取时间。
字段文档里的说明存的时候注意什么
symbol交易对多个合约存同一张表时必须有
sumOpenInteresttotal open interest(持仓总量)是数量,价格涨跌不改变它
sumOpenInterestValuetotal open interest value(持仓总价值)会随价格变动,和上一列分开存
CMCCirculatingSupplycirculating supply provided by CMC(CMC 提供的流通量)想算持仓占流通量的比例时用
timestampEnd time of the period, in milliseconds(周期结束时间,毫秒)和 symbol、period 一起做唯一键

用 CSV 的话,第一行可以写成 symbol,period,timestamp,sumOpenInterest,sumOpenInterestValue,CMCCirculatingSupply,fetched_at,之后每行一条记录;接口返回的数值是字符串,写入时按原样保留小数位,别先转成浮点数再四舍五入。

补数时遇到下面的情况,这样处理:

  • 返回的条数比上表算出来的少:文档说明没有成交的周期不会有记录,这些空缺不会事后补上。脚本别把它当成请求失败去重试,也别自己插值填满。
  • 返回的是报错而不是数组:先看 startTime 是不是早于一个月前,再看时间戳是不是误用了 10 位的秒,最后核对 period 是否在可选档位里。
  • 两段数据的衔接处出现重复记录:写入前按唯一键去重,保留一条即可。

3. 之后每天跑一次,漏跑几天也能补回来。

补齐以后,每天固定一个时间请求一次 period=1h&limit=24,不带 startTime 和 endTime,拿到的就是最近 24 个小时周期。写入前同样按唯一键去重,和前一天的末尾重叠的那条会被去掉。

这样做的好处是容错大。脚本停了几天、服务器重启没人发现,只要在一个月内发现,就能用第 2 节的分段方法从表里最后一条 timestamp 接着补。超过一个月才发现,中间那段从币安接口就拿不回来了。给脚本加一个检查:表里最新一条的 timestamp 落后当前时间超过 2 天,就发一封邮件或一条消息提醒自己。

如果你还想要某个时点的即时持仓,GET /fapi/v1/openInterest?symbol=BTCUSDT 返回 openInterest 和 time 两项,只有数量,没有价值字段。它适合在盘中看一眼当前值;写进历史表时,还是以 openInterestHist 的 sumOpenInterest 为准,两个接口的数不要混在同一列。

多空账户比和主动买卖量同样有回查上限,接口参数写法和持仓量一样,放进同一个定时任务里顺手存掉,省得以后再遇到同样的问题。存进同一张表时,每种数据单独记一列 metric,别靠列的位置区分。

4. 一个月以前的持仓量只能去第三方数据站找。

币安接口拿不到的那一段,只能去第三方数据站找;各站免费层能看多长、要不要付费,参考 4 个免费指标聚合站对比。拿来之前确认两件事:它显示的是币安单家的持仓量,还是多家交易所加总;它的时间点是周期开始还是结束。

这两项和你自己存的数据不一致,接到同一条曲线上就会出现一个看起来像行情、其实是换了数据源的台阶。稳妥的做法是在表里加一列 source,币安接口存的记 binance_api,第三方补进来的记站名,画图时两段用不同颜色。

5. 存档脚本动手写之前再核对一下。

调 openInterestHist 需要 API Key 吗?

文档给这个接口列出的只有 symbol、period、limit、startTime、endTime 五个查询参数,没有请求头要求;同一页里需要 Key 的接口,比如 historicalTrades,会单独标出 X-MBX-APIKEY 请求头。它按 IP 计权重,写定时任务时注意别超过每 5 分钟的限频。

该存 sumOpenInterest 还是 sumOpenInterestValue?

两个字段都存下来。sumOpenInterest 是持仓总量,不受价格影响,适合看某个币的仓位在增加还是减少;sumOpenInterestValue 是持仓总价值,价格涨跌会带着它变,适合比较不同币种的仓位规模。写周报时别把两个数放进同一列比较。


下一步该看什么。