合约详情总览

reqContractDetails() 用来把一个 Contract 合约对象交给 TWS 校验，并返回更完整的合约信息。它是很多 TWS API 项目的第一道“合约确认”步骤。

它适合回答这些问题：

• 这个合约写法能不能被 TWS 识别？
• AAPL + STK + SMART + USD 最终对应哪个 conId？
• 主要交易所、交易类别、最小报价单位、交易时间是什么？
• 这个合约会不会返回多条匹配结果？
• 是否需要补 primaryExchange、localSymbol、tradingClass 或直接改用 conId？

请求流程

reqContractDetails(reqId, contract)
    -> contractDetails(reqId, contractDetails)
    -> contractDetailsEnd(reqId)

步骤	中文解释
reqContractDetails()	发起合约详情请求。
contractDetails()	TWS 返回一条合约详情。可能返回多次。
contractDetailsEnd()	对应 reqId 的合约详情已经返回完毕。

一个请求可能返回多条 contractDetails()。例如条件太宽，或者查询期权、期货、同代码多市场产品时，都可能有多条匹配。程序不要只看第一条，应该等 contractDetailsEnd(reqId) 后再统一处理。

返回对象分两层

contractDetails 是 ContractDetails 对象，它里面又包含一个 contract 字段：

ContractDetails
    ├─ contract                  # Contract 对象，保存 conId、symbol、secType 等合约身份字段
    ├─ longName                  # 合约长名称
    ├─ minTick                   # 最小报价单位
    ├─ validExchanges            # 可用交易所/路由
    ├─ marketRuleIds             # 市场规则 ID
    ├─ tradingHours              # 交易时段
    └─ ...

可以这样理解：

• contractDetails.contract 回答“这到底是哪一个合约”。
• contractDetails 其他字段回答“这个合约有哪些交易规则和描述信息”。

常用字段

信息	字段示例	用途
精确合约标识	contract.conId	程序保存和再次请求时最稳定。
标的代码	contract.symbol	人工识别。
证券类型	contract.secType	股票、期权、期货、外汇等。
路由交易所	contract.exchange	例如 SMART。
主要交易所	contract.primaryExchange	消除同代码歧义。
币种	contract.currency	区分不同市场和计价币种。
本地代码	contract.localSymbol	TWS 或交易所本地显示。
交易类别	contract.tradingClass	期权链、交易规则里常用。
合约全名	longName	UI 展示或日志。
市场名称	marketName	IBKR 返回的市场名。
最小报价单位	minTick	基础价格步长，下单价格校验会用到。
可用交易所	validExchanges	判断可用路由和交易所。
市场规则 ID	marketRuleIds	可配合 reqMarketRule() 查价格增量规则。
交易时间	tradingHours、liquidHours	判断交易时段。
时区	timeZoneId	处理历史数据和交易时间。
合约月份	contractMonth	期货、期权等衍生品常见。
真实到期日	realExpirationDate	某些衍生品用于确认实际到期日期。
最后交易时间	lastTradeTime	部分产品返回，用于到期相关判断。
价格精度	lastPricePrecision	展示和格式化价格时有用。
数量精度	lastSizePrecision	展示和格式化数量时有用。
最小数量	minSize	部分产品会返回最小交易数量。
数量增量	sizeIncrement	部分产品会返回数量步长。

字段很多，但新手先重点保存这几类：

conId, symbol, secType, exchange, primaryExchange, currency,
localSymbol, tradingClass, longName, minTick, timeZoneId,
validExchanges, marketRuleIds

AAPL 参考结果

请求输入：

symbol=AAPL
secType=STK
exchange=SMART
currency=USD

使用 TWS 模拟账户请求后参考返回：

CONNECTED=True
REQUEST_SENT=True
CONTRACT_DETAILS_END_RECEIVED=True
CONTRACT_DETAILS_ROW_COUNT=1
SEC_TYPE_COUNTS=STK:1
EXCHANGE_COUNTS=SMART:1
PRIMARY_EXCHANGE_COUNTS=NASDAQ:1
FIRST_CONID=265598
FIRST_SYMBOL=AAPL
FIRST_LOCAL_SYMBOL=AAPL
FIRST_TRADING_CLASS=NMS
FIRST_LONG_NAME=APPLE INC
FIRST_MIN_TICK=0.01
FIRST_TIME_ZONE_ID=US/Eastern
FIRST_MARKET_NAME=NMS
FIRST_VALID_EXCHANGES=SMART,AMEX,NYSE,CBOE,PHLX,ISE,CHX,ARCA,NASDAQ,DRCTEDGE,BEX,BATS,EDGEA,BYX,IEX,EDGX,FOXRIVER,PEARL,NYSENAT,LTSE,MEMX,IBEOS,OVERNIGHT,TPLUS0,PSX,T24X
INFO_CODES=2104,2106,2158
NON_INFO_ERROR_COUNT=0
IS_CONNECTED_AFTER_DISCONNECT=False

这说明 TWS 找到了 1 条明确合约：

字段	返回值
conId	265598
symbol	AAPL
secType	STK
exchange	SMART
primaryExchange	NASDAQ
currency	USD
tradingClass	NMS

这组结果可以被行情、历史 K 线、最小价格增量和下单示例复用。

为什么可能返回多条

因为你的 Contract 条件可能不够精确。

写法	可能问题	改进
只写 symbol="AAPL"	可能匹配股票、债券、衍生品等	补 secType、exchange、currency。
股票没写币种	同代码可能有不同币种	补 currency。
同代码多市场	返回多条或歧义	补 primaryExchange 或使用 conId。
期权只写底层代码	无法唯一定位某张期权	补到期日、行权价、看涨/看跌、乘数。
期货只写根代码	可能匹配多个月份	补 lastTradeDateOrContractMonth。

新手可以记住一个顺序：先用较少字段查询，再看返回结果；如果返回多条，就逐步补字段，直到只剩目标合约。

请求限制

合约详情不是无限频接口。官方文档说明，TWS API 会对合约详情请求做节流，特别是期权链或模糊查询返回大量合约时更容易慢。正式系统不要在循环里高频反复查同一个合约。

建议做法：

• 第一次启动或新增标的时查 reqContractDetails()。
• 查到明确结果后保存 conId 和关键字段。
• 常用合约走本地缓存，只有字段变更或查不到时再请求。

官方参考

• TWS API Contract Details
• TWS API ContractDetails 类