连接指南

Client Portal WebSocket 用于接收流式数据，例如行情、订单、成交、通知和盈亏更新。它和 REST 接口共用 Gateway 登录会话。

官方参考：Web API Documentation 和 WebSocket 教程

连接地址

Client Portal Gateway 模式的连接地址：

wss://localhost:5000/v1/api/ws

正式 Web API 地址通常是：

wss://api.ibkr.com/v1/api/ws

使用 Gateway 时，把 api.ibkr.com 换成 localhost:5000。两种地址使用的是同一套 topic 思路，但认证来源不同：Gateway 依赖浏览器登录会话，正式 Web API 依赖 OAuth 与对应的会话 cookie。

连接前提

前提	说明
Gateway 正在运行	命令行窗口保持开启。
浏览器已登录	访问 https://localhost:5000 完成登录和 2FA。
/iserver/auth/status 正常	authenticated=true 且 connected=true。
/tickle 可正常返回	用来维持 REST / Gateway 会话，也可在 OAuth 场景中取得 session token。
WebSocket 客户端接受自签名证书	Gateway 开发环境常见自签名证书；正式环境应使用受信任证书。

Topic 消息格式

WebSocket 不是发 HTTP 请求，而是向连接发送字符串 topic：

smd+265598+{"fields":["31","84","86"]}

常见结构：

部分	中文说明
smd	topic 类型，例如市场数据。
265598	合约编号。
JSON 参数	字段、频率、快照等附加参数。

常见 topic

Topic	用途
ech+hb	心跳，建议定期发送。
smd+{conid}+{...}	订阅行情。
umd+{conid}+{}	取消行情。
smh+{conid}+{...}	请求历史行情。
sbd+{conid}+{...}	订阅 BookTrader / 深度报价相关数据。
spl+{}	订阅盈亏。
upl+{}	取消盈亏。
sor+{}	订阅订单更新。
uor+{}	取消订单更新。
str+{}	订阅成交更新。

连接问题排查

现象	常见原因
WebSocket 打开后没有消息	只建立连接还不够，需要发送 topic 触发后端事件。
连接立刻关闭	Gateway 未登录、证书被拒绝或地址写错。
行情没有推送	没有行情权限、conid 错误或字段不合法。
一段时间后断开	没有心跳或 Gateway 会话过期。