企业官网建设流程全解析

用 Tushare fut_holding 接口获取期货每日成交持仓排名：Vibe-Trading 中的完整实战指南

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

导读

本文以 每日持仓排名 文档为骨架，系统讲解 Tusharefut_holding接口的权限要求、输入输出参数、调用方式与数据解读方法。读完本文，你将掌握如何拉取国内期货市场各期货公司会员的逐日成交量、持买仓量与持卖仓量数据，并能够将其与合约信息、日线行情、仓单日报等接口联动，构建多空力量对比、主力席位追踪等量化研究流程。文中同时结合 Vibe-Trading 仓库中 Tushare 数据源的实际接入方式，说明这套数据在个人交易 Agent 中的落点。

一、接口定位与业务含义

期货交易所每日盘后都会披露会员（期货公司）的成交与持仓明细，这是公开数据中最能反映"谁在买卖"的信息之一。fut_holding接口返回的正是这一排名数据，其每行记录代表：

• 某一交易日、某一合约品种上，某一家期货公司席位的成交量与成交量变化；
• 该席位在买方向（多单）与卖方向（空单）上的持仓量与持仓量变化。

通过观察持买仓量（long_hld）与持卖仓量（short_hld）的对比，可以推断期货公司所代理客户的多空分歧；而long_chg/short_chg则揭示了席位在一日之内多空仓位的增减方向，是识别资金动向的核心抓手。

在 SKILL.md 的技能定义中，Tushare 被定位为"财经数据接口包"，覆盖股票、基金、期货、数字货币等行情数据与基本面数据。fut_holding正是该技能中"期货数据"分类下的接口之一，接口 ID 为 139。

二、调用前置条件

调用fut_holding之前需要满足两个条件：

1. 积分门槛：用户需要至少2000 积分才可以调取该接口。积分可通过 Tushare 官方渠道获取，具体规则见接口文档中的"积分获取办法"说明。
2. Token 配置：注册 Tushare 账号后获取 token，安装依赖并配置环境变量：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple export TUSHARE_TOKEN=your_token

fut_holding的限量规则为：单次最大返回 2000 条记录，总量不限制。这意味着长历史数据需要通过日期分段循环拉取。

三、输入参数详解

fut_holding支持四个输入参数，均为可选：

参数使用要点：

• trade_date 与 symbol 至少输入一个：按日期查询可一次取回当日全市场排名；按symbol查询则聚焦单一品种。
• start_date / end_date：用于批量拉取一段日期区间内的数据，配合 2000 条/次的限量做循环翻页。
• exchange：可指定交易所过滤，常见取值为DCE（大商所）、CZCE（郑商所）、SHFE（上期所）、CFFEX（中金所）、INE（上海国际能源交易中心）、GFEX（广期所）。交易所代码清单与 合约信息 文档中的fut_basic接口保持一致。

四、输出参数详解

接口返回的每条记录包含以下字段：

字段解读与注意事项：

• vol 与 vol_chg：当日成交量及较上一交易日的变化，单位通常为手。
• long_hld / short_hld：持买（多单）与持卖（空单）持仓量，其相对大小直接决定席位净头寸方向。
• long_chg / short_chg：多空持仓的当日增减，正值为加仓、负值为减仓。
• 缺失值 NaN：从数据示例可见，并非每个席位在每个字段都有值。例如只有成交量、没有持仓的席位（纯日内交易），或只有单边持仓的席位。统计时务必使用dropna或对缺失值单独处理，不能当作 0 参与计算。
• symbol 是品种级代码：示例中返回的symbol为C（玉米）而非具体合约C1905，即该接口按品种聚合排名，这一点与fut_daily按合约代码ts_code返回行情的粒度不同。

五、接口调用示例

官方示例代码如下：

pro = ts.pro_api() df = pro.fut_holding(trade_date='20181113', symbol='C1905', exchange='DCE')

更完整的生产级写法，可显式传入 token 并指定字段：

import tushare as ts # 方式一：环境变量中的 token（与 Vibe-Trading 的 TUSHARE_TOKEN 配置一致） pro = ts.pro_api() # 方式二：显式指定 token # pro = ts.pro_api('your_token') # 按交易日 + 品种 + 交易所拉取玉米主力相关排名 df = pro.fut_holding(trade_date='20181113', symbol='C', exchange='DCE') print(df) # 按日期区间批量拉取，单次上限 2000 条，超限需分段 df = pro.fut_holding(start_date='20181101', end_date='20181113', symbol='C') print(df)

在调用前建议先通过 合约信息 的fut_basic接口确认品种与合约代码，再决定以symbol还是trade_date作为查询主键：

# 查询大商所普通合约，确认玉米品种代码 df = pro.fut_basic(exchange='DCE', fut_type='1', fields='ts_code,symbol,name,list_date,delist_date')

六、返回数据示例解读

以文档中的真实数据为例（2018-11-13，大商所玉米C）：

trade_date symbol broker vol vol_chg long_hld long_chg short_hld short_chg 20181113 C 东证期货 37161.0 -6435.0 15432.0 1837.0 14281.0 -384.0 20181113 C 国投安信 49251.0 -43610.0 84537.0 4253.0 105797.0 7326.0 20181113 C 中粮期货 12331.0 -5430.0 45350.0 3705.0 70184.0 -2658.0

从这几行可以读出三层信息：

1. 净头寸：国投安信持卖仓量（105797）显著大于持买仓量（84537），净空约 2.1 万手；而东证期货多空基本均衡（15432 vs 14281）。
2. 增减方向：国投安信当日多空同时增仓（long_chg=+4253，short_chg=+7326），空头加仓更快，方向偏空；中粮期货多头加仓（+3705）而空头减仓（-2658），方向偏多。
3. 数据稀疏性：表中大量席位仅出现在成交量或单边持仓中（如中信建投只有成交量与多头持仓，short_hld为 NaN），说明这类席位要么以日内交易为主、要么只披露了单边代理数据，统计多空合计时必须剔除 NaN。

七、与期货数据族接口联动：构建席位分析流程

fut_holding不是孤立的接口，Vibe-Trading 的 Tushare 技能文档将期货数据整理为一个完整的数据族（见 SKILL.md 中"期货数据"分类）：

一个典型的席位研究流程可以这样组织：

import tushare as ts pro = ts.pro_api() # 1. 定位品种合约（fut_basic） basic = pro.fut_basic(exchange='DCE', fut_type='1', fields='ts_code,symbol,name') # 2. 拉取某日全市场持仓排名（fut_holding） holding = pro.fut_holding(trade_date='20241231') # 3. 计算每个品种席位层面的多空力量 holding = holding.dropna(subset=['long_hld', 'short_hld']) holding['net'] = holding['long_hld'] - holding['short_hld'] # 4. 按品种汇总多头/空头前 5 席位 top_long = holding.sort_values('long_hld', ascending=False).groupby('symbol').head(5) print(top_long[['symbol', 'broker', 'long_hld', 'long_chg']])

若需将排名数据与价格行情对照，可同时调用fut_daily获取当日结算价与总持仓量oi，形成"价格 + 总持仓 + 席位结构"的立体视图；需要核对实物库存压力时，再叠加fut_wsr的仓单增减数据。

八、在 Vibe-Trading 仓库中的落点与配置

Tushare 在 Vibe-Trading 中承担着"中国市场数据源"的职责，主要体现在以下源码位置：

• 数据源注册：registry.py 将tushare注册为合法 loader（第 34 行），并在 A 股、基金、宏观等市场的数据源链（fallback chain）中占据一席之地；同时该文件也明确注释：Tushare 对部分期货端点支持有限，接入期货数据时应结合其它源交叉验证。
• Token 配置：仓库统一通过环境配置读取tushare_token，占位符为""或"your-tushare-token"，未配置时直接判定不可用（见 tushare_fallbacks.py 第 15-30 行、tushare.py 第 85-145 行）。
• 降级适配模式：tushare_fallbacks.py 展示了"主源不可用、以 Tushare 兜底"的适配器写法：通过_pro_api()初始化接口、_records()将 DataFrame 归一化为记录列表、_compact_date()将YYYY-MM-DD规整为YYYYMMDD。如果你要在自己的研究流程里接入fut_holding，完全可以复用这套"日期规整 + 记录归一化 + 缺失值转 None"的模式。

需要特别说明的是，仓库当前对 Tushare 的期货端点（含fut_holding）并无内置封装，本文中的持仓排名调用属于基于技能文档的自主脚本实践，请在本地运行前确认自己的 Tushare 账号已满足 2000 积分门槛，并核对该接口在当前账号权限下是否可用。

九、常见问题与注意事项

1. 权限报错：提示积分不足或"permission denied"时，先检查账号积分是否达到 2000，再检查TUSHARE_TOKEN是否已正确配置且非占位符。
2. 返回为空：确认trade_date是否为交易日（周末与节假日无数据）；symbol使用品种代码（如C）而非带后缀的ts_code；exchange取值是否与交易所代码表一致。
3. 单次超限：2000 条/次的限制意味着按trade_date全市场查询可能一次取不完，需要配合start_date/end_date或逐日循环分段拉取。
4. NaN 处理：席位数据天然稀疏，聚合前必须决定 NaN 的语义（不参与交易 vs 未披露），避免误算多空净头寸。
5. 粒度差异：fut_holding的symbol是品种级，若需要合约级持仓需结合fut_daily的oi与ts_code自行对齐口径。

十、总结

fut_holding是理解国内期货市场资金结构的入口级接口：通过它，你可以还原每个交易日、每个品种上各家期货公司席位的成交与多空持仓全貌，进而支撑主力席位追踪、多空力量对比、资金流向研判等量化研究。结合 Vibe-Trading 仓库中 Tushare 技能的完整数据族（合约信息、日线行情、仓单日报、结算参数）与数据源降级模式，你可以把这套席位数据接入自己的回测与研究流水线，形成可复用的期货多空监测模块。

延伸阅读：Tushare 技能总览 ｜ 日线行情 ｜ 合约信息 ｜ 仓单日报 ｜ 数据源注册与降级链 ｜ Tushare 降级适配器

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading