Client Portal Web API

Client Portal Web API 是 IBKR 面向 Web 集成场景提供的一组 HTTP 和 WebSocket 接口。它更接近普通 Web 开发习惯：通过 endpoint 发送请求，通过 JSON 获取响应，部分实时数据通过 WebSocket topic 订阅。

如果你已经习惯 REST API、WebSocket、OAuth、服务端网关这些概念，Client Portal Web API 会比 TWS API 更容易从“Web 系统”的角度理解。

适合什么场景

场景	为什么适合
Web 后台或管理系统	HTTP/JSON 接口更容易接入后端服务。
账户、组合、订单、行情查询	官方提供了覆盖账户、组合、市场数据、订单等方向的 endpoint。
浏览器或服务端需要 WebSocket 数据	WebSocket topic 比 TWS Socket 更接近前后端常见模型。
团队更熟悉 REST/WebSocket	学习成本通常低于 TWS API 的 `EClient` / `EWrapper` 回调模型。

不适合的场景：

场景	建议
只想快速用 Python 连接本机 TWS 跑模拟交易	TWS API 更直接。
需要复用大量 TWS API 示例代码	TWS API 的资料和代码结构更匹配。
想完全避开登录、会话和认证问题	Client Portal Web API 仍然需要处理会话认证。
只要日终报表和流水	Flex Web Service 更合适。

Client Portal Web API 的典型链路是：

你的 Web 服务或脚本
  ↓ HTTP / WebSocket
Client Portal Gateway 或官方认证入口
  ↓
IBKR 后端

和 TWS API 最大的区别在于：它不是连接 TWS 的 7497 Socket 端口，而是通过 Web 风格接口访问。

Client Portal Web API 里经常会看到两类概念：

名称	中文理解	用途
endpoint	HTTP 接口地址	用来请求账户、组合、订单、行情快照等数据。
WebSocket topic	WebSocket 订阅主题	用来订阅实时行情、订单通知、账户更新等消息。

HTTP endpoint 更像一次性查询；WebSocket topic 更像持续订阅。

例如：

HTTP 请求：查询账户列表、合约信息、订单状态
WebSocket 订阅：持续接收行情或通知

具体 endpoint 和 topic 适合到对应目录中按业务场景查询。入门页先理解它们的区别，不需要一次性背完。

Client Portal Web API 的难点通常不在“怎么发 HTTP 请求”，而在认证和会话管理。

开发时需要特别注意：

事项	说明
会话有效期	登录状态不是永久有效，需要处理过期和重新认证。
Gateway 状态	如果使用 Client Portal Gateway，需要确认它已经启动并可访问。
多会话限制	同一个账户在不同客户端、浏览器或网关中的登录状态可能互相影响。
生产环境认证	真正上线时要按官方要求处理认证、权限和安全边界。

这也是为什么很多个人开发者第一步仍然会选择 TWS API：先在本机模拟账户里把交易和行情逻辑跑通，再决定是否需要 Web API 方案。

对比项	Client Portal Web API	TWS API
协议风格	HTTP / WebSocket	TCP Socket
数据格式	JSON 为主	Python/Java/C++/C# 客户端对象和回调
开发习惯	更像 Web 后端	更像连接交易客户端
是否需要 TWS	通常不直接连接 TWS 端口	必须连接 TWS 或 IB Gateway
示例代码风格	`curl`、HTTP client、WebSocket client	`EClient`、`EWrapper`、回调方法
入门难点	认证、会话、Gateway	TWS 设置、Socket 连接、回调模型

简单理解：

Client Portal Web API 的请求通常由本地 Gateway 或官方认证入口转发到 IBKR 后端。入门阶段先理解结构，不急着复制代码。

部分	中文理解	常见内容
Gateway 地址	本地 Client Portal Gateway 的访问地址。	常见是 `https://localhost:5000/v1/api`。
endpoint	HTTP 接口路径。	账户、组合、行情、订单、会话等路径。
认证状态	当前浏览器或 Gateway 会话是否已经登录。	会话过期时接口会失败。
证书处理	本地 Gateway 常涉及 HTTPS 自签证书。	开发环境和生产环境处理方式不同。

例如账户查询在结构上属于：

真正放入可复制代码前，应先确认 Gateway、认证、证书和返回结果都已经在本机或测试环境验证通过。

如果你当前目标是：

那就先从 TWS API 开始。Client Portal Web API 更适合作为 Web 化、服务端化或 OAuth 接入方向的补充。