接收搜索到的股票合约

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

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

contractDescriptions 是一组 ContractDescription 对象。每个对象包含一个 contract，以及一组衍生品类型 derivativeSecTypes。

字段说明

字段	类型	中文含义	AAPL 示例	说明
`reqId`	`int`	请求编号	`9502`	对应 `reqMatchingSymbols()`。
`contract.conId`	`int`	合约 ID	`265598`	程序保存和继续请求时最推荐使用。
`contract.symbol`	`str`	标的代码	`AAPL`	不一定唯一。
`contract.secType`	`str`	证券类型	`STK`	搜索结果里也可能有 `BOND`、`IND`。
`contract.primaryExchange`	`str`	主要交易所	`NASDAQ`	区分同代码不同市场时很重要。
`contract.currency`	`str`	币种	`USD`	交易和行情请求都要关注。
`derivativeSecTypes`	`set[str]`	支持的衍生品类型	`BAG,CFD,IOPT,OPT,WAR`	例如 `OPT` 表示可以继续查期权链。

结构化处理示例

def symbolSamples(self, reqId, contractDescriptions):
    candidates = []
    for item in contractDescriptions:
        contract = item.contract
        candidates.append(
            {
                "conId": contract.conId,
                "symbol": contract.symbol,
                "secType": contract.secType,
                "primaryExchange": contract.primaryExchange,
                "currency": contract.currency,
                "derivativeSecTypes": sorted(str(x) for x in item.derivativeSecTypes),
            }
        )
    self.rows = candidates

如果只想要 AAPL 美股，可以再过滤：

aapl_us_stock = [
    row
    for row in self.rows
    if row["symbol"] == "AAPL"
    and row["secType"] == "STK"
    and row["currency"] == "USD"
    and row["primaryExchange"] == "NASDAQ"
]

参考样例

示例连接搜索 AAPL 后，符合 AAPL 美股条件的候选为：

SYMBOL_SAMPLE=conId=265598;symbol=AAPL;secType=STK;primaryExchange=NASDAQ;currency=USD;derivativeSecTypes=BAG,CFD,IOPT,OPT,WAR

搜索结果证券类型分布：

SYMBOL_SEC_TYPE_COUNTS=BOND:3,IND:2,STK:12

这说明 AAPL 关键词返回了 12 条股票结果、3 条债券结果、2 条指数结果。交易系统不要默认第一条以外都无关，也不要默认所有结果都是 STK。

`derivativeSecTypes` 怎么用

类型	常见含义	可以怎么用
`OPT`	期权	说明该标的可以继续请求期权链。
`IOPT`	交互式/组合相关期权类型	一般不作为新手首选交易类型。
`CFD`	差价合约	是否可交易取决于账户、地区和产品权限。
`WAR`	权证	与股票期权不同，应单独确认合约详情。
`BAG`	组合合约	组合订单或价差策略会涉及。

常见问题

搜索返回多只股票怎么办

展示 symbol、primaryExchange、currency、conId 给用户选择；自动化程序则应按业务规则过滤，并用合约详情再次确认。

搜索结果为空怎么办

先检查关键词拼写，再改用更短的关键词。仍为空时，可以在 TWS 合约搜索界面确认该产品是否存在，或者检查账号地区与产品权限。

看到 `OPT` 就能直接拼期权合约吗

不能。OPT 只表示这个标的支持期权。还需要用 reqSecDefOptParams() 获取可用到期日、行权价、交易类别和乘数。