IB 股息数据

IB Dividends 是 IB 提供的股息相关行情字段，需要在 genericTickList 中请求 456。它通常通过 tickString() 返回。

股息字段适合做持仓展示、收益预估或基本面提示，不适合当作实时交易价格字段使用。

官方参考：Available Tick Types

返回字符串

官方说明中，IB Dividends 返回 4 个逗号分隔字段：

位置	中文含义	示例
1	过去 12 个月股息合计	0.83
2	未来 12 个月预估股息合计	0.92
3	下一次股息日期	20130219
4	下一次单笔股息金额	0.23

示例原始值：

0.83,0.92,20130219,0.23

请求示例

app.reqMktData(
    97805,
    aapl_stock(),
    "456",
    False,
    False,
    [],
)

接收与解析

def tickString(self, reqId, tickType, value):
    if reqId == 97805:
        data = parse_ib_dividends(value)
        print("IB 股息", data)


def parse_ib_dividends(value: str) -> dict[str, str]:
    """解析 IB Dividends 原始字符串。字段为空时保留空字符串，便于排查。"""
    past_12m, next_12m, next_date, next_amount = (value.split(",") + ["", "", "", ""])[:4]
    return {
        "past_12m_dividends": past_12m,
        "next_12m_dividends": next_12m,
        "next_dividend_date": next_date,
        "next_dividend_amount": next_amount,
    }

genericTickList 写 456，回调中常见 tickType 是 59。保存数据时建议保留两者，便于排查字段来源。

实际项目中建议同时保存原始字符串和接收时间，再按业务需要解析。

使用边界

项目	说明
数据用途	股息提示、持仓展示、收益估算。
典型回调	tickString()。
请求编号	generic tick 456。
依赖条件	合约支持、市场数据权限、账户权限。

参考边界样例

AAPL 456 请求到达 TWS，但没有返回股息字符串：

TICK_REQ_PARAMS=reqId=97805;name=ib_dividends_456;minTick=0.01;bboExchange=EMPTY;snapshotPermissions=0
STRING_ROWS=0
ERROR=reqId=97805;name=ib_dividends_456;code=10089;msg=请求的市场数据对于API来说需要额外订阅
ERROR=reqId=97805;name=ib_dividends_456;code=300;msg=无法使用tickerId找到EId：:97805

这说明账户没有足够 API 行情权限。程序应提示用户检查订阅，而不是把空字符串当作“没有股息”。

开发建议

股息字段常用于辅助信息，不应作为交易触发的唯一依据。涉及真实收益、除权除息和税务处理时，应结合账户报表、公司行动数据和 IBKR 官方信息核对。