我应该使用哪种 API？

IBKR 的 API 不止一种。选错入口会让开发过程变得很绕：有的 API 适合本地程序化交易，有的适合 Web 系统，有的只适合报表和流水查询。

如果你是第一次接触 IBKR API，可以先用一句话判断：

要做本地策略、行情、订单和账户查询，优先从 TWS API 开始；要做标准 HTTP/WebSocket 集成，再看 Client Portal Web API 或新版 Web API；只取报表和对账数据，用 Flex Web Service。

官方 API 分类

官方资料主要分为以下几类：

API	主要用途	入口
TWS API	通过本机或服务器上的 TWS / IB Gateway 连接交易、行情、账户和订单功能。	TWS API Documentation
Client Portal Web API	通过 HTTP 和 WebSocket 使用交易、行情、扫描器、组合和账户功能。	Web API v1.0 Documentation
Web API	IBKR 正在整理的新一代统一 Web API 文档，把 Client Portal Web API、账户管理和 Flex 相关能力放到同一个文档体系里。	Web API Documentation
Flex Web Service	通过 HTTP 生成和下载已经配置好的 Flex 报表，适合对账、流水、成交确认和审计数据。	Flex Web Service

官方还有 FIX、Excel 等接口。它们适合更特定的场景，本教程先把最常见的开发入口讲清楚。

快速选择

你的需求	推荐 API	原因
写 Python 策略，读取行情，下单，查账户和持仓	TWS API	功能覆盖完整，适合程序化交易和本地开发。
在 Windows 本机连接已经登录的 TWS	TWS API	直接连接 127.0.0.1:7497，最适合新项目先跑通。
在 Linux 服务器上长期运行连接	TWS API + IB Gateway	IB Gateway 更适合服务器运行，但仍然需要处理登录、重连和每日重置。
做 Web 后台，希望用 HTTP 请求和 WebSocket	Client Portal Web API / Web API	更接近普通 Web 开发习惯，不是 TWS Socket 协议。
下载日终报表、流水、成交确认、审计数据	Flex Web Service	它本来就是报表接口，不适合实时交易轮询。
只想先验证股票、期权、期货合约和订单对象	TWS API	官方 Python 示例和社区资料最多，调试路径清晰。

TWS API 适合什么

TWS API 是本站文档的主线。它通过 TCP Socket 连接已经登录的 TWS 或 IB Gateway。

适合：

• 本地 Python / Java / C++ / C# 程序化交易
• 实时行情、历史 K 线、合约详情查询
• 下单、撤单、订单状态监听
• 账户、持仓、盈亏和执行记录查询
• 模拟账户里的 WhatIf 订单预览和策略验证

不适合：

• 纯浏览器直接调用
• 不想安装或运行 TWS / IB Gateway 的场景
• 希望完全使用标准 REST API 的系统

TWS API 的典型链路是：

Python 程序
  ↓ TCP Socket
TWS / IB Gateway
  ↓
IBKR 后端

所以它开发起来更像“连接一个本地交易终端”，而不是“请求一个云端 HTTP 地址”。

Client Portal Web API 适合什么

Client Portal Web API 更接近普通 Web 开发：使用 HTTP 请求和 WebSocket 通信。它适合已经习惯 REST/WebSocket 的开发者，也适合一些 Web 后台和服务端系统。

适合：

• HTTP 接口风格的账户、行情、订单和组合查询
• Web 系统或服务端集成
• 不想直接处理 TWS API Socket 消息模型的团队

需要注意：

• 它通常需要 Client Portal Gateway 或对应的认证流程。
• 和 TWS API 可用的功能、订单类型、数据表现不完全一样。
• 官方部分资料正在向新版 Web API 体系迁移，阅读时要注意文档版本。

如果官方示例使用 curl、HTTP endpoint、WebSocket topic，一般就是 Web API / Client Portal Web API 这一类。

Web API 适合什么

新版 Web API 是 IBKR 正在整理的统一文档体系，目标是把 Client Portal Web API、账户管理相关 API 和 Flex Web Service 放到更统一的认证和文档结构中。

适合：

• 新项目希望跟随官方 Web API 方向
• 需要统一理解 HTTP endpoint、OAuth 和 WebSocket 的团队
• 做第三方平台、组织级接入或更标准化的 Web 服务集成

需要注意：

• 官方 Reference 里有些内容仍在补齐。
• 已有 Client Portal Web API、账户管理和 Flex 的旧入口仍然有参考价值。
• 如果目标是先用 Python 跑通本地模拟账户交易，TWS API 通常更直接。

Flex Web Service 适合什么

Flex Web Service 不是实时交易接口。它用于生成和下载已经在 Client Portal 里配置好的 Flex Queries。

适合：

• 日终对账
• 成交确认
• 活动报表
• 审计流水
• 财务和运营系统同步数据

不适合：

• 高频查询
• 实时行情
• 实时下单
• 每秒轮询账户变化

官方也提醒，某些 Flex 报表数据不会在一天内频繁更新，所以它更适合按日或按需拉取，不适合作为实时数据源。

本站为什么主讲 TWS API

对中文开发者来说，最常见的需求是：

• 在本机连接模拟账户
• 先确认 TWS 设置是否正确
• 用 Python 拉行情和历史 K 线
• 构造合约对象
• 测试订单对象
• 处理错误码和限频

这些问题都和 TWS API 强相关。因此本站优先把 TWS API 写扎实，同时把 Web API、Client Portal Web API 和 Flex Web Service 放在独立目录中说明，避免把不同协议的示例混在一起。

选择建议

如果你还不确定，按下面的顺序选：

1. 你要写本地或服务器上的交易程序：选 TWS API。
2. 你要做 HTTP/WebSocket 风格的 Web 集成：看 Client Portal Web API 或新版 Web API。
3. 你只需要报表、流水和对账文件：选 Flex Web Service。
4. 你是机构级低延迟或专线场景：再单独评估 FIX。

大多数个人开发者和中小型策略系统，第一步从 TWS API + 模拟账户 + Python 示例 开始最稳。