股票代码搜索总览

股票代码搜索用于把用户输入的关键词，转换成 TWS 能识别的一组候选合约。它适合做搜索框、合约选择器，也适合在不知道准确 conId 时作为第一步。

app.reqMatchingSymbols(reqId, pattern)

搜索结果通过 symbolSamples() 回调返回：

def symbolSamples(self, reqId, contractDescriptions):
    ...

这里的重点是：搜索结果只是“候选”，不是最终可直接交易的合约。交易、行情、历史 K 线和期权链请求，都建议先把候选结果筛选清楚，再用合约详情接口确认。

它适合解决什么问题

场景	是否适合	说明
用户输入股票代码后展示候选	适合	例如输入 AAPL 后展示股票、债券、指数等相关结果。
不知道标的 conId	适合	可以从候选结果里拿到 contract.conId。
直接生成下单合约	不建议	搜索结果可能包含多种证券类型，应再确认。
查期权链前找标的	适合	先筛出股票合约，再把 conId 交给 reqSecDefOptParams()。

搜索结果包含什么

每条结果是一个 ContractDescription，主要由两部分组成：

字段	中文含义	用法
contract	匹配到的合约对象	包含 conId、symbol、secType、primaryExchange、currency 等字段。
derivativeSecTypes	可用衍生品类型列表	例如 OPT 表示可继续查期权链，CFD 表示可能有差价合约。

AAPL 参考结果

示例连接搜索 AAPL 返回：

CONNECTED=True
SYMBOL_CALLBACK_RECEIVED=True
SYMBOL_ROW_COUNT=17
SYMBOL_SEC_TYPE_COUNTS=BOND:3,IND:2,STK:12
SYMBOL_SAMPLE=conId=265598;symbol=AAPL;secType=STK;primaryExchange=NASDAQ;currency=USD;derivativeSecTypes=BAG,CFD,IOPT,OPT,WAR
NON_INFO_ERROR_COUNT=0

这说明搜索 AAPL 不只返回股票，也会返回相关债券和指数。程序不能看到关键词是股票代码，就假设所有结果都是股票。

推荐筛选流程

以 AAPL 美股为例，比较稳的流程是：

1. 调用 reqMatchingSymbols(9502, "AAPL")。
2. 过滤 secType == "STK"。
3. 过滤 currency == "USD"。
4. 优先选择 primaryExchange == "NASDAQ" 的候选。
5. 拿到 conId=265598 后，用 reqContractDetails() 确认合约详情。
6. 如果要查期权链，把这个 conId 传给 reqSecDefOptParams()。

和合约详情的关系

接口	作用	是否最终确认
reqMatchingSymbols()	根据关键词找候选合约	否
reqContractDetails()	根据合约条件返回完整详情	是

搜索接口帮助你缩小范围，合约详情接口帮助你确认“到底是哪一个合约”。

官方参考

• IBKR Campus TWS API Documentation
• TWS API Contract Search