ibkr-api-skill

name: ibkr-api-skill description: Interactive Brokers (IBKR) API integration for portfolio management, account queries, and trade execution across multiple account types (Roth IRA, personal brokerage, business). Use when the user mentions IBKR, Interactive Brokers, IB Gateway, TWS API, Client Portal API, brokerage API, portfolio positions, account balances, placing trades via API, multi-account trading, IRA trading restrictions, or wants to build/debug code that connects to Interactive Brokers. Also triggers on "ib_async", "ib_insync", "ibapi", or any IBKR endpoint reference.

Quick Decision: Which API?

Default recommendation: TWS API via ib_async library for all programmatic work.

Account Architecture

Tim's setup: Roth IRA + Personal Brokerage + THK Enterprises (future business account)

• All linked under single IBKR username/password
• Single API session accesses all linked accounts
• Use reqLinkedAccounts() to enumerate account IDs
• Specify account ID per order placement
• Market data subscriptions charged once across all linked accounts
• One active session per username — connecting elsewhere closes current session

IRA-Specific Restrictions (Critical)

Core API Operations

Read Operations (Safe — use for all account types)

# 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

Write Operations (Use with caution — respect IRA restrictions)

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

Client Portal REST Endpoints (Alternative)

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 Library: ib_async

Install: pip install ib_async

Why ib_async over alternatives:

• Modern successor to ib_insync (original creator's project continued)
• Native asyncio support
• Implements IBKR binary protocol internally (no need for official ibapi)
• Active maintenance (GitHub: ib-api-reloaded/ib_async)

Alternatives (use only if ib_async doesn't meet needs):

• ib_insync — Legacy, stable but unmaintained since early 2024
• ibapi — Official IBKR library, cumbersome event loop

Reference: Connection Pattern

See reference/connection-patterns.md for:

• IB Gateway setup and configuration
• Connection/reconnection handling
• Session timeout management (6-min ping for CP API)
• Multi-account query patterns
• Error handling and rate limit management

Reference: Trading Patterns

See reference/trading-patterns.md for:

• Order types (market, limit, stop, bracket, IB algos)
• IRA-safe order validation
• Multi-account order routing
• Position sizing with account-type awareness
• Greeks-aware options order flow

Infrastructure Requirements

1. IB Gateway (lightweight) or TWS (full UI) running locally
2. Java 8+ installed
3. API enabled in TWS/Gateway settings
4. Ports: 7496 (live) / 7497 (paper trading)
5. Credentials: Stored in OS credential manager (never hardcode)

Security Best Practices

• Run IB Gateway on localhost only (no internet exposure)
• Use read-only login for portfolio queries when trading not needed
• Store credentials in macOS Keychain / Linux secret-service
• Implement session timeout handling
• Validate market data subscriptions before placing orders
• Log all order attempts with account ID + timestamp

Cost Structure

Integration with Trading-Signals Skill

This skill complements the trading-signals-skill:

• trading-signals → generates signals, confluence scores, regime detection
• ibkr-api → executes trades, queries positions, manages accounts
• Pipeline: Signal generation → Position sizing → IRA validation → Order execution

IBKR MCP Server (Installed)

ArjunDivecha/ibkr-mcp-server is installed and configured:

• Location: ~/Desktop/tk_projects/ibkr-mcp-server/
• Claude Code: Added to ~/.claude.json (user scope)
• Claude Desktop: Added to claude_desktop_config.json
• Mode: Paper trading (port 7497), live trading disabled
• Safety: Order cap 1,000 shares, confirmation required

Available MCP Tools

To Activate

1. Start IB Gateway → port 7497 (paper) or 7496 (live)
2. Enable API: Config → API → Settings → "ActiveX and Socket Clients"
3. Add 127.0.0.1 to Trusted IPs
4. Restart Claude Code / Claude Desktop

Other Community MCP Servers

• code-rabi/interactive-brokers-mcp — Client Portal REST API
• xiao81/IBKR-MCP-Server — TWS API focused
• Hellek1/ib-mcp — Read-only via ib_async (safest)

Multi-Broker Aggregation

For unified view across IBKR + Robinhood:

• SnapTrade MCP (dangelov/mcp-snaptrade) — Read-only aggregator, 15+ brokerages, OAuth-based (safe)
• Alpaca MCP (official) — Alternative broker with production-ready MCP
• Manual CSV import from Robinhood as fallback (ToS-safe)

See reference/multi-broker-strategy.md for aggregation patterns.

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-ibkr-api.json:

{"ts":"[UTC ISO8601]","skill":"ibkr-api","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]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.