跳转到内容
IBKR TWS API 中文实战文档

交易 Web API

交易 Web API 是 IBKR Web API 中面向交易和账户监控的部分。它通过 HTTPS / JSON 和部分 WebSocket 能力访问账户、组合、合约、行情、订单、成交和通知。

官方统一 Web API 方向使用 OAuth 2.0。旧版 Client Portal Web API 则常见本地 Client Portal Gateway 会话模式。两者都是 Web API 方向，但认证、base URL、会话维护和可用 endpoint 不完全相同。

官方定位

Section titled “官方定位”

官方 Trading Web API 文档把 Web API 描述为 RESTful API：请求走 HTTPS，参数和响应主要使用 JSON，认证体系以 OAuth 2.0 为方向。官方同时说明，零售和个人客户使用 Web API 交易能力时，通常通过 Client Portal Gateway 完成本地登录与会话路由；机构、顾问、介绍经纪商和第三方服务商则可能涉及 OAuth、SSO、合规审批或额外配置。

这意味着写程序前要先确认自己属于哪种接入方式。相同的“交易 Web API”能力，在 Gateway 会话、OAuth 1.0a、OAuth 2.0 或 SSO 方案下，准备材料和请求入口并不完全一样。

适合场景

Section titled “适合场景”
场景是否适合
Web 后端服务读取账户、组合和订单状态适合
需要 HTTP / JSON，而不是本地 Socket 回调适合
多用户系统，希望把认证和账户授权放在 Web 流程里适合
桌面端快速学习 TWS 回调、下单和历史 K 线更适合先用 TWS API
不想处理 OAuth、Gateway 会话或重新认证不适合

常见资源

Section titled “常见资源”
资源中文理解常见操作
Session会话检查认证状态、保活、重新认证。
Accounts账户获取可见账户、账户摘要、账户元信息。
Portfolio组合获取持仓、资产、盈亏、组合明细。
Contracts合约搜索合约、获取 conid、读取合约信息。
Market Data行情快照行情、订阅行情、查询行情字段。
Orders订单预览订单、提交订单、修改订单、撤单。
Executions成交查询成交记录和执行明细。
Notifications通知接收账户、订单或系统通知。

认证和会话

Section titled “认证和会话”
接入方式中文理解常见对象注意点
Client Portal Gateway在用户机器或服务器上运行 Gateway，浏览器登录后由 Gateway 转发请求。个人客户、零售客户、快速验证。需要维护 Gateway 进程、登录状态、重新认证和 /tickle 保活。
OAuth 2.0官方统一 Web API 方向，使用 private_key_jwt 客户端认证。一方或机构集成。需要注册应用、公钥、回调地址、scope 和 token 生命周期管理。
OAuth 1.0a旧一代 OAuth 接入方式。部分机构和第三方服务商。第三方通常需要审批，流程比个人 Gateway 更长。
SSO经纪商/顾问为客户构建替代界面时使用。FA、IB、机构平台。常和账户管理能力一起设计。

Web API 的“认证在线”不等于“交易会话可用”。部分 /iserver 交易能力需要 brokerage session；账户、组合或合约搜索中的一部分能力可以在只读会话下使用。

请求结构

Section titled “请求结构”

Web API 请求通常由四部分组成：

部分含义
HTTP methodGET、POST、DELETE 等。
pathendpoint 路径，例如账户、合约或订单资源路径。
headers认证信息、Content-Type: application/json、可能的会话 cookie 或 bearer token。
bodyPOST / PUT 请求中的 JSON 参数。

返回值通常是 JSON。HTTP 状态码只能说明传输层是否成功，业务是否成功还要看返回体中的字段、错误码、订单状态和警告。

合约标识：先拿 conid

Section titled “合约标识：先拿 conid”

Web API 交易、行情和合约规则通常使用 IBKR 的 conid 标识合约。开发时不要只靠 symbol 下单或订阅行情，应该先通过合约搜索或合约详情接口拿到明确的 conid，再保存并复用。

股票搜索的典型形态如下：

GET /trsrv/stocks?symbols=AAPL
Accept: application/json

返回结构会按股票代码分组，每个候选项包含名称、conid、交易所、货币等字段。实际写程序时，应结合交易所、币种和产品类型筛掉错误候选。

限频和维护窗口

Section titled “限频和维护窗口”

官方文档说明，Web API 有全局和单接口限频。普通认证会话的全局上限是每个用户名约 50 次请求/秒；通过 Client Portal Gateway 访问时，上限更低，约 10 次请求/秒。超过限制时通常会收到 429 Too Many Requests。

另外，Web API 和 brokerage session 有维护窗口。尤其是 /iserver 相关交易能力，可能在每天区域性维护时短暂不可用。生产程序需要把 429、会话失效、维护窗口和重新认证当作正常状态处理。

与 TWS API 对应关系

Section titled “与 TWS API 对应关系”
Web API 能力TWS API 对应能力
合约搜索 / 合约详情reqContractDetails()、reqMatchingSymbols()
行情快照 / 行情订阅reqMktData()、reqMarketDataType()
历史数据reqHistoricalData()、reqHistoricalTicks()
订单预览 / 下单 / 撤单placeOrder()、cancelOrder()、WhatIf
成交查询reqExecutions()
账户与组合reqAccountSummary()、reqPositions()、reqPnL()

易错点

Section titled “易错点”
  • Web API 的认证成功不代表账户具备行情、交易或报表权限。
  • 订单接口通常会返回确认、警告或预览信息，不能只按 HTTP 200 判断下单完成。
  • 行情字段和 TWS API 的 Tick 类型不是一一同名，写程序时要建立字段映射。
  • 使用 Gateway 模式时，要处理登录、会话过期、重新认证和进程重启。
  • 使用 OAuth 模式时，要处理 token 生命周期、scope、回调地址和授权撤销。
  • conid 是 Web API 的关键合约标识；拿错合约 ID 比请求失败更危险，因为程序可能在错误标的上继续执行。

写程序时的顺序

Section titled “写程序时的顺序”
  1. 先打通认证和会话状态检查。
  2. 读取账户列表，确认目标账户可见。
  3. 用合约搜索拿到稳定合约 ID。
  4. 做行情或历史数据请求，确认权限边界。
  5. 做订单预览或模拟账户低风险订单确认。
  6. 再接入撤单、订单状态、成交和错误处理。