ibkr

用途

本技能是使用 Python 通过 Interactive Brokers TWS API（基于 ib_async 库）构建、运行和调试交易系统的参考手册，覆盖股票、期权、期货、外汇、差价合约和加密货币。

其组织围绕一条核心规则：IBKR 的行为是“你的合约、你的账户实体、你的终端”的属性，而不是全局常量。大多数代价高昂的 IBKR 缺陷并非编码错误，而是正确代码建立在关于交易场所的未经验证假设之上。因此对任何问题的求证顺序为：

阅读能力列表。ContractDetails.orderTypes 声明该合约接受什么，许多问题到此即可免费解决。
阅读文档并引用原句。若无法在页面上找到该句，就不算有答案；绝不接受搜索引擎摘要作为证据。
在模拟 Gateway 上探测并保留记录。
记录答案及其来源与覆盖范围。

venue-questions-and-probes.md 是方法论，gateway-verification.md 是工具。

主要能力

基础：TWS API 架构、Gateway 与 TWS 对比、端口、clientId 策略、会话独占性、ib_async 设置、版本固定与实测差异。
合约与工具：各资产类别的合约构建、资格化、市场规则与实际生效的最小变动单位、各资产类别的数量语义、期权链、组合、whatToShow，以及各失败模式影响哪些类别的矩阵。
订单：订单类型、有效期（TIF）、成交模式与属性；括号订单（附加订单加 OCA、transmit 分阶段、每腿 TIF、OCA 类型与超额成交保护、触发方法、六种变体）；订单执行机制、execDetails、竞态条件、模拟交易注意事项；订单生命周期契约、判定窗口、placeOrder 返回值的含义、终端预设、净额平仓路径、归因。
诊断：错误码与判定（可拒绝订单的三层、ib_async 本地取消活动订单的评级步骤、已发布表的能与不能、如何给未见过的代码评级）；场所问题与探测（证据阶梯、来源标签、探测工具、文档未回答问题的常设登记表）；场所边界失败模式（适配层、异步拒绝入口、tick 一致性、依赖实体的合约路由、资格化生命周期、NaN 安全数量计算、场所到领域的验证边界）。
账户与数据：账户状态与盈亏（五个账户界面及其节奏、两个 PnL 数据源为何允许不一致、(account, conId) 键与缺失的平仓事件、Gateway 下当日执行限制、保证金与无保证金通知的强制平仓、前视风险标签、卖空可用性与静默 locate 冻结、Flex 作为对账来源）；事件驱动数据（订阅、K 线构建、限速、历史数据静默排查、会话重开占位 K 线、eventkit 监听器契约）。
运维：重连韧性（重连模式、isConnected() 僵尸状态、半开连接、监督进程自死、终端保留内容、Gateway 日志取证）；Gateway 自动化（计划停机窗口、IBC、多进程启动锁、Windows/Linux/macOS/Docker 部署）；Gateway 验证（配置一次性模拟 Gateway 并用其回答问题）。
数据资产：assets/tws-message-codes.tsv 收录全部 458 个已发布 TWS 消息码，每个都标注 ib_async 赋予的评级。

使用方式

快速开始要点：

连接：优先使用 IB Gateway（无头、更轻）而非 TWS。端口 4002 为模拟盘，4001 为实盘。生产环境使用离线独立构建，绝不使用自动更新器。
库：pip install "ib_async<3.0.0"（Python >= 3.10）。上界强制显式升级决策。
合约：进行资格化，拒绝 conId <= 0 的占位符，每次重连清空缓存。
价格：按市场规则区间的增量对齐，而非 minTick。
订单：每条腿显式设置 tif。将返回的 placeOrder 视为“已提交”，而非“已接受”。
错误：订阅 errorEvent、orderStatusEvent、openOrder，并将库的标准日志器接入你的接收端。四个通道都不可或缺。
韧性：disconnectedEvent 加带抖动的退避，并以主动探测而非 isConnected() 为门控。
验证：scripts/ibkr_gateway.py 配置模拟 Gateway；scripts/ibkr_probe.py 测量其行为。

工具脚本（S=${CLAUDE_PLUGIN_ROOT}/skills/ibkr/scripts）：

python $S/ibkr_gateway.py doctor              # 已安装内容、哪些端口开放
python $S/ibkr_gateway.py install             # 下载并安装 Gateway + IBC，无人值守
python $S/ibkr_gateway.py configure --user U  # 配置固定为模拟盘
python $S/ibkr_gateway.py start               # 无头启动，通过端口探测验证

python $S/ibkr_probe.py capabilities --stock AAPL       # 该合约真正允许什么
python $S/ibkr_probe.py shape --stock AAPL --type STP --tif GTC --attr allOrNone
python $S/ibkr_probe.py matrix --stock AAPL --types LMT,STP --tifs DAY,GTC,IOC
python $S/ibkr_probe.py bracket --stock AAPL --qty 1    # 生命周期、TIF 回读、预设检测
python $S/ibkr_probe.py codes 10256 10257 10349         # 无需 gateway

仅限模拟盘，双重强制：拒绝实盘端口，且连接后每个受管账户必须看起来像模拟账户。

适用场景

适合需要构建、运行或调试通过 IBKR TWS API 交易系统的 Python 开发者，尤其是遇到订单被拒、订单消失、保护腿过期、止损未触发、持仓翻倍、PnL 无法对账、保证金滞后、成交缺失、事件丢失、连接假死、Gateway 启动冲突等问题时。文档提供了“症状到入口”的对照表，便于快速定位应阅读的章节。

限制

仅限模拟盘（paper）使用，工具会拒绝实盘端口。
依赖 Python >= 3.10 与 ib_async<3.0.0。
部分问题 IBKR 文档并未回答，需通过探测登记表记录。
关于收费、价格、具体平台支持范围等事实，资料未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制