查找最早可用数据点

历史行情不是无限回溯的。即使合约现在可以交易，也不代表所有年份、所有 whatToShow、所有 useRTH 组合都有数据。正式请求大范围历史 K 线之前，先查询最早可用时间点，可以避免把回测脚本写成“盲猜开始日期”。

官方参考：

这一组接口解决什么问题

reqHeadTimeStamp() 只回答一个问题：指定合约在指定历史数据类型下，最早可以从什么时候开始取。

角色	接口 / 回调	说明
发起请求	`reqHeadTimeStamp()`	向 TWS 查询最早可用历史行情时间。
接收结果	`headTimestamp()`	返回一个时间字符串或 Unix 时间戳，格式受 `formatDate` 影响。
取消请求	`cancelHeadTimeStamp()`	取消仍在运行的最早时间请求。

它常用于这些场景：

回测程序先确定可用起点，再分段请求历史 K 线。
用户输入很早的开始日期时，先判断是否早于数据可用范围。
比较 TRADES、MIDPOINT、BID_ASK 等不同 whatToShow 的可用范围。
避免一次请求过长历史区间后才发现数据缺口。

参数关系

reqHeadTimeStamp() 的核心参数和历史 K 线请求类似，但它不需要 durationStr、barSizeSetting 和 endDateTime。

app.reqHeadTimeStamp(
    reqId,
    contract,
    whatToShow,
    useRTH,
    formatDate,
)

参数	中文解释	常见取值
`reqId`	请求编号，用来在回调里识别是哪一次请求	自己分配的整数
`contract`	合约对象，必须能被 IBKR 识别	股票、期货、期权、外汇等
`whatToShow`	要查询哪类历史数据的起点	`TRADES`、`MIDPOINT`、`BID_ASK`
`useRTH`	是否只看常规交易时段	`1` 只看 RTH，`0` 包含盘前盘后
`formatDate`	返回时间格式	`1` 返回字符串时间，`2` 返回 Unix 时间戳

AAPL 参考输出

AAPL 股票合约查询 TRADES 的最早时间点：

REQUEST_SENT=reqId=3001;name=aapl_trades_rth_string;whatToShow=TRADES;useRTH=1;formatDate=1
REQUEST_SENT=reqId=3002;name=aapl_trades_all_string;whatToShow=TRADES;useRTH=0;formatDate=1
REQUEST_SENT=reqId=3003;name=aapl_trades_rth_unix;whatToShow=TRADES;useRTH=1;formatDate=2
CONNECTED=True
CONTRACT=AAPL STK SMART NASDAQ USD
INFO_CODES=2104,2106,2158
HEAD_ROWS=3
HEAD=reqId=3001;name=aapl_trades_rth_string;timestamp=19801212-14:30:00
HEAD=reqId=3002;name=aapl_trades_all_string;timestamp=19801212-14:30:00
HEAD=reqId=3003;name=aapl_trades_rth_unix;timestamp=345479400
NON_INFO_ERROR_COUNT=0

这个结果说明，在该合约、数据类型和账户权限组合下，AAPL 的 TRADES 历史数据起点可以追溯到 1980-12-12 14:30:00。formatDate=2 会返回 Unix 时间戳风格的数值。

这个时间不是固定模板。换成其他合约、交易所、whatToShow、useRTH 或账户权限后都可能不同。

输出字段怎么读

字段	含义
`CONNECTED=True`	Socket 连接已建立。
`CONTRACT=AAPL STK SMART NASDAQ USD`	请求使用的合约口径。
`HEAD_ROWS=3`	三个最早时间请求都收到了结果。
`timestamp=19801212-14:30:00`	`formatDate=1` 的字符串时间。
`timestamp=345479400`	`formatDate=2` 的 Unix 秒级时间戳。
`NON_INFO_ERROR_COUNT=0`	没有参数、权限或连接类业务错误。

实战建议

不要把 headTimestamp() 的结果直接当作回测真实起点。它只能说明 TWS API 可返回数据的最早边界，策略仍然要处理停牌、换合约、拆股、期货换月、成交稀疏和权限不足等情况。

更稳妥的流程是：

先用 reqContractDetails() 确认合约唯一。
再用 reqHeadTimeStamp() 查询可用历史起点。
按 step size 和 pacing 规则分段请求 reqHistoricalData()。
对返回 K 线做缺口检查，而不是假设每个周期都有数据。