市场扫描器参数总览

市场扫描器参数是 TWS 告诉 API 客户端“现在可以怎样扫描市场”的清单。它不是行情结果，而是一份 XML 配置表，里面包含可用的产品类型、市场区域、扫描条件和排序方式。

写扫描器功能时，不应该只凭记忆写 instrument、locationCode 和 scanCode。更稳的做法是先调用 reqScannerParameters()，从返回的 XML 中确认 TWS 支持哪些组合，然后再发起 reqScannerSubscription()。

官方参考：IBKR Campus - Market Scanner；IBKR Campus 教程：TWS Python API Market Parameters and Scanners

为什么先请求参数

市场扫描器的字段不是完全固定的。不同 TWS 版本、区域、产品类型和账户权限，可能会影响可用扫描条件。

例如常见股票扫描会用到：

字段	示例	说明
`instrument`	`STK`	扫描对象类型，`STK` 表示股票。
`locationCode`	`STK.US.MAJOR`	扫描市场范围，例如美国主要股票市场。
`scanCode`	`HOT_BY_VOLUME`	扫描规则，例如按成交量活跃度排序。

如果其中一个值写错，TWS 可能直接返回空结果或错误；如果三个值彼此不匹配，也可能收不到结果。

接口关系

步骤	接口 / 回调	说明
1	`reqScannerParameters()`	请求可用扫描器参数。
2	`scannerParameters(xml)`	接收一段 XML 字符串。
3	解析 XML	找到合适的 `instrument`、`locationCode`、`scanCode`。
4	`reqScannerSubscription()`	用选好的参数请求真实扫描结果。

字段从 XML 哪里来

官方文档把 ScannerSubscription 的核心字段和 XML 节点对应起来了：

订阅字段	XML 来源	用途
`instrument`	`ScanParameterResponse / InstrumentList / Instrument / type`	产品类型，例如股票、期货、指数等。
`locationCode`	`ScanParameterResponse / LocationTree / Location / ... / locationCode`	扫描市场或区域。
`scanCode`	`ScanParameterResponse / ScanTypeList / ScanType / scanCode`	排序或扫描规则。
过滤条件	`ScanParameterResponse / FilterList / RangeFilter / AbstractField / code`	价格、成交量、市值等额外筛选。

这样设计的好处是：程序可以先读取 TWS 当下支持的参数，再让用户选择组合。比把几个字符串硬编码在页面里更稳。

参考输出

示例请求扫描器参数成功，TWS 返回了完整 XML：

CONNECTED=True
PARAMETERS_RECEIVED=True
PARAMETERS_XML_LENGTH=1963553
PARAMETERS_ROOT=ScanParameterResponse
INSTRUMENT_COUNT=784
SAMPLE_INSTRUMENTS=STK,STK,STK,STK,STK,STK,STK,STK
LOCATION_COUNT=321
SAMPLE_LOCATIONS=STK.US,STK.US.MAJOR,STK.NYSE,STK.AMEX,STK.ARCA,STK.NASDAQ,STK.NASDAQ.NMS,STK.NASDAQ.SCM
SCAN_CODE_COUNT=771
SAMPLE_SCAN_CODES=SCAN_etfAssets_DESC,SCAN_etfAssets_ASC,SCAN_etfExpense_DESC,SCAN_etfExpense_ASC,SCAN_etfALTAR_DESC,SCAN_etfALTAR_ASC,SCAN_etfAvgALTAR_DESC,SCAN_etfAvgALTAR_ASC

这说明 reqScannerParameters() 可以正常连接 TWS 并拿到配置。XML 很大，页面或日志里不要完整打印；实际项目里通常只解析自己需要的字段。

和行情权限的关系

扫描器参数本身只是配置清单，通常不等同于实时行情订阅。扫描订阅也只返回“符合条件的合约列表”，不会返回 bid、ask、last、volume 等行情字段。

但如果使用价格、成交量、市值等过滤条件，IBKR 官方说明通常仍可能需要相应市场数据订阅。实际开发时可以把扫描器分成两步处理：

先用少量条件确认能返回合约列表。
再对返回的合约单独请求实时行情、延迟行情或历史 K 线。

新手容易误解的点

市场扫描器参数不是“扫描结果”。它只告诉你能扫什么、怎么扫。

扫描器结果也不是普通行情。scannerData() 返回的是排名和合约信息，例如第几名、股票代码、交易所、conId 等；如果要继续拿价格、买卖盘或历史 K 线，还需要再对返回的合约调用对应行情接口。