想拿 BTCUSDT 两个月前的持仓量做对照,币安的 /futures/data/openInterestHist 给不了:接口文档写明,这个接口只提供最近 1 个月的数据。今天能做的,是把接口里还在的这一个月先存下来,之后每天定时取一次接着往后存,一个月以后你手上就有了接口本身给不出的长历史。
要准备的东西不多:一台能定时运行脚本的电脑或服务器,一个 CSV 文件或一张数据库表。接口属于公开行情数据,按 IP 计权重,每天调几次远远碰不到限频。
1. 持仓量和多空比接口最多能往回查多久。
持仓量所在的这组统计类接口都有回查上限,存档时一起存省事。/fapi/v1/openInterest 只给当前值,放在最后一行作对照。
| 接口 | 数据 | 可查范围 | 单次条数上限(默认) | 权重 / 限频 | 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. 第一次运行时先把接口里的一个月补齐。
一次请求最多 500 条,所以一个月要分几次取,取决于你选的 period。按 30 天算:
| period | 30 天的条数 | 需要的请求次数 |
|---|---|---|
| 12h | 30 × 2 = 60 | 1 |
| 1h | 30 × 24 = 720 | 2(500 + 220) |
| 5m | 30 × 288 = 8,640 | 18(8,640 ÷ 500 向上取整) |
选哪一档看你以后怎么用:写周报、看日级别趋势,1h 足够;要研究盘中某一小时的仓位变化,才需要 5m。档位越细,补齐和续存的请求越多,但离限频还差得远。
具体步骤:
- 算时间戳。startTime 和 endTime 都是毫秒时间戳(13 位数字),拿当前时间减 30 天作为第一段的 startTime。
- 发第一段请求,例如
https://fapi.binance.com/futures/data/openInterestHist?symbol=BTCUSDT&period=1h&limit=500&startTime=…&endTime=…,endTime 设成 startTime 往后 500 个周期。 - 拿返回结果里最后一条的 timestamp,作为下一段的起点,再发一次,直到追到当前时间。
- 每条记录存下面这几个字段,再加一列你自己写入的抓取时间。
| 字段 | 文档里的说明 | 存的时候注意什么 |
|---|---|---|
symbol | 交易对 | 多个合约存同一张表时必须有 |
sumOpenInterest | total open interest(持仓总量) | 是数量,价格涨跌不改变它 |
sumOpenInterestValue | total open interest value(持仓总价值) | 会随价格变动,和上一列分开存 |
CMCCirculatingSupply | circulating supply provided by CMC(CMC 提供的流通量) | 想算持仓占流通量的比例时用 |
timestamp | End 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 是持仓总价值,价格涨跌会带着它变,适合比较不同币种的仓位规模。写周报时别把两个数放进同一列比较。
下一步该看什么。
- 持仓量 Open Interest 入门到实战 — 存下来的数怎么读。
- 多空比是反指标还是真信号?实战手册 — 同一个定时任务里的另一组数据。
- 合约主动买卖量(Taker 买卖比)怎么读 — 主动买卖量存下来以后怎么读。
- 期现基差怎么读 — 基差接口也能放进同一个存档任务。
- 4 个免费指标聚合站对比 — 一个月以前的数据去哪找。
- 期权 PCR 实时看板:BTC / ETH 看跌看涨比与最大痛点 — 期权这边的持仓量,按到期日看 Put / Call 分布。