新版统一 Web API
新版统一 Web API 是 IBKR 正在整理的新一代 Web API 文档体系。它不是 TWS API 的替代品，也不是单纯把旧文档换个名字，而是把多个 Web 方向的能力放到同一个入口下说明。
官方在 Web API 文档中说明，这个体系会把 Client Portal Web API、Digital Account Management 和 Flex Web Service 放在一个更统一的接口与认证框架下，并逐步使用 OAuth 2.0 作为统一授权认证方向。
它解决什么问题
Section titled “它解决什么问题”TWS API 更像“连接一台已经登录的交易终端”，而 Web API 更像“通过标准 Web 接口访问 IBKR 后端能力”。
新版 Web API 主要解决这些问题：
| 问题 | Web API 的方向 |
|---|---|
| 文档分散 | 把交易、账户管理、报表相关能力放进同一套 Web API 文档体系。 |
| 认证方式分散 | 逐步向统一的 OAuth 2.0 方向整理。 |
| Web 开发接入复杂 | 用 HTTP endpoint、JSON body、WebSocket 等 Web 开发者熟悉的方式组织接口。 |
| 团队协作困难 | 通过 Documentation 和 Reference 两类资料，把流程说明和 endpoint 定义分开。 |
这里的重点是“Web 集成”。如果你的第一步是用 Python 连接本机 TWS 模拟账户，仍然应该先看 TWS API。
和旧入口的关系
Section titled “和旧入口的关系”新版 Web API 不是说旧入口马上不能用了。官方说明中也提到，既有 endpoint 和认证方案没有废弃，仍会继续获得功能和更新。
可以这样理解：
| 名称 | 中文理解 | 当前作用 |
|---|---|---|
| Client Portal Web API | 旧版 Web API v1.0 入口 | 仍然有大量可参考的 endpoint、Gateway、会话和 WebSocket 资料。 |
| Web API | 新版统一 Web API 文档体系 | 把交易、账户管理、报表等 Web 能力放到统一结构下。 |
| Web API Reference | endpoint 参考 | 以 Swagger 风格展示接口定义，但官方也说明并非所有 endpoint 都已经完整收录。 |
| Flex Web Service | 报表接口 | 在新版 Web API 体系下也会被一起整理，但用途仍然是报表和对账。 |
所以阅读时不要只看名字。看到 HTTP、JSON、OAuth、endpoint、WebSocket 这些关键词，基本都属于 Web API 方向；看到 EClient、EWrapper、Socket Port 7497，就是 TWS API 方向。
适合什么场景
Section titled “适合什么场景”新版 Web API 更适合这些项目：
| 场景 | 说明 |
|---|---|
| Web 后台系统 | 后端服务通过 HTTP 请求账户、组合、行情、订单等数据。 |
| 组织级或机构级接入 | 企业、机构、顾问、介绍经纪商等需要更正式的认证和权限流程。 |
| 第三方应用接入 | 需要用户授权访问其 IBKR 账户时，通常要走官方审批和 OAuth 流程。 |
| 报表与交易能力统一管理 | 同一个系统既要报表，又要部分交易、账户或行情能力。 |
| 团队熟悉 REST / WebSocket | 开发体验更接近常见 Web API，而不是 TWS Socket 回调模型。 |
不适合这些情况：
| 场景 | 更适合 |
|---|---|
| 本机已经打开 TWS，只想马上跑 Python 示例 | TWS API |
| 想先学合约对象、订单对象、历史 K 线和错误码 | TWS API |
| 只要下载日终报表、流水和成交确认 | Flex Web Service |
| 不想处理认证、会话、OAuth 或 Gateway | TWS API 也需要登录，但入门路径通常更直接。 |
认证和账户要求
Section titled “认证和账户要求”Web API 的认证方式会因为使用者身份不同而不同。
| 使用者 | 常见方向 |
|---|---|
| 个人用户 | 通常涉及 IBKR 用户名、密码和可用账户状态。 |
| 组织或机构 | 可能使用 OAuth 2.0、OAuth 1.0a、SSO 等方式，具体取决于账户结构和接入类型。 |
| 第三方开发者 | 通常需要官方审批、合规审核、协议和回调地址等配置。 |
对于普通个人开发者，最容易踩坑的是：Web API 不是一个“拿到公开 key 就随便调用”的普通行情接口。交易、账户、行情、订单这些能力都和 IBKR 用户、权限、订阅、会话状态有关。
常见 endpoint 分类
Section titled “常见 endpoint 分类”新版 Web API 文档会围绕工作流组织内容，Reference 则会展示具体 endpoint。入门阶段先理解这些分类即可：
| 分类 | 典型含义 |
|---|---|
/iserver/... | 和交易会话、行情、订单、执行记录等经纪业务功能相关。 |
/portfolio/... | 账户、组合、持仓、权益、保证金等数据。 |
/pa/... | PortfolioAnalyst 相关数据，例如绩效、摘要、交易记录等。 |
/fyi/... | FYI、通知、提示、订阅设置等消息类功能。 |
/tickle | 常用于保持或检查会话，并获取会话相关 token。 |
/logout | 结束会话。 |
这些路径不是让你现在背下来，而是帮助你读官方 Reference 时先判断“这个 endpoint 大概属于哪类业务”。
行情和订单的特点
Section titled “行情和订单的特点”Web API 也可以处理行情和订单，但它的表达方式和 TWS API 不一样。
行情常见概念：
| 概念 | 中文理解 |
|---|---|
conid | IBKR 内部合约 ID，用来唯一识别股票、期权、期货等工具。 |
fields | 需要返回的行情字段编号，例如价格、买卖价、成交量等。 |
| snapshot | 快照行情，一次请求返回当前可用字段。 |
| pre-flight | 某些行情快照前需要先发一次请求，让服务端开始准备该合约的数据流。 |
订单常见字段：
| 字段 | 中文理解 |
|---|---|
accountId | 下单账户 ID。 |
conid | 要交易的合约 ID。 |
side | 买卖方向，例如 BUY 或 SELL。 |
orderType | 订单类型，例如 LMT 限价单。 |
price | 限价或相关价格字段。 |
quantity | 数量。 |
tif | 订单有效期，例如 DAY。 |
order_id | Web API 返回的订单 ID，用于查询或撤单。 |
Web API 的订单提交一般是 HTTP POST 请求，请求体是 JSON。需要特别注意大小写、字段类型和订单风险提示。有些订单不会一次请求就直接生效，而是返回需要确认的 reply 消息。
请求结构说明
Section titled “请求结构说明”Web API 的请求由四部分组成：
| 部分 | 中文理解 | 例子 |
|---|---|---|
| Method | HTTP 方法 | GET 查询数据，POST 提交数据，DELETE 撤销或删除资源。 |
| Endpoint | 接口路径 | /portfolio/accounts、/iserver/account/{accountId}/orders。 |
| Authentication | 认证信息 | OAuth、会话、Cookie、Token 或签名，取决于接入方式。 |
| Body | 请求体 | 下单、改单等请求通常使用 JSON。 |
例如账户查询属于“无订单请求体”的查询类请求：
| 项目 | 内容 |
|---|---|
| Method | GET |
| Endpoint | /portfolio/accounts |
| Body | 无 |
| 返回重点 | 账户列表、账户 ID、账户类型等信息。 |
订单提交属于“带 JSON 请求体”的交易类请求：
| 项目 | 内容 |
|---|---|
| Method | POST |
| Endpoint | /iserver/account/{accountId}/orders |
| Body | 订单数组，包含 conid、side、orderType、quantity、tif 等字段。 |
| 返回重点 | order_id、订单状态，或需要二次确认的 reply 消息。 |
这类请求和 TWS API 的 EClient.placeOrder() 不同：Web API 通过 HTTP endpoint 和 JSON 表达请求，TWS API 通过本机 Socket 客户端对象发送消息。
需要特别注意
Section titled “需要特别注意”| 注意点 | 说明 |
|---|---|
| 会话限制 | 一个用户名在不同 IBKR 平台上的交易会话可能互相影响。 |
| 限频 | 官方 Web API 对认证用户和部分 endpoint 有请求频率限制，超限可能返回 429 Too Many Requests。 |
| 维护窗口 | Web API 和 /iserver 相关经纪业务功能会有维护和重置时间。 |
| 行情权限 | 是否能拿到实时行情仍取决于用户名的市场数据订阅和交易权限。 |
| Reference 不完整 | 官方 Swagger Reference 仍在补齐，遇到缺失时要结合长文档和旧入口阅读。 |
| 订单确认 | 下单可能返回需要二次确认的 reply 消息，不要只按 HTTP 状态码判断订单已经工作。 |
和 TWS API 怎么选
Section titled “和 TWS API 怎么选”如果你正在做的是中文开发者最常见的入门项目：
- Windows 本机已经登录 TWS
- 想用 Python 读取历史 K 线
- 想验证合约对象和订单对象
- 想在模拟账户里跑 WhatIf 或小规模调试
优先继续走 TWS API。
如果你要做的是正式 Web 系统、组织级接入、OAuth 授权、第三方平台或统一账户管理，再深入研究新版 Web API。它更适合系统集成，不一定适合作为第一天跑通交易脚本的入口。