历史 K 线

历史 K 线是 TWS API 最常用的行情接口之一。它把一个合约在某段时间内的价格和成交量整理成固定周期的 bar，例如 5 分钟线、1 小时线、日线或月线。

如果说 Contract 解决的是“查谁”，历史 K 线解决的就是“查这个合约过去一段时间的价格走势”。

请求要说清楚什么

请求历史 K 线时，你要同时说清楚这几件事：

问题	对应参数	AAPL 示例
查哪个合约	`contract`	AAPL 股票
查到什么时候	`endDateTime`	`""` 表示截至 TWS 可用的最新时间
向前查多长	`durationStr`	`1 D`
每根 K 线多大	`barSizeSetting`	`5 mins`
查哪种数据	`whatToShow`	`TRADES`
是否只要常规交易时段	`useRTH`	`1`
返回什么日期格式	`formatDate`	`1`

核心请求长这样：

app.reqHistoricalData(
    reqId,
    contract,
    endDateTime,
    durationStr,
    barSizeSetting,
    whatToShow,
    useRTH,
    formatDate,
    keepUpToDate,
    chartOptions,
)

AAPL 验证结果

AAPL 股票请求参数：

durationStr=1 D
barSizeSetting=5 mins
whatToShow=TRADES
useRTH=1
formatDate=1

验证输出显示连接、合约、历史数据 farm 和请求参数都正常，并返回 78 根 5 分钟 K 线：

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

实际开发时不要只看第一根 bar，要等 historicalDataEnd() 到达后再认为本次请求完成。

目标	方法 / 回调
请求历史 K 线	`reqHistoricalData()`
接收每根 K 线	`historicalData()`
接收结束通知	`historicalDataEnd()`
取消历史 K 线请求	`cancelHistoricalData()`
保持最后一根 K 线更新	`keepUpToDate=True` 时接收 `historicalDataUpdate()`

新手最容易错的地方

问题	说明
`durationStr` 和 `barSizeSetting` 组合太大	可能返回很慢、被拒绝或触发限频。
合约没有先验证	先用 `reqContractDetails()` 确认 `conId` 和主交易所。
`useRTH=1` 和 `useRTH=0` 混用	回测和实盘数据口径会不一致。
不处理 `historicalDataEnd()`	脚本不知道什么时候真正结束。
忽略时区	AAPL 返回的是 `US/Eastern`，不要直接当成电脑所在时区。

历史 K 线看起来像“拉一个数组”，但在 TWS API 里它是异步回调。程序必须收集每根 BarData，等 historicalDataEnd() 到达后再统一处理。

历史 K 线

请求要说清楚什么

AAPL 验证结果

相关方法和回调

新手最容易错的地方