理解 Brokerage Session

Brokerage session 可以理解为“某个 IBKR 用户名连接到后端交易系统的交易会话”。它不是账户本身，也不是某个单独 endpoint 的 token。

用户名、账户和权限

名称	中文理解
Username	登录凭证。交易权限、行情订阅、可见账户通常挂在用户名上。
Account	资金和持仓所在的账户，例如个人账户、子账户或 FA 客户账户。
Brokerage session	该用户名活跃的交易会话。
Trading permission	用户名可交易哪些产品、市场和账户。
Market data subscription	用户名订阅了哪些行情数据。

一个用户名可能能看到多个账户，但 brokerage session 是由用户名建立的。建立成功后，程序可以操作该用户名有权访问的账户。

单用户名只能一个交易会话

IBKR 对同一用户名的 active brokerage session 有限制。常见竞争关系包括：

已登录平台	再登录 Client Portal API 时可能发生什么
TWS	API 建立 brokerage session 可能导致 TWS 交易会话被挤掉，或 API 被竞争状态挡住。
IB Gateway	同样可能竞争交易会话。
IBKR Mobile	移动端交易会话也可能占用同一用户名。
Client Portal 网站	如果进入交易功能，也可能形成竞争。

compete 字段

调用 /iserver/auth/ssodh/init 时，compete 字段决定是否让这次连接竞争 brokerage session。

值	中文解释
false	不主动抢占其他 brokerage session。适合先探测状态。
true	让这次连接优先，可能断开同一用户名在其他平台上的 trading session。

使用 compete=true 前要确认不会影响正在运行的 TWS、移动端或其他自动化程序。

和 /iserver 的关系

/iserver 可以理解为 IBKR 后端交易服务的 Web API 入口。访问订单、行情、成交和交易相关资源时，通常都要先有 authenticated brokerage session。

如果没有 brokerage session，常见表现是：

• /iserver/auth/status 返回 authenticated=false
• 行情或订单 endpoint 返回未认证或未连接
• WebSocket 交易 topic 无法正常订阅
• 程序以为 HTTP 连通，但业务数据为空或被拒绝

实战判断

开发时可以把认证检查写成三步：

1. Gateway 是否能访问。
2. SSO / Portal session 是否有效。
3. Brokerage session 是否 authenticated=true。

只有第三步通过，才进入下单、行情和成交处理逻辑。