请求最早数据点

reqHeadTimeStamp() 是一个轻量但很有用的历史行情辅助请求。它不会返回 K 线数组，只返回“这个合约在这种历史数据类型下，最早能从哪里开始取”的时间。

官方参考：Head Timestamp

示例代码

下面的示例查询 AAPL 股票在 TRADES 数据类型下的历史起点。

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.reqHeadTimeStamp(
    3001,         # reqId：本次请求编号，回调时会原样返回。
    contract,     # contract：要查询的合约。
    "TRADES",     # whatToShow：查询成交类历史数据的起点。
    1,            # useRTH：1 表示只使用常规交易时段。
    1,            # formatDate：1 返回可读时间字符串。
)

参数说明

参数	新手理解	常见错误
reqId	给这次请求贴一个编号	多个请求复用同一个编号，导致回调难以对应。
contract	要查哪个品种	合约不唯一或缺少 primaryExchange。
whatToShow	要查哪类历史数据	使用账户没有权限或该合约不支持的数据类型。
useRTH	是否只看常规交易时段	回测用 RTH，实盘信号却用全时段，数据不一致。
formatDate	时间返回格式	没按返回格式解析，导致时区或时间戳处理错误。

参考输出

REQUEST_SENT=reqId=3001;name=aapl_trades_rth_string;whatToShow=TRADES;useRTH=1;formatDate=1
CONNECTED=True
CONTRACT=AAPL STK SMART NASDAQ USD
HEAD=reqId=3001;name=aapl_trades_rth_string;timestamp=19801212-14:30:00
NON_INFO_ERROR_COUNT=0

如果把 useRTH 改为 0，同一 AAPL TRADES 样本返回同一个起点：

REQUEST_SENT=reqId=3002;name=aapl_trades_all_string;whatToShow=TRADES;useRTH=0;formatDate=1
HEAD=reqId=3002;name=aapl_trades_all_string;timestamp=19801212-14:30:00

这不表示所有合约的 RTH 和全时段起点都相同。期货、外汇、盘前盘后活跃股票都可能不同。

reqHeadTimeStamp() 只返回最早时间，不返回开高低收、成交量或 bar 数量。拿到时间后，仍要用 reqHistoricalData() 分段拉取实际 K 线。

和历史 K 线请求的区别

reqHistoricalData() 返回一组 K 线；reqHeadTimeStamp() 只返回最早时间点。实际开发中通常先查起点，再按时间窗口循环取 K 线。

# 第一步：查最早可用时间。
app.reqHeadTimeStamp(3001, contract, "TRADES", 1, 1)

# 第二步：根据返回的 headTimestamp，再分段请求历史 K 线。
app.reqHistoricalData(
    4102,
    contract,
    "",
    "2 D",
    "1 hour",
    "TRADES",
    1,
    1,
    False,
    [],
)

请求完成后建议调用 cancelHeadTimeStamp(reqId)。这样批量查询多合约时，请求生命周期更清晰。