扫描器

扫描器接口用于让 IBKR 根据市场条件筛选合约，例如涨幅榜、成交量榜、活跃股票等。

它适合做选股入口，但不应该直接把扫描结果无条件交给下单逻辑。扫描只提供候选，仍然需要人工或策略规则确认。

官方参考：Client Portal API

常用接口

接口	方法	用途
/iserver/scanner/params	GET	获取可用扫描条件、地区、品种和过滤参数。
/iserver/scanner/run	POST	提交扫描请求。

获取扫描参数

curl -k https://localhost:5000/v1/api/iserver/scanner/params

这个接口返回内容较大，通常包括：

分类	中文说明
instrument	可扫描的产品类型，例如股票、期货、期权。
location	市场或地区，例如美股、港股、欧洲市场。
scanCode	扫描类型，例如涨幅、成交量、活跃度。
filter	可附加的价格、市值、成交量等过滤条件。

运行扫描

示例请求结构：

{
  "instrument": "STK",
  "location": "STK.US.MAJOR",
  "type": "TOP_PERC_GAIN",
  "filter": [
    {
      "code": "priceAbove",
      "value": 10
    }
  ]
}

字段解释：

字段	中文说明
instrument	产品类型。
location	市场范围。
type	扫描类型。
filter	可选过滤条件数组。

Python 示例：

import requests

BASE_URL = "https://localhost:5000/v1/api"

payload = {
    "instrument": "STK",
    "location": "STK.US.MAJOR",
    "type": "TOP_PERC_GAIN",
    "filter": [{"code": "priceAbove", "value": 10}],
}

response = requests.post(
    f"{BASE_URL}/iserver/scanner/run",
    json=payload,
    verify=False,  # 仅限开发调试；正式环境请配置受信任证书
    timeout=20,
)
response.raise_for_status()
print(response.json())

使用建议

问题	建议
参数太多不知道怎么选	先调用 /iserver/scanner/params，从返回里选择合法值。
扫描结果为空	检查市场、产品类型、过滤条件是否过窄。
想做自动交易	扫描结果只能作为候选池，还需要合约确认、行情确认和下单风控。

运行扫描请求前，先调用 /iserver/scanner/params 读取合法参数，再用小范围条件请求 /iserver/scanner/run。扫描运行接口会受市场、参数和权限影响；返回为空时，优先检查 instrument、location、type 和过滤条件是否来自参数接口。