Tushare ft_limit 期货合约涨跌停价格接口详解：在 Vibe-Trading 中获取每日涨跌停价与最低保证金率-平芜编程栈

Tushare ft_limit 期货合约涨跌停价格接口详解：在 Vibe-Trading 中获取每日涨跌停价与最低保证金率

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

本篇技术指南以 Vibe-Trading 仓库中 Tushare 技能参考文档期货合约涨跌停价格为核心，系统讲解ft_limit接口的输入/输出参数、调用示例、数据字段含义，并结合仓库源码（Tushare 加载器、国内期货回测引擎）深入说明涨跌停价格、保证金率在期货策略回测中的底层作用与落地方式。读完本文，你将掌握：如何通过 Tushare 快速批量获取全部期货合约每日涨跌停价格与最低保证金率、如何按合约/品种/交易所/日期灵活筛选，以及这些"盘前数据"在涨跌停封板过滤、保证金与杠杆测算等实战场景中的使用方法。

接口概览：ft_limit 能提供什么

ft_limit（Futures Limit）是 Tushare 提供的期货涨跌停价格接口，核心能力是：

获取所有期货合约每天的涨跌停价格（涨停价up_limit、跌停价down_limit）；
同时输出最低交易保证金率（m_ratio，单位 %）；
历史数据开始于 2005 年，覆盖 CFFEX / SHFE / DCE / ZCE / INE / GFEX 等国内期货交易所的合约；
单次最大获取 4000 行数据，可通过日期、合约代码等参数循环拉取全部历史；
调用门槛：用户积分达到 5000 分方可调取（积分可通过 Tushare 官方积分机制获取，具体以官方文档说明为准）。

从仓库的技能清单看，该接口在 SKILL.md 中被注册为编号 368 的数据接口（ft_limit），归入"期货数据"分类，与fut_daily（日线行情）、fut_settle（每日结算参数）、fut_mapping（期货主力与连续合约）等接口构成完整的期货数据体系。ft_limit的典型定位是"盘前"数据——交易所会在每个交易日开盘前公布当日涨跌停价格与保证金要求，这正是它区别于收盘后生成的日线行情（fut_daily）的关键时间属性。

前置准备：环境、Token 与积分

按照 SKILL.md 的快速上手说明，调用ft_limit前需要完成以下准备：

安装 tushare 依赖包（推荐 Python 3.7+ 环境，可从清华 PyPI 镜像安装）：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple

注册 Tushare 并获取 token，配置为环境变量：

export TUSHARE_TOKEN=your_token

确认账户积分达到 5000 分。若积分不足，接口会返回权限类错误，无法正常取数。
初始化 Pro API 实例。仓库 tushare.py 加载器中的初始化方式可作为参考——它从配置读取TUSHARE_TOKEN，并校验 token 是否为占位符（TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}）：

import os import tushare as ts token = os.getenv('TUSHARE_TOKEN') or ts.get_token() pro = ts.pro_api(token)

输入参数详解

ft_limit共支持 6 个输入参数，全部可选（标 N），但实际使用时需至少提供一个筛选维度（如日期或合约代码），否则会返回全量数据。

名称	类型	必选	描述
ts_code	str	N	合约代码
trade_date	str	N	交易日期（格式：YYYYMMDD）
start_date	str	N	开始日期（格式：YYYYMMDD）
end_date	str	N	结束日期（格式：YYYYMMDD）
cont	str	N	合约代码（品种代码，例如`cont='CU'`）
exchange	str	N	交易所代码（例如`exchange='DCE'`）

参数使用要点：

ts_code与cont的区分：ts_code是具体合约代码（如A2503.DCE、ZN2509.SHF），对应单一月份合约；cont是品种代码（如CU铜、A豆一、ZN沪锌），一次可拉取该品种下全部月份合约的涨跌停价。
trade_date/start_date/end_date：日期统一使用YYYYMMDD格式（如20250213）。trade_date精确到单日；start_date/end_date用于日期区间查询。
exchange交易所代码：常见取值包括DCE（大连商品交易所）、SHFE（上海期货交易所）、CFFEX（中国金融期货交易所）、ZCE（郑州商品交易所）、INE（上海国际能源交易中心）、GFEX（广州期货交易所）。从仓库 china_futures.py 的模块注释可以看出，国内期货市场正是由这六家交易所构成。
组合筛选：各参数可以组合使用，例如"DCE 交易所某日的全部合约涨跌停价"可同时传trade_date与exchange。

输出参数详解

接口每次返回一个 pandas DataFrame，包含 8 个字段：

名称	类型	默认显示	描述
trade_date	str	Y	交易日期
ts_code	str	Y	TS 合约代码
name	str	Y	合约名称
up_limit	float	Y	涨停价
down_limit	float	Y	跌停价
m_ratio	float	Y	最低交易保证金率（%）
cont	str	Y	合约代码（品种代码）
exchange	str	Y	交易所代码

字段解读：

ts_code为 Tushare 标准化合约代码，格式为"品种代码+年份+月份+交易所后缀"，例如A2503.DCE表示大商所 2025 年 3 月到期的豆一合约。
up_limit/down_limit为当日涨停价与跌停价。国内期货的涨跌停板价格以前一交易日结算价为基准计算，这一点在仓库 china_futures.py 中有明确体现：self.base_price_fields = ("pre_settle", "pre_close")，并注释"Futures bands come off the previous settlement, not the previous close"（期货涨跌停幅以昨结算价而非昨收盘价为基准）。
m_ratio为最低交易保证金率，单位为 %。例如7.000表示该合约最低保证金比例为 7%。这是期货杠杆的核心变量——保证金率越低，相同资金可撬动的合约名义价值越大。
name为中文合约名称（如"连豆一2503""沪锌2509"），便于人工阅读与展示。

接口调用示例

原文档给出的两个核心调用示例如下：

pro = ts.pro_api() # 获取单日全部期货合约涨跌停价格 df = pro.ft_limit(trade_date='20250213') # 获取单个品种所有合约涨跌停价格 df = pro.ft_limit(cont='CU')

在此基础上，可以扩展出更多实用调用方式：

import tushare as ts pro = ts.pro_api() # 按交易所筛选：获取 2025 年 2 月 13 日大商所全部合约涨跌停价 df_dce = pro.ft_limit(trade_date='20250213', exchange='DCE') # 按具体合约代码查询 df_a2503 = pro.ft_limit(ts_code='A2503.DCE') # 按日期区间查询 df_range = pro.ft_limit(start_date='20250201', end_date='20250213', cont='CU') # 单次最大 4000 行，可循环翻页拉取全历史 import pandas as pd frames = [] dates = pro.trade_cal(exchange='DCE', start_date='20250101', end_date='20250228', is_open='1') for d in dates['cal_date'].tolist(): part = pro.ft_limit(trade_date=d, exchange='DCE') if part is not None and not part.empty: frames.append(part) df_all = pd.concat(frames, ignore_index=True)

说明：由于ft_limit单次最多返回 4000 行，而全市场期货合约数量通常远超此数（原文档样例中仅 DCE + SHFE 两个交易所单日就有近 800 条记录），因此拉取全历史数据时推荐按交易日或交易所循环请求，再使用pd.concat合并结果。交易日历可配合期货数据专题中的交易日历接口获取，避免对非交易日发起无效请求。

数据样例解读

原文档给出了20250213交易日的数据样例：

trade_date ts_code name up_limit down_limit m_ratio cont exchange 0 20250213 A2503.DCE 连豆一2503 4229.000 3751.000 7.000 A DCE 1 20250213 A2505.DCE 连豆一2505 4249.000 3769.000 7.000 A DCE ... 783 20250213 ZN2509.SHF 沪锌2509 24890.000 21635.000 9.000 ZN SHFE 784 20250213 ZN2510.SHF 沪锌2510 24885.000 21630.000 9.000 ZN SHFE

逐字段解读这几行数据：

A2503.DCE / 连豆一2503：大连商品交易所豆一（黄大豆 1 号）2025 年 3 月合约。当日涨停价 4229 元/吨、跌停价 3751 元/吨，最低保证金率 7%。
A2505.DCE / A2507.DCE / A2509.DCE / A2511.DCE：同一品种不同月份到期的合约，涨跌停价随合约价位不同而不同，但保证金率保持一致（同为 7%），说明保证金率按品种设定而非按月份合约。
ZN2509.SHF / 沪锌2509：上海期货交易所沪锌 2025 年 9 月合约。涨停价 24890 元/吨、跌停价 21635 元/吨，最低保证金率 9%。

可以看到，不同品种的保证金率存在明显差异（豆一 7% vs 沪锌 9%），这与品种波动性和交易所风控要求直接相关。仓库 china_futures.py 中维护了一张按品种区分的保证金率表（_MARGIN_RATE），例如"a": 0.08（豆一 8%）、"zn": 0.08（沪锌 8%），与接口返回的"最低保证金率"互为印证——接口数据是交易所实际公布值，引擎表是回测时的近似模拟值。

涨跌停价与保证金率的市场含义

涨跌停价的定价基准

国内期货的涨跌停板价格并非简单按"昨收盘价 × 涨跌幅"计算，而是以前一交易日结算价为基准。结算价由交易所按当日成交加权等方式确定，与收盘价不同。这也是 china_futures.py 将base_price_fields设置为("pre_settle", "pre_close")的原因——期货涨跌停幅度的计算基准与股票（昨收盘）有本质区别。

该引擎注释中还给出了各交易所的价格波动范围规则：

股指期货（CFFEX）：±10%；
国债期货（CFFEX）：±2%（简化）；
商品期货：±3%～8% 不等。

对应到代码中的_PRICE_LIMIT表：IF/IC/IH/IM均为 0.10（±10%），国债T为 0.02、TF0.012、TS0.005、TL0.035，未列出的商品品种默认按 0.05（5%）处理。这与ft_limit返回的每个合约当日具体涨跌停价格形成对照：接口给出的是每个合约的实际价格数值，而引擎表给出的是回测时的品种级涨跌幅比例近似值。

保证金率与杠杆

m_ratio（最低交易保证金率）直接决定期货交易的杠杆倍数：杠杆 ≈ 1 / 保证金率。例如保证金率 7% 对应约 14.3 倍杠杆，9% 对应约 11.1 倍杠杆。在 china_futures.py 中，_leverage_for_symbol正是通过1.0 / self.get_margin_rate(symbol)从保证金率推导杠杆，而_MARGIN_RATE表记录的品种保证金率范围约在 1.5%～12% 之间（如国债TS为 0.015、镍ni为 0.12），与接口文档所述"保证金率随品种不同而不同"完全一致。

涨跌停价在回测中的执行过滤

涨跌停价格在回测引擎中的一个关键用途是执行过滤：当某合约开盘即封在涨停/跌停板上时，买单/卖单可能无法成交。仓库 china_futures.py 的can_execute方法在每次模拟交易时调用_blocked_by_limit（定义于 china_a.py），结合品种涨跌幅比例判断当前 bar 是否处于涨跌停封板状态，从而决定是否允许成交。若使用ft_limit提供的每日精确涨跌停价格替换品种级比例近似值，可以让回测的成交过滤更加贴近真实市场。

在 Vibe-Trading 项目中的落地方式

技能体系中的数据源定位

Vibe-Trading 将 Tushare 封装为 Agent 可调用的数据源技能，入口为 SKILL.md。该技能以references/目录下的 Markdown 文档作为接口参考手册（本文主题文档即其中之一），Agent 通过阅读这些文档获知接口参数、调用方法与返回结构，再编写 Python 代码调取数据。同一技能目录下还提供了股票数据获取示例与基金数据获取示例两个脚本模板。

加载器与限频处理

仓库的 tushare.py 加载器展示了生产级调用 Tushare 的工程细节，对编写ft_limit的循环拉取代码同样适用：

Token 校验：is_available()检查TUSHARE_TOKEN是否已配置且非占位符；
限频识别与退避重试：_RATE_LIMIT_MARKERS通过异常文本中的"每分钟/每天/抽取/频率/rate limit"等标记识别配额拒绝，_call_with_backoff按 5 秒、20 秒、40 秒三级退避等待（_RATE_LIMIT_BACKOFF_SECONDS），等待窗口覆盖 Tushare 每分钟配额周期；
错误隔离：单个合约/日期拉取失败只记录 warning，不中断整体任务——这在按日循环拉取全历史涨跌停价时尤为重要。

需要注意的是，该加载器当前声明支持的 market 为{"a_share", "hk_equity", "fund"}，并明确注释未声明 futures：原因在于期货日线接口fut_daily需要较高的积分门槛，加载器暂未实现对应积分档位，因此期货数据目前更适合通过技能文档 + 独立脚本的方式使用。这一点说明，若要在 Vibe-Trading 中正式接入期货行情，需要账户具备相应积分能力，这也是使用ft_limit时必须满足 5000 积分门槛的相同约束。

与其他期货数据接口的配合

ft_limit通常与期货数据专题中的其他接口配合使用，形成完整的期货策略数据闭环：

日线行情（fut_daily）：提供pre_close、pre_settle、OHLC 等每日行情，可与涨跌停价对照验证价格是否触及板幅；
每日结算参数（fut_settle）：提供交易与交割费率等结算参数；
合约信息（fut_basic）：提供合约列表，用于构造需要遍历的合约代码集合；
期货主力与连续合约（fut_mapping）：用于将逐月合约映射为主力/连续序列。

使用注意事项与最佳实践

积分门槛：ft_limit需要 5000 积分，未达标账户会收到权限错误。使用前请先确认账户积分状态。
单次行数限制：单次最大返回 4000 行。全市场合约数据量大，务必按trade_date（或配合exchange）循环拉取，再用pd.concat合并，避免数据截断。
日期格式：所有日期参数统一使用YYYYMMDD字符串格式（如20250213），不要使用带连字符的YYYY-MM-DD或 datetime 对象。
品种代码大小写：cont参数按品种代码传入，如CU（沪铜）、ZN（沪锌）、A（豆一）。注意不同交易所品种代码风格不同，可从合约信息接口获取权威品种代码列表。
限频控制：Tushare 对积分档位有限频约束。循环取数时建议引入退避重试机制（参考 tushare.py 加载器的_call_with_backoff模式），识别"每分钟/每天"等配额拒绝文本并等待后重试，而不是盲目重发请求。
盘前时间属性：涨跌停价是盘前公布的当日数据，与收盘后生成的日线行情时间语义不同。若用于回测，需注意将当日涨跌停价与当日行情正确对齐，避免引入未来函数（look-ahead bias）。
与引擎参数互为校验：ft_limit返回的实际涨跌停价和保证金率，可用于校验回测引擎（如 china_futures.py）中品种级默认参数（_PRICE_LIMIT、_MARGIN_RATE）的合理性；对引擎未覆盖的品种，也可从接口数据中提取真实参数进行校准。