IBKR API 总览

IBKR 提供多种 API。本站重点写 TWS API，因为它最适合做程序化交易、行情读取、历史 K 线、账户查询和模拟订单测试，也适合作为编程 Agent 通过 MCP 查询的中文文档基础。

TWS API 的核心不是普通网页接口，而是一个连接到 Trader Workstation（TWS） 或 IB Gateway 的 Socket API。也就是说，程序并不是直接连 IBKR 官网服务器，而是先连接你本机或服务器上已经登录好的 TWS / IB Gateway，再由它和 IBKR 后端通信。

官方资料入口

官方资料建议这样看：

资料	作用
IBKR Campus - TWS API	新版官方入口，适合查看当前 API 分类和官方说明。
TWS API Documentation	TWS API 详细文档，查看连接、行情、订单、账户、合约等章节。
TWS API Reference	类、方法、回调和字段参考，适合查参数含义。

本站不会逐字翻译官方文档，而是把官方规则整理成中文实战说明：什么时候用哪个接口、字段是什么意思、常见错误怎么排查、示例代码怎么跑通。

新手先理解这条链路

用户自己的 Python 程序 / 交易系统
        ↓
本机或服务器上的 TWS / IB Gateway
        ↓
IBKR 后端

最容易误解的一点是：TWS API 不是 REST API。它不是一个可以直接在浏览器地址栏访问的接口。

TWS API 通常连接：

环境	常见端口	说明
TWS 模拟账户	7497	本地开发最常用，适合先跑通连接、行情、历史数据、WhatIf 订单。
TWS 实盘账户	7496	真实交易环境，后期必须增加保护和确认机制。
IB Gateway 模拟账户	4002	更适合服务器长期运行。
IB Gateway 实盘账户	4001	服务器实盘环境，风险更高。

本站当前优先讲 TWS 模拟账户 + 7497 的开发方式。

示例代码怎么读

每个接口页会尽量按同一种结构写。只要安装 IBKR Python API，就可以复制示例代码，在自己的电脑上连接自己的 TWS / IB Gateway。

每个接口页会尽量包含：

内容	说明
请求方法	例如 reqCurrentTime()、reqHistoricalData()、placeOrder()。
回调方法	例如 currentTime()、historicalData()、openOrder()。
参数解释	保留英文参数名，并用中文解释含义、常见取值和坑点。
Python 示例	尽量给完整可运行代码，示例变量保持英文，注释使用中文。
返回结果	说明正常会收到什么回调，输出大概长什么样。
常见错误	解释连接失败、权限不足、行情订阅不足、限频等问题。
验证建议	说明这个接口适合怎样在自己的 TWS / IB Gateway 环境里验证。

例如最小连接测试会长这样：

from ibapi.client import EClient
from ibapi.wrapper import EWrapper


class DemoApp(EWrapper, EClient):
    def __init__(self):
        EClient.__init__(self, self)

    def nextValidId(self, orderId: int):
        # 收到 nextValidId 通常表示连接已经准备好，可以开始发送请求。
        self.reqCurrentTime()

    def currentTime(self, time_: int):
        # TWS 返回的服务器时间，格式是 Unix 时间戳。
        print("服务器时间:", time_)
        self.disconnect()


app = DemoApp()
app.connect("127.0.0.1", 7497, clientId=901)
app.run()

如果成功，会看到类似：

服务器时间: 1710000000

这说明三件事：

看到的结果	含义
Socket 能连上	TWS 的 API 设置和端口基本正确。
收到 nextValidId	TWS 已经接受这个 API 客户端。
收到 currentTime	请求和回调链路已经通了。

为什么要等 nextValidId

官方示例里经常先连接，再等待 nextValidId 回调。新手可以先这样理解：

nextValidId 是 TWS 告诉你的程序：“连接已经准备好，你可以开始发请求了。”

如果程序刚 connect() 就马上请求行情或下单，有些请求可能在连接完全准备好之前发出去，导致没有返回或者行为不稳定。所以示例代码里会等 nextValidId 后再请求服务器时间、合约详情、行情或订单预览。

浏览器能不能直接连 Windows 的 TWS 接口？

结论：不能直接连。

原因很简单：

限制	解释
浏览器不能直接打开普通 TCP Socket	TWS API 是 TCP Socket 协议，不是浏览器可直接调用的 HTTP 接口。
TWS 不是 WebSocket 服务	浏览器可以连 WebSocket，但 TWS 的 7497 端口不是 WebSocket。
远程网页不能安全地操作用户本机交易端	即使是模拟账户，也需要明确的本地授权和连接器边界。

所以浏览器页面本身不能直接调用 TWS API。真正开发时，建议把示例代码复制到自己的 Python 项目里运行，由 Python 程序连接 TWS Socket：

Python 示例代码
  ↓ TWS Socket
TWS / IB Gateway

如果要把这些能力封装成自己的交易系统，通常应由后端服务连接 TWS / IB Gateway，再由网页调用后端服务。当前版本不做网页按钮式连接功能，重点放在清楚解释接口、参数、返回和常见错误。

适合先本地验证的请求包括：

功能	本地验证方式
测试连接	调用 reqCurrentTime()，确认能收到服务器时间。
合约详情查询	调用 reqContractDetails()，确认合约定义唯一。
历史 K 线	调用 reqHistoricalData()，确认行情权限和参数正确。
WhatIf 订单预览	构造 Order，设置 whatIf=True，检查保证金和风险提示。