接收债券详情

当 reqContractDetails() 查询的是债券合约时，TWS API 会通过 bondContractDetails() 返回债券详情。

def bondContractDetails(self, reqId, contractDetails):
    ...

债券详情仍然使用 ContractDetails 对象，只是会填充更多债券相关字段，例如 CUSIP、评级、票息、到期日、可赎回/可回售条款等。

和普通合约详情的区别

普通合约详情	债券详情
重点是 conId、交易所、币种、交易时间	还需要债券评级、票息、到期日、赎回/回售条款
股票可用 symbol + STK + SMART + USD 查	债券更依赖 CUSIP/ISIN 等精确标识
返回 contractDetails()	返回 bondContractDetails()
股票、期权、期货更常用于行情和下单示例	债券字段更多用于产品识别、展示和适当性检查

常见债券字段

字段	中文含义	说明
cusip	CUSIP 编码	美国和加拿大证券常用识别码。
ratings	债券评级	可能包含多个评级机构信息。
descAppend	追加描述	债券描述补充信息。
bondType	债券类型	例如公司债、政府债等，实际返回以 TWS 为准。
couponType	票息类型	固定、浮动等。
coupon	票息	债券票面利率。
maturity	到期日	债券到期日期。
issueDate	发行日	债券发行日期。
callable	是否可赎回	发行人是否可提前赎回。
putable	是否可回售	持有人是否可按条款回售。
convertible	是否可转换	是否可转换为其他证券。
nextOptionDate	下一可选日期	下一次可赎回、可回售或其他可选条款日期。
nextOptionType	下一可选类型	下一可选条款类型。
nextOptionPartial	是否部分可选	是否只适用于部分本金或部分条款。
notes	备注	债券相关补充说明。

债券字段不一定每个都有值。程序要能处理空字符串、空日期和未知字段。

请求债券的写法

债券合约比股票更依赖明确标识。不要只用 symbol 猜债券，通常应使用 secIdType 和 secId，例如 CUSIP、ISIN 等。

from ibapi.contract import Contract


bond = Contract()
bond.secType = "BOND"          # BOND 表示债券
bond.exchange = "SMART"        # 常见路由写法，实际以账户和产品为准
bond.currency = "USD"          # 债券计价币种
bond.secIdType = "CUSIP"       # 也可能使用 ISIN 等
bond.secId = "实际 CUSIP"       # 使用真实且有权限查询的证券 ID

公开示例不要编造 CUSIP 或真实债券返回。债券代码、评级和发行信息属于具体产品信息，实际使用时应从 TWS、账户可见数据或授权数据源中确认。

Python 回调结构

def bondContractDetails(self, reqId, details):
    row = {
        "reqId": reqId,
        "conId": details.contract.conId,
        "currency": details.contract.currency,
        "cusip": details.cusip,
        "ratings": details.ratings,
        "bondType": details.bondType,
        "couponType": details.couponType,
        "coupon": details.coupon,
        "maturity": details.maturity,
        "issueDate": details.issueDate,
        "callable": details.callable,
        "putable": details.putable,
        "convertible": details.convertible,
        "nextOptionDate": details.nextOptionDate,
        "nextOptionType": details.nextOptionType,
        "notes": details.notes,
    }
    self.rows.append(row)

如果把债券详情展示给用户，建议把空值统一显示为“未返回”，不要直接展示空字符串。

数据权限和可见性

债券合约定义和债券行情不是同一件事。能查到债券详情，不代表一定能订阅实时行情；能在 TWS 中看到某个债券，也不代表所有字段都能通过 API 返回。

常见影响因素包括：

• 账户地区与产品权限。
• 债券数据源可见性。
• 使用的证券 ID 是否准确。
• TWS 登录账户是否能访问该产品。
• 该债券是否仍可交易或仍有可用市场数据。

常见问题

债券详情可以用 AAPL 股票示例验证吗？

不可以。AAPL 股票会走普通 contractDetails()，不会走债券回调。只有债券合约才会触发 bondContractDetails()。

债券一定有行情权限才能查吗？

不一定。合约定义和实时行情是不同概念，但债券数据可见性会受账户、地区和产品权限影响。实际返回以 TWS 为准。

为什么不提供具体债券 CUSIP？

债券示例需要真实产品标识和权限。公开文档里给出结构和字段解释，比编造一个不可用 CUSIP 更可靠。

如果没有收到 bondContractDetails() 怎么办？

先确认你请求的是 secType="BOND"，并且使用了正确的 CUSIP、ISIN 或其他证券 ID。若仍没有返回，再检查 TWS 是否能看到该债券、账户是否有对应产品权限，以及是否出现非信息类错误码。

官方参考

• TWS API Contract Details
• TWS API ContractDetails 类