合约

IBKR 的 Web API 下单和行情请求通常不直接使用股票代码，而是使用 conid。conid 是 IBKR 对具体金融合约的合约 ID。

例如 AAPL 只是股票代码；conid=265598 才能明确表示美股 Apple Inc. 普通股。

官方参考：Client Portal API

常用接口

接口	方法	用途
/iserver/secdef/search	POST	按 symbol 搜索合约。
/iserver/secdef/info	GET	查询指定合约的详细定义。
/iserver/secdef/strikes	GET	查询期权可用行权价。
/trsrv/stocks	GET	查询股票 symbol 对应的合约候选。
/trsrv/futures	GET	查询期货合约候选。

搜索合约

curl -k -X POST "https://localhost:5000/v1/api/iserver/secdef/search" ^
  -H "Content-Type: application/json" ^
  -d "{\"symbol\":\"AAPL\",\"name\":false}"

常见返回结构：

[
  {
    "conid": "265598",
    "companyName": "APPLE INC",
    "symbol": "AAPL",
    "description": "NASDAQ",
    "sections": [
      {
        "secType": "STK"
      }
    ]
  }
]

字段解释：

字段	中文说明
conid	IBKR 合约编号，行情和下单接口经常使用它。
companyName	公司或合约名称。
symbol	交易代码。
description	交易所、到期月份或其它描述信息。
sections	可交易品种分类，例如股票、期权、期货等。
secType	合约类型，常见有 STK、OPT、FUT、CASH。

查询股票合约候选

curl -k "https://localhost:5000/v1/api/trsrv/stocks?symbols=AAPL"

这个接口适合做 symbol 自动补全。它可能返回多个市场或交易所下的同名 symbol，程序不要只取第一个就下单，应该让用户确认交易所、币种和合约类型。

Python 示例

import requests

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

payload = {
    "symbol": "AAPL",
    "name": False,
}

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

contracts = response.json()
for contract in contracts:
    print(contract.get("conid"), contract.get("symbol"), contract.get("companyName"))

成功判断

运行示例后，应重点检查这些结果：

检查项	正常含义
返回数组不为空	至少找到一个候选合约。
候选里有 conid	行情、订单和合约详情可以继续使用该 ID。
symbol、secType、description 符合预期	没有把同名股票、期货、期权或其它交易所合约混在一起。

新手容易踩的坑

问题	说明
symbol 不等于合约	AAPL、ES、EUR 都可能对应多个具体合约。
期权必须进一步选到到期日和行权价	只知道正股 conid 不能直接下期权单。
搜索结果可能包含不同交易所	下单前要确认交易所、币种、合约类型。
conid 也可能随合约生命周期变化	期货、期权到期后不要继续使用旧合约编号。