请求历史 K 线

reqHistoricalData() 是历史 K 线的入口。它不会同步返回数组，而是先发送请求，然后通过 historicalData() 一根一根回调，最后用 historicalDataEnd() 表示结束。

AAPL 请求示例

from ibapi.contract import Contract


def make_aapl_contract():
    """创建 AAPL 股票合约。"""
    contract = Contract()
    contract.symbol = "AAPL"
    contract.secType = "STK"
    contract.exchange = "SMART"
    contract.currency = "USD"
    contract.primaryExchange = "NASDAQ"
    return contract


contract = make_aapl_contract()

app.reqHistoricalData(
    2001,        # reqId：请求编号
    contract,    # contract：合约对象
    "",          # endDateTime：空字符串表示 TWS 可用的最新时间
    "1 D",       # durationStr：向前取 1 天
    "5 mins",    # barSizeSetting：每根 K 线 5 分钟
    "TRADES",    # whatToShow：成交价相关数据
    1,           # useRTH：只使用常规交易时段
    1,           # formatDate：返回可读日期字符串
    False,       # keepUpToDate：只取一次历史数据
    [],          # chartOptions：普通请求传空列表
)

这段代码的意思是：

请求 AAPL 股票最近 1 个交易日内、常规交易时段的 5 分钟成交 K 线。

参数解释

参数	中文解释	实战建议
`reqId`	请求编号	每个未完成请求用不同编号。
`contract`	合约对象	股票建议先用 `reqContractDetails()` 验证。
`endDateTime`	历史窗口的结束时间	`""` 表示截至 TWS 可用的最新时间；指定时间时常用 `yyyyMMdd HH:mm:ss 时区`，例如 `20260612 16:00:00 US/Eastern`。
`durationStr`	从结束时间向前回看多久	格式是数量加单位，例如 `60 S`、`1 D`、`1 W`、`1 M`、`1 Y`。
`barSizeSetting`	每根 K 线的周期	例如 `5 mins`、`1 hour`、`1 day`；写法必须使用 TWS 支持的字符串。
`whatToShow`	用哪类数据生成 K 线	股票成交 K 线常用 `TRADES`，报价中间价常用 `MIDPOINT`；不同产品支持的取值不同。
`useRTH`	是否只使用常规交易时段	`1` 只要常规交易时段，`0` 包含盘前盘后等可用数据。回测和实盘口径要保持一致。
`formatDate`	返回日期格式	`1` 返回可读字符串；`2` 返回 Unix 秒级时间戳。日线以上周期通常仍按日期字符串理解。
`keepUpToDate`	是否持续更新最后一根 bar	`False` 只下载一次；`True` 会在初始历史数据后继续通过 `historicalDataUpdate()` 更新，且 `endDateTime` 应传空字符串。
`chartOptions`	额外图表选项	普通请求传空列表；只有明确需要 TWS 特殊选项时才填 `TagValue` 列表。

验证输出

AAPL 股票验证返回：

REQUEST_SENT=reqId=4101;name=aapl_5min_rth;duration=1 D;barSize=5 mins;whatToShow=TRADES;useRTH=1;formatDate=1;keepUpToDate=False
CONNECTED=True
CONTRACT=AAPL STK SMART NASDAQ USD
BAR_TOTAL_COUNT=reqId=4101;name=aapl_5min_rth;count=78
BAR=reqId=4101;name=aapl_5min_rth;date=20260612 09:30:00 US/Eastern;open=295.9;high=297.14;low=294.89;close=295.35;volume=1472090;wap=295.893;barCount=10645
BAR=reqId=4101;name=aapl_5min_rth;date=20260612 09:35:00 US/Eastern;open=295.34;high=295.4;low=293.57;close=293.59;volume=725473;wap=294.585;barCount=8512
BAR=reqId=4101;name=aapl_5min_rth;date=20260612 09:40:00 US/Eastern;open=293.6;high=293.75;low=291.87;close=292.4;volume=828923;wap=292.679;barCount=8510
END=reqId=4101;name=aapl_5min_rth;start=20260613 01:01:33 US/Eastern;end=20260614 01:01:33 US/Eastern
NON_INFO_ERROR_COUNT=0

78 根 5 分钟 K 线对应美股常规交易时段 6.5 小时：

6.5 小时 * 60 分钟 / 5 分钟 = 78 根

请求前检查

nextValidId() 已经到达，说明 Socket 握手完成。
合约能被 reqContractDetails() 唯一解析。
durationStr 和 barSizeSetting 组合符合官方 step size。
whatToShow 适合该合约和账户权限。
程序实现了 error() 回调，能看到权限、限频和参数错误。

如果合约或权限有问题，错误会走 error(reqId, code, msg, ...)，不要只等待 historicalData()。