Tushare 可转债票面利率接口（cb_rate）实战指南：从票息结构到定价研究

• 金融科技
• 示例工程

本文围绕 ai_quant_trade 仓库中 tushare 数据源 Skill 包内的《可转债票面利率》接口文档，系统讲解 Tusharecb_rate接口的权限门槛、输入/输出参数、调用方法与数据落地，并结合仓库中的配套脚本与可转债系列接口（cb_basic、cb_daily），展示如何把票面利率数据用于可转债的现金流建模、双低策略与转股价值研究。

一、接口总览：cb_rate 能拿到什么

可转债（Convertible Bond）兼具"债性"与"股性"，其票面利率（coupon rate）是刻画债性的核心变量：它直接决定每期应付利息，是现金流贴现、纯债价值测算的输入项。绝大多数可转债采用累进利率设计（存续期内逐年递增），因此"票面利率"不是一个单值，而是一组随付息区间变化的序列。

Tushare 的cb_rate接口（接口 ID：305，分类：债券专题）正是为此设计，提供每只转债各付息期内的票面利率明细。接口核心信息如下（出自 可转债票面利率.md）：

二、前置准备：安装、Token 与 Pro 接口

cb_rate属于 Tushare Pro 积分接口，调用前需完成环境准备。仓库中 tushare Skill 包的 SKILL.md 给出了标准流程：

1. 安装依赖（推荐 Python 3.7+，建议使用清华 PyPI 镜像加速）：

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

2. 注册并配置 Token：在 Tushare 官网注册获取 token 后，写入环境变量：

export TUSHARE_TOKEN=your_token

3. 初始化 Pro 接口：仓库中的 scripts/stock_data_example.py 展示了推荐的 token 读取方式——优先读环境变量，缺失时回退到本地缓存 token：

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

注意仓库文档的通用格式约定（见 SKILL.md 的"参数格式说明"）：日期统一为YYYYMMDD格式，代码统一使用ts_code（如123046.SZ、110030.SH），接口返回均为 pandas DataFrame。

三、输入参数详解

cb_rate的入参非常简单，仅一个必选参数（下表取自原文档并补充取值说明）：

关键点：ts_code必须采用 Tushare 标准转债代码格式（6 位数字 + 交易所后缀），例如123046.SZ表示深交所转债、113008.SH表示上交所转债。由于支持多值输入，单次调用即可批量获取多只转债的票息结构，配合"单次最大 2000 条"的限量，完全覆盖全市场存量转债的票息明细。

四、输出参数详解

接口返回 5 个字段（下表为原文档完整参数表）：

语义说明：

• rate_freq：年付息次数。绝大多数转债为每年付息一次（rate_freq=1），少数品种可能为半年付息（rate_freq=2），它是现金流时间轴的"节奏"参数。
• rate_start_date/rate_end_date：当前票面利率的适用区间（YYYYMMDD格式）。同一只转债会按存续期拆成多行，每一行对应一个票息区间，这正是累进利率结构的体现。
• coupon_rate：该区间内的年化票面利率（百分数，如0.500000表示 0.5%）。

五、接口调用示例

原文档给出的标准调用方式如下：

pro = ts.pro_api(your token) # 获取可转债基础信息列表 df = pro.cb_rate(ts_code='123046.SZ,127064.SZ', fields="ts_code,rate_freq,rate_start_date,rate_end_date,coupon_rate")

调用要点：

1. pro即ts.pro_api(token)返回的 Pro 接口实例（token 获取方式见第二节）。
2. ts_code传入多只转债（123046.SZ、127064.SZ），验证了多值输入能力。
3. fields显式指定返回字段，只取需要的 5 列，减少网络传输；不传fields时默认返回全部字段。
4. 返回结果为 pandas DataFrame，可直接用df.head()、df.to_csv()等方式预览或持久化。

为便于日常使用，可将其封装为可复用函数（参照 scripts/stock_data_example.py 的工程化写法）：

import os import tushare as ts token = os.getenv('TUSHARE_TOKEN') or ts.get_token() pro = ts.pro_api(token) def get_cb_rate(ts_code): """获取可转债票面利率明细""" try: df = pro.cb_rate( ts_code=ts_code, fields="ts_code,rate_freq,rate_start_date,rate_end_date,coupon_rate" ) print(f"{ts_code} 票面利率获取成功，共 {len(df)} 条票息区间") return df except Exception as e: print(f"获取票面利率失败：{e}") return None if __name__ == "__main__": df = get_cb_rate("123046.SZ,127064.SZ") if df is not None: print(df.sort_values(['ts_code', 'rate_start_date']))

六、返回数据示例与解读

原文档给出的cb_rate数据示例如下：

ts_code rate_freq rate_start_date rate_end_date coupon_rate 0 123046.SZ 1 20200319 20210318 0.500000 1 123046.SZ 1 20210319 20220318 0.700000 2 123046.SZ 1 20220319 20230318 1.000000 3 123046.SZ 1 20230319 20240318 1.500000 4 123046.SZ 1 20240319 20250318 2.500000 5 123046.SZ 1 20250319 20260318 3.000000 6 127064.SZ 1 20220519 20230518 0.200000 7 127064.SZ 1 20230519 20240518 0.400000 8 127064.SZ 1 20240519 20250518 0.600000 9 127064.SZ 1 20250519 20260518 1.500000 10 127064.SZ 1 20260519 20270518 1.800000 11 127064.SZ 1 20270519 20280518 2.000000

从数据中可以读出几个重要事实：

• 同一转债多行输出：123046.SZ在 2020-03-19 至 2026-03-18 的六年存续期内被拆成 6 行，每行一个票息区间，验证了"票面利率为逐年累进序列"的判断。
• 累进利率结构：123046.SZ的票息从 0.5%（第一年）逐级抬升至 3.0%（第六年）；127064.SZ则从 0.2% 升至 2.0%。这种"前低后高"的设计是 A 股转债主流结构。
• 区间连续性：每行rate_end_date与下一行rate_start_date首尾相接（如20200319~20210318之后紧接20210319~20220318），中间无空档，可直接按区间拼接成完整现金流时间轴。
• 付息频率：两例均为rate_freq=1（每年付息一次），与多数沪深转债一致。

七、应用场景：票面利率如何进入可转债研究

票面利率数据单独使用价值有限，通常要与仓库中债券专题的其他接口联动，构成完整的可转债分析链路。本 Skill 包中与票息强相关的接口还有（均见 SKILL.md 数据接口列表）：

典型研究路径包括：

1. 现金流贴现 / 纯债价值测算：以cb_rate的票息序列 +cb_basic的面值、期限、到期赎回价，按rate_freq的付息节奏贴现，得到理论债底；再与cb_daily的bond_value相互校验。
2. "双低"策略构建：双低 = 低价 + 低转股溢价率。其中"低价"的判断离不开债底支撑，而债底又由票息决定——cb_rate正是该链条的起点。
3. 持有收益预判：转债持有一年以上的策略，需要预判未来各期的利息收入，累进票息结构直接影响持有期回报预期，尤其对临近回售/到期条款的转债，票息与赎回条款（cb_basic的maturity_put_price）共同决定到期收益。

调用时可参考本包内其他可转债接口的入参习惯：cb_basic支持按ts_code、list_date、exchange过滤，cb_daily支持按trade_date/start_date/end_date提取——先用cb_basic拿到全市场转债代码池，再批量喂给cb_rate逐只拉取票息结构，是兼顾限量与效率的推荐组合。

八、注意事项与限制

• 权限门槛：cb_rate需要至少 5000 积分，门槛高于cb_basic（2000 积分）与cb_daily（2000 积分），属于进阶数据接口；积分不足时调用会报权限错误，需按官方积分获取办法升级。
• 限量与分批：单次最大返回 2000 条。一只 6 年期转债约产生 6 行记录，全市场存量转债不过数百只，通常单次即可取完；若自建历史转债全集（含已退市品种），超出限量时需按代码分批循环提取。
• 数据范围：接口返回的是各付息区间内的约定票面利率，不含补偿利率（cb_basic的add_rate字段单独提供）及回售价差，做到期收益测算时需叠加cb_basic的补偿利率与到期赎回条款。
• 日期格式：rate_start_date、rate_end_date为YYYYMMDD字符串，需要做日期运算（如计算剩余付息次数）时请先pd.to_datetime()转换。

九、小结

cb_rate是 Tushare 债券专题中定位精准、结构清晰的数据接口：入参仅需转债代码，输出即完整的票息分期序列。掌握它之后，配合仓库内 SKILL.md 的安装与鉴权流程、scripts/stock_data_example.py 的工程化调用范式，以及cb_basic/cb_daily的联动数据，即可搭建从"票息现金流 → 债底估值 → 转债行情"的完整可转债研究数据底座。

• 金融科技
• 示例工程