ibkr-api-skill

使用 TWS API（ib_async）或 Client Portal REST API，构建和管理 Interactive Brokers（IBKR）集成，用于投资组合查询、交易执行，以及跨 Roth IRA、个人经纪账户和企业账户的多账户管理。

<quick_start>

1. 安装：pip install ib_async
2. 在端口 7497（模拟）或 7496（实盘）启动 IB Gateway
3. 连接：ib = IB(); await ib.connectAsync('127.0.0.1', 7497, clientId=1)
4. 查询：positions = ib.positions() / summary = await ib.accountSummaryAsync() </quick_start>

<success_criteria>

• API 连接已建立并通过身份验证
• 已获取所有关联账户的投资组合持仓和余额
• 写入操作遵守 IRA 限制
• 凭证已安全存储（绝不硬编码） </success_criteria>

快速选择：使用哪个 API？

标准	TWS API（推荐）	Client Portal REST API
最适合	自动化交易、投资组合管理	Web 仪表板、轻量级使用
身份验证	通过 TWS/IB Gateway 本地登录	OAuth 2.0 JWT
性能	异步、低延迟、高吞吐量	REST，速度较慢
数据质量	可获取逐笔数据	仅 Level 1
多账户	同时访问所有账户	每个请求单独处理
基础设施	本地 Java 应用（端口 7496/7497）	HTTPS REST 调用
Python 库	ib_async（推荐）	requests + OAuth
费用	免费	免费

默认建议：所有程序化操作均通过 ib_async 库使用 TWS API。

账户架构

Tim 的设置：Roth IRA + 个人经纪账户 + THK Enterprises（未来的企业账户）

• 所有账户关联到同一个 IBKR 用户名/密码下
• 单个 API 会话可访问所有关联账户
• 使用 reqLinkedAccounts() 枚举账户 ID
• 下单时指定账户 ID
• 所有关联账户仅收取一次市场数据订阅费用
• 每个用户名只能有一个活动会话——在其他位置连接会关闭当前会话

IRA 特定限制（重要）

限制	影响
禁止卖空	placeOrder() 会拒绝卖空订单
禁止保证金借款	仅限现金（不得有借方余额）
禁止借入外币	必须先执行外汇交易
期货保证金高出 2 倍	会影响头寸规模
禁止 MLP/UBTI	将其从 IRA 订单流中过滤掉
仅限美元提款	仅供参考

核心 API 操作

读取操作（安全——适用于所有账户类型）

# Key TWS API functions for portfolio queries
reqLinkedAccounts()        # List all account IDs
reqAccountSummary()        # Balances, buying power, equity (all accounts)
reqPositions()             # Current positions (up to 50 sub-accounts)
reqPositionsMulti()        # Per-account positions (>50 sub-accounts)
reqAccountUpdates()        # Stream account + position data (single account)
reqMktData()               # Real-time Level 1 market data
reqHistoricalData()        # Historical price data

写入操作（谨慎使用——遵守 IRA 限制）

placeOrder(account_id, contract, order)  # Place order on specific account
cancelOrder(order_id)                     # Cancel pending order
reqGlobalCancel()                         # Cancel all open orders

Client Portal REST 端点（替代方案）

GET  /iserver/accounts                        # List accounts
GET  /iserver/account/{id}/positions          # Positions
GET  /iserver/account/{id}/summary            # Balances
POST /iserver/account/{id}/orders             # Place order
GET  /market/candle                           # Historical candles

Python 库：ib_async

安装：pip install ib_async

选择 ib_async 而非其他方案的原因：

• ib_insync 的现代继任者（原作者的项目仍在持续开发）
• 原生支持 asyncio
• 在内部实现 IBKR 二进制协议（无需官方 ibapi）
• 持续维护（GitHub：ib-api-reloaded/ib_async）

替代方案（仅在 ib_async 无法满足需求时使用）：

• ib_insync——旧版，稳定，但自 2024 年初起无人维护
• ibapi——IBKR 官方库，事件循环使用繁琐

参考：连接模式

参见 reference/connection-patterns.md，了解：

• IB Gateway 的设置和配置
• 连接/重新连接处理
• 会话超时管理（CP API 每 6 分钟 ping 一次）
• 多账户查询模式
• 错误处理和速率限制管理

参考：交易模式

参见 reference/trading-patterns.md，了解：

• 订单类型（市价、限价、止损、括号单、IB 算法）
• 符合 IRA 规定的订单验证
• 多账户订单路由
• 考虑账户类型的头寸规模计算
• 考虑希腊值的期权订单流

基础设施要求

1. IB Gateway（轻量级）或 TWS（完整 UI）在本地运行
2. 已安装 Java 8+
3. 在 TWS/Gateway 设置中启用 API
4. 端口：7496（实盘）/ 7497（模拟交易）
5. 凭据：存储在操作系统凭据管理器中（切勿硬编码）

安全最佳实践

• 仅在 localhost 上运行 IB Gateway（不暴露到互联网）
• 无需交易时，使用只读登录查询投资组合
• 将凭据存储在 macOS Keychain / Linux secret-service 中
• 实现会话超时处理
• 下单前验证市场数据订阅
• 记录所有下单尝试，并包含账户 ID 和时间戳

费用结构

项目	费用
API 访问	免费
市场数据	每个交易所订阅每月 $5-50
交易佣金	IBKR 标准费率（因资产而异）
账户最低金额	每个账户 $500
预估总计	合计最低约 $1,500；数据费用每月 $15-50

与 Trading-Signals Skill 集成

此技能可与 trading-signals-skill 配合使用：

• trading-signals → 生成信号、融合评分、市场状态检测
• ibkr-api → 执行交易、查询持仓、管理账户
• 流程：信号生成 → 仓位规模计算 → IRA 验证 → 订单执行

IBKR MCP 服务（已安装）

ArjunDivecha/ibkr-mcp-server 已安装并配置：

• 位置： ~/Desktop/tk_projects/ibkr-mcp-server/
• Claude Code： 已添加到 ~/.claude.json（用户范围）
• Claude Desktop： 已添加到 claude_desktop_config.json
• 模式： 模拟交易（端口 7497），已禁用实盘交易
• 安全措施： 订单上限为 1,000 股，需确认

可用的 MCP 工具

工具	用途	账户类型
get_portfolio	持仓 + 盈亏	所有账户
get_account_summary	余额、保证金、购买力	所有账户
switch_account	切换 Roth IRA / 个人 / THK	多账户
get_market_data	实时行情	不适用
get_historical_data	历史 OHLCV	不适用
place_order	带安全检查的订单	所有账户（强制执行 IRA 限制）
check_shortable_shares	可卖空情况	仅个人/企业账户
get_margin_requirements	各证券的保证金要求	仅个人/企业账户
get_borrow_rates	卖空借券成本	仅个人/企业账户
short_selling_analysis	完整的卖空分析包	仅个人/企业账户
get_connection_status	IB Gateway 健康检查	不适用

启用方法

1. 启动 IB Gateway → 端口 7497（模拟）或 7496（实盘）
2. 启用 API：Config → API → Settings → "ActiveX and Socket Clients"
3. 将 127.0.0.1 添加到 Trusted IPs
4. 重启 Claude Code / Claude Desktop

其他社区 MCP 服务

• code-rabi/interactive-brokers-mcp — Client Portal REST API
• xiao81/IBKR-MCP-Server — 专注于 TWS API
• Hellek1/ib-mcp — 通过 ib_async 提供只读功能（最安全）

多券商聚合

要统一查看 IBKR + Robinhood 账户：

• SnapTrade MCP（dangelov/mcp-snaptrade）— 只读聚合器，支持 15 家以上券商，基于 OAuth（安全）
• Alpaca MCP（官方）— 具备生产就绪 MCP 的替代券商
• 从 Robinhood 手动导入 CSV，作为后备方案（符合服务条款）

请参阅 reference/multi-broker-strategy.md 了解聚合模式。

输出结果 Sidecar

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-ibkr-api-skill.json：

{"ts":"[UTC ISO8601]","skill":"ibkr-api-skill","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"queries_executed":[n],"positions_analyzed":[n],"accounts_checked":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但仍生成了结果，请使用状态 "partial"。仅当未生成任何输出时，才使用 "error"。