ibkr-openclaw

# IBKR + OpenClaw Integration Connect OpenClaw to your Interactive Brokers account for live portfolio monitoring, real-time quotes, technical analysis, and automated Telegram alerts. ## Features - **Live account data** — NAV, cash, P&L, buying power - **Positions** — all holdings with avg cost and exchange - **Real-time quotes** — delayed or live market data - **Historical K-lines** — daily OHLCV data for technical analysis - **Technical indicators** — RSI, MACD, Bollinger Bands, ATR, MA (via ib_async) - **Read-only safe** — API configured for read-only access ## Prerequisites - Interactive Brokers account (live or paper) - IBKR Mobile app (for 2FA approval) - Docker & Docker Compose installed on your server - Python 3.9+ with `ib_async` and `pandas` ## Setup Guide ### Step 1: Install Docker ```bash curl -fsSL https://get.docker.com | sh docker --version docker compose version ``` ### Step 2: Clone IB Gateway Docker The IB Gateway runs in a Docker container based on [gnzsnz/ib-gateway-docker](https://github.com/gnzsnz/ib-gateway-docker). ```bash cd ~/.openclaw/workspace git clone https://github.com/gnzsnz/ib-gateway-docker.git cd ib-gateway-docker ``` ### Step 3: Configure Environment Create a `.env` file in the `ib-gateway-docker` directory: ```env # IBKR Account TWS_USERID=your_username TWS_PASSWORD=your_password # Trading mode: live or paper TRADING_MODE=live # Read-only API (recommended for monitoring) READ_ONLY_API=yes # API settings TWS_ACCEPT_INCOMING=auto TWS_MASTER_CLIENT_ID=1 # 2FA device name (find in IBKR web portal → Settings → Security) TWOFA_DEVICE=IB Key # 2FA timeout TWOFA_TIMEOUT_ACTION=exit # Timezone TIME_ZONE=Asia/Singapore TZ=Asia/Singapore # VNC password (optional, for remote desktop) VNC_SERVER_PASSWORD=your_password # Auto restart (daily maintenance) AUTO_RESTART_TIME=23:45 # Save settings between restarts SAVE_TWS_SETTINGS=yes ``` **Important:** Find your `TWOFA_DEVICE` name in your IBKR web portal under: Settings → Security → Second Factor Authentication → Devices ### Step 4: Start the Container ```bash docker compose up -d ``` Check logs: ```bash docker logs algo-trader-ib-gateway-1 --tail 20 ``` ### Step 5: Approve 2FA The Gateway will prompt for 2FA. Approve the notification on your **IBKR Mobile app**. Once connected, the API is available on: - **Port 4001** → Paper trading API - **Port 4002** → Live trading API (read-only if configured) ### Step 6: Install Python Dependencies ```bash pip install ib_async pandas ``` ### Step 7: Test the Connection ```bash python3 ~/.openclaw/workspace/skills/ibkr-openclaw/scripts/ibkr_client.py summary --port 4001 ``` Expected output: ``` Account: ['DU1234567'] ---------------------------------------- BuyingPower.............. 500,000.00 NetLiquidation........... 125,000.00 TotalCashValue........... 25,000.00 StockMarketValue......... 100,000.00 FuturesPNL............... -500.00 UnrealizedPnL............ 3,200.00 ``` ## CLI Usage ### ibkr_client.py — Account, Positions & Quotes ```bash # Account summary python3 scripts/ibkr_client.py summary --port 4001 # All positions python3 scripts/ibkr_client.py positions --port 4001 # Quick NAV python3 scripts/ibkr_client.py nav --port 4001 # Quote a stock python3 scripts/ibkr_client.py quote 2800 --exchange SEHK --currency HKD --port 4001 ``` ### Getting Historical Data (Python) ```python from ib_async import IB, Stock ib = IB() ib.connect('127.0.0.1', 4001, clientId=1, readonly=True) contract = Stock('2800', 'SEHK', 'HKD', primaryExchange='SEHK') qualified = ib.qualifyContracts(contract) bars = ib.reqHistoricalData( qualified[0], '', '6 M', '1 day', 'TRADES', True, 1 ) for bar in bars[-5:]: print(f"{bar.date} O:{bar.open} H:{bar.high} L:{bar.low} C:{bar.close} V:{bar.volume}") ib.disconnect() ``` ## API Port Reference | Port | Mode | Description | |---|---|---| | 4001 | Paper | Paper trading API | | 4002 | Live | Live trading API | | 5900 | VNC | Remote desktop (if VNC enabled) | ## Troubleshooting ### 2FA not arriving - Check IBKR Mobile app is logged in with the correct username - Verify `TWOFA_DEVICE` matches your device name in IBKR web portal - Check phone notification settings for IBKR app ### Connection timeout - Ensure the container is running: `docker ps` - Check logs: `docker logs algo-trader-ib-gateway-1 --tail 20` - The Gateway restarts daily at 23:45 SGT (configured via `AUTO_RESTART_TIME`) ### Read-only errors - `READ_ONLY_API=yes` prevents trading but allows all read queries - Some ib_async features auto-request write access — ignore those errors - Account summary and positions work fine in read-only mode ### Container won't start - Check `.env` file has correct credentials - Ensure ports 4001, 4002, 5900 are not in use: `netstat -tlnp | grep 400` - Try recreating: `docker compose up -d --force-recreate` ## Security Notes - `.env` contains your IBKR password in plain text — keep it secure - `READ_ONLY_API=yes` prevents accidental trades - VNC is bound to `127.0.0.1` (localhost only) by default - The container auto-restarts daily to maintain connection ## Architecture ``` ┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ │ OpenClaw │────►│ ibkr_client.py │────►│ IB Gateway │ │ Agent │ │ (ib_async) │ │ (Docker) │ └─────────────┘ └──────────────────┘ └──────┬──────┘ │ ┌──────▼──────┐ │ IBKR Servers│ │ (live data) │ └─────────────┘ ``` ## Credits - [gnzsnz/ib-gateway-docker](https://github.com/gnzsnz/ib-gateway-docker) — IB Gateway Docker image - [ib_async](https://github.com/ib-api-reloaded/ib_async) — Python IBKR API wrapper (maintained fork of ib_insync)