Client Portal API 认证文档中会出现一些容易混淆的术语。先把这些词分清，排查时会简单很多。
| 术语 | 中文理解 |
|---|
| Client Portal | IBKR 网页端客户门户，用于账户管理、报表、资金、交易等功能。 |
| Client Portal API | 通过 HTTP / WebSocket 访问 Client Portal 相关功能的 API。 |
| Client Portal Gateway | 本地 Java 网关，个人账户常用它完成浏览器登录和 API 代理。 |
| Gateway session | Gateway 登录会话。 |
| SSO session | 单点登录会话，用来证明用户已经完成 Web 登录。 |
| Portal session | 外层 Client Portal 会话，不一定具备交易功能。 |
| Brokerage session | 交易会话，可访问交易、行情和 /iserver 资源。 |
/iserver | 交易、行情、订单、合约等 brokerage 功能的 endpoint 前缀。 |
/portfolio | 组合、账户相关 endpoint 前缀，部分资源不一定要求 brokerage session。 |
| Paper username | Paper Trading 专用用户名，不是 Live 用户名加一个开关。 |
| Competing session | 同一用户名在另一个平台或连接中占用 brokerage session。 |
| 容易误解 | 正确理解 |
|---|
| 登录 Gateway 就等于可以下单 | 还要确认 brokerage session authenticated=true。 |
| 账户 ID 等于用户名 | 账户是资金池，用户名是登录凭证。一个用户名可能能访问多个账户。 |
| Paper 和 Live 靠页面滑块切换 | Gateway 登录要使用 Paper Trading 专用用户名。 |
| HTTP 200 就代表交易成功 | 还要看 JSON 业务字段、订单状态、警告和错误码。 |
/tickle 能永久登录 | /tickle 只能保活，不能绕过每日重新认证和 2FA。 |
| Client Portal API | TWS API 中类似概念 |
|---|
| Gateway session | TWS / IB Gateway 已登录运行状态 |
| Brokerage session | TWS / IB Gateway 与 IBKR 后端交易连接 |
/iserver/auth/status | TWS API 中没有完全对应 endpoint，通常靠连接状态和错误码判断 |
competing=true | 多平台登录导致交易会话竞争 |
| Paper username | TWS 登录时选择的模拟账户身份 |
代码里建议把变量名写清楚：
| 推荐命名 | 含义 |
|---|
base_url | Gateway 地址，例如 https://localhost:5000/v1/api 或对应文档要求的 base URL。 |
portal_session_ok | 外层 Web session 是否有效。 |
brokerage_authenticated | brokerage session 是否已认证。 |
competing_session | 是否检测到竞争交易会话。 |
paper_username | Paper Trading 专用用户名。 |
这样可以避免把“登录成功”“连接成功”“交易会话认证成功”混成一个布尔值。