系列：《Python 量化取数指南》｜连载项目 · 纯 GET 取数 · 仅依赖 requests
数据：由智兔数服提供。更多接口见 智兔数服技术博客。

1. 你将得到什么

• 可转债 3 类端点的完整代码：列表、现货行情、比价
• 一个自动算转股溢价率的小函数（公式 + 容错）
• 一个离线 run_check()，不填 token 也能验证公式

2. 本篇取数约定

• 可转债列表：/kzz/list
• 可转债现货行情：/kzz/spot
• 可转债比价：/kzz/comparison
• 请求：GET https://api.zhituapi.com<path>?token=<你的智兔token>
• 转股溢价率需「转债价 + 正股价 + 转股价」三要素；正股价走 A 股实时 /hs/real/ssjy/（见第 4 篇）

3. 核心模板（全系列复用）

import time, json, requests

BASE = "https://api.zhituapi.com"
TOKEN = "你的智兔token"      # 演示证书（免费版）即可起步

def _get(path, params=None, timeout=15, retry=3, backoff=1.5):
    params = dict(params or {})
    params["token"] = TOKEN
    url = BASE + path
    last = None
    for i in range(retry):
        try:
            r = requests.get(url, params=params, timeout=timeout)
            if r.status_code != 200:
                last = f"HTTP {r.status_code} {r.text[:120]}"
                time.sleep(backoff * (i + 1)); continue
            try:
                return r.json(), None
            except ValueError:
                last = f"非JSON响应: {r.text[:120]}"
                return None, last
        except requests.RequestException as e:
            last = str(e); time.sleep(backoff * (i + 1))
    return None, last

def _hit_key(d, *keys, default=None):
    if not isinstance(d, dict):
        return default
    for k in keys:
        if k in d and d[k] not in (None, "", []):
            return d[k]
    return default

def _to_float(x, default=float("nan")):
    try:
        return float(x)
    except (TypeError, ValueError):
        return default

4. 跑通示例：拉可转债 + 算转股溢价率

def conv_premium(bond_price, stock_price, conv_price):
    if not (stock_price > 0 and conv_price > 0):
        return float("nan")
    conv_value = 100.0 / conv_price * stock_price
    return bond_price / conv_value - 1.0

def demo_cb():
    data, err = _get("/kzz/spot")
    if err:
        print("可转债现货失败:", err); return
    items = data if isinstance(data, list) else (data.get("data") or [])
    print(f"  可转债现货 {len(items)} 只")
    for it in (items or [])[:5]:
        code = _hit_key(it, "code", "dm", "bond_id")
        bp = _to_float(_hit_key(it, "price", "zxj", "bond_price", "收盘价"))
        sp = _to_float(_hit_key(it, "stock_price", "zgxj", "正股价"))
        cp = _to_float(_hit_key(it, "conv_price", "zhj", "转股价"))
        prem = conv_premium(bp, sp, cp)
        print(f"    {code} 转债价 {bp} 溢价率 {prem*100:.1f}%" if prem==prem else f"    {code} 转债价 {bp}（缺正股/转股价）")

def run_check():
    p = conv_premium(130, 10, 8)
    print(f"  [run_check] 合成溢价率 {p*100:.1f}%")

if __name__ == "__main__":
    demo_cb()
    run_check()

返回字段说明：现货 list 每项含 code/dm（转债代码）、price/zxj/收盘价（转债价）、stock_price/zgxj（正股价）、conv_price/zhj（转股价）等。字段名三套并存，统一 _hit_key。

5. 坑与注意事项

1. 三要素缺一则算不出：溢价率要转债价+正股价+转股价；缺正股价就用 /hs/real/ssjy/ 补（第 4 篇）。
2. 转股价会下修：分红送股/下修条款会改变转股价， stale 值会算错，取最新。
3. 单位：转债价多为「元/张」，正股价「元/股」，转股价「元/股」，口径一致。
4. 退市/强赎：临近强赎的可转债溢价率会被压到 0 附近，属正常。
5. 字段名三套：price/zxj/收盘价，用 _hit_key。
6. 限流：可转债列表量大，批量拉加 sleep。

6. 常见报错速查

7. 小结与下一篇预告

小结：可转债走 /kzz/list|spot|comparison，转股溢价率 = 转债价/(100/转股价×正股价)−1；正股价靠 /hs/real/ssjy/ 补，转股价取最新防下修。

下一篇计划写 #11《ETF 数据接口实测与组合取数》：用 ETF 实时端点拉宽基/行业/主题 ETF 行情与清单。

8. 免责声明

本文仅演示公开数据接口的用法，所有代码示例均为演示数据，不构成任何投资建议；实际返回字段以接口文档与你的证书权限为准。数据由 智兔数服 提供，更多接口示例见 技术博客。

免费领取证书 / 查看完整接口文档，可前往 智兔数服官网。