用 Tushare fut_holding 接口获取期货每日成交持仓排名Vibe-Trading 中的完整实战指南【免费下载链接】Vibe-TradingVibe-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之前需要满足两个条件积分门槛用户需要至少2000 积分才可以调取该接口。积分可通过 Tushare 官方渠道获取具体规则见接口文档中的积分获取办法说明。Token 配置注册 Tushare 账号后获取 token安装依赖并配置环境变量pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple export TUSHARE_TOKENyour_tokenfut_holding的限量规则为单次最大返回 2000 条记录总量不限制。这意味着长历史数据需要通过日期分段循环拉取。三、输入参数详解fut_holding支持四个输入参数均为可选名称类型必选描述trade_datestrN交易日期trade_date / symbol 至少输入一个参数symbolstrN合约或产品代码start_datestrN开始日期YYYYMMDD 格式下同end_datestrN结束日期exchangestrN交易所代码参数使用要点trade_date 与 symbol 至少输入一个按日期查询可一次取回当日全市场排名按symbol查询则聚焦单一品种。start_date / end_date用于批量拉取一段日期区间内的数据配合 2000 条/次的限量做循环翻页。exchange可指定交易所过滤常见取值为DCE大商所、CZCE郑商所、SHFE上期所、CFFEX中金所、INE上海国际能源交易中心、GFEX广期所。交易所代码清单与 合约信息 文档中的fut_basic接口保持一致。四、输出参数详解接口返回的每条记录包含以下字段名称类型默认显示描述trade_datestrY交易日期symbolstrY合约代码或类型brokerstrY期货公司会员简称volintY成交量vol_chgintY成交量变化long_hldintY持买仓量long_chgintY持买仓量变化short_hldintY持卖仓量short_chgintY持卖仓量变化exchangestrN交易所字段解读与注意事项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_date20181113, symbolC1905, exchangeDCE)更完整的生产级写法可显式传入 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_date20181113, symbolC, exchangeDCE) print(df) # 按日期区间批量拉取单次上限 2000 条超限需分段 df pro.fut_holding(start_date20181101, end_date20181113, symbolC) print(df)在调用前建议先通过 合约信息 的fut_basic接口确认品种与合约代码再决定以symbol还是trade_date作为查询主键# 查询大商所普通合约确认玉米品种代码 df pro.fut_basic(exchangeDCE, fut_type1, fieldsts_code,symbol,name,list_date,delist_date)六、返回数据示例解读以文档中的真实数据为例2018-11-13大商所玉米Ctrade_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从这几行可以读出三层信息净头寸国投安信持卖仓量105797显著大于持买仓量84537净空约 2.1 万手而东证期货多空基本均衡15432 vs 14281。增减方向国投安信当日多空同时增仓long_chg4253short_chg7326空头加仓更快方向偏空中粮期货多头加仓3705而空头减仓-2658方向偏多。数据稀疏性表中大量席位仅出现在成交量或单边持仓中如中信建投只有成交量与多头持仓short_hld为 NaN说明这类席位要么以日内交易为主、要么只披露了单边代理数据统计多空合计时必须剔除 NaN。七、与期货数据族接口联动构建席位分析流程fut_holding不是孤立的接口Vibe-Trading 的 Tushare 技能文档将期货数据整理为一个完整的数据族见 SKILL.md 中期货数据分类接口文档用途fut_basic合约信息合约列表、品种代码、上市/退市日期fut_daily日线行情行情 OHLC、结算价、持仓量oifut_holding本文会员席位成交持仓排名fut_wsr仓单日报仓库/厂库仓单变化fut_settle每日结算参数交易与交割费率等结算参数一个典型的席位研究流程可以这样组织import tushare as ts pro ts.pro_api() # 1. 定位品种合约fut_basic basic pro.fut_basic(exchangeDCE, fut_type1, fieldsts_code,symbol,name) # 2. 拉取某日全市场持仓排名fut_holding holding pro.fut_holding(trade_date20241231) # 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, ascendingFalse).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 积分门槛并核对该接口在当前账号权限下是否可用。九、常见问题与注意事项权限报错提示积分不足或permission denied时先检查账号积分是否达到 2000再检查TUSHARE_TOKEN是否已正确配置且非占位符。返回为空确认trade_date是否为交易日周末与节假日无数据symbol使用品种代码如C而非带后缀的ts_codeexchange取值是否与交易所代码表一致。单次超限2000 条/次的限制意味着按trade_date全市场查询可能一次取不完需要配合start_date/end_date或逐日循环分段拉取。NaN 处理席位数据天然稀疏聚合前必须决定 NaN 的语义不参与交易 vs 未披露避免误算多空净头寸。粒度差异fut_holding的symbol是品种级若需要合约级持仓需结合fut_daily的oi与ts_code自行对齐口径。十、总结fut_holding是理解国内期货市场资金结构的入口级接口通过它你可以还原每个交易日、每个品种上各家期货公司席位的成交与多空持仓全貌进而支撑主力席位追踪、多空力量对比、资金流向研判等量化研究。结合 Vibe-Trading 仓库中 Tushare 技能的完整数据族合约信息、日线行情、仓单日报、结算参数与数据源降级模式你可以把这套席位数据接入自己的回测与研究流水线形成可复用的期货多空监测模块。延伸阅读Tushare 技能总览 日线行情 合约信息 仓单日报 数据源注册与降级链 Tushare 降级适配器【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考