ibkr-trading – OpenClaw Skill

---

name: ibkr-trading description: Interactive Brokers (IBKR) trading automation via Client Portal API. Use when setting up IBKR account access, authenticating sessions, checking portfolio/positions, or building trading bots. Handles IBeam automated login with IBKR Key 2FA.

IBKR Trading Skill

Automate trading with Interactive Brokers using the Client Portal Gateway API.

Overview

This skill enables:

• Automated IBKR authentication via IBeam + IBKR Key
• Portfolio and position monitoring
• Order placement and management
• Building custom trading strategies

Prerequisites

• IBKR account (live or paper)
• IBKR Key app installed on phone (for 2FA)
• Linux server with Java 11+ and Chrome/Chromium

Quick Setup

1. Install Dependencies

# Java (for Client Portal Gateway)
sudo apt-get install -y openjdk-17-jre-headless

# Chrome + ChromeDriver (for IBeam)
sudo apt-get install -y chromium-browser chromium-chromedriver

# Virtual display (headless auth)
sudo apt-get install -y xvfb

# Python venv
python3 -m venv ~/trading/venv
source ~/trading/venv/bin/activate
pip install ibeam requests

2. Download Client Portal Gateway

cd ~/trading
wget https://download2.interactivebrokers.com/portal/clientportal.gw.zip
unzip clientportal.gw.zip -d clientportal

3. Configure Credentials

Create ~/trading/.env:

IBEAM_ACCOUNT=your_username
IBEAM_PASSWORD='your_password'
IBEAM_GATEWAY_DIR=/path/to/trading/clientportal
IBEAM_CHROME_DRIVER_PATH=/usr/bin/chromedriver
IBEAM_TWO_FA_SELECT_TARGET="IB Key"

Authentication

Start Gateway + Authenticate

# 1. Start Client Portal Gateway
cd ~/trading/clientportal && bash bin/run.sh root/conf.yaml &

# 2. Wait for startup (~20 sec)
sleep 20

# 3. Run IBeam authentication
cd ~/trading
source venv/bin/activate
source .env
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 &
python -m ibeam --authenticate

Important: User must approve IBKR Key notification on phone within ~2 minutes!

Check Auth Status

curl -sk https://localhost:5000/v1/api/iserver/auth/status

Authenticated response includes "authenticated": true.

API Usage

Account Info

# List accounts
curl -sk https://localhost:5000/v1/api/portfolio/accounts

# Account summary
curl -sk "https://localhost:5000/v1/api/portfolio/{accountId}/summary"

Positions

# Current positions
curl -sk "https://localhost:5000/v1/api/portfolio/{accountId}/positions/0"

Market Data

# Search for symbol
curl -sk "https://localhost:5000/v1/api/iserver/secdef/search?symbol=AAPL"

# Get quote (after searching)
curl -sk "https://localhost:5000/v1/api/iserver/marketdata/snapshot?conids=265598&fields=31,84,86"

Place Orders

curl -sk -X POST "https://localhost:5000/v1/api/iserver/account/{accountId}/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [{
      "conid": 265598,
      "orderType": "MKT",
      "side": "BUY",
      "quantity": 1,
      "tif": "DAY"
    }]
  }'

Session Management

Sessions expire after ~24 hours. Options:

1. Keepalive cron - Ping /v1/api/tickle every 5 min
2. Auto re-auth - Run IBeam when session expires (requires phone approval)

Keepalive Script

import requests
import urllib3
urllib3.disable_warnings()

def keepalive():
    try:
        r = requests.post("https://localhost:5000/v1/api/tickle", verify=False, timeout=10)
        status = requests.get("https://localhost:5000/v1/api/iserver/auth/status", verify=False, timeout=10)
        return status.json().get("authenticated", False)
    except:
        return False

Troubleshooting

Issue	Solution
Gateway not responding	Check if Java process is running: ps aux | grep GatewayStart
Login timeout	User didn't approve IBKR Key in time - retry auth
Connection refused	Gateway not started - run bin/run.sh root/conf.yaml
Chrome errors	Ensure Xvfb is running: Xvfb :99 & and export DISPLAY=:99

Files Reference

See references/api-endpoints.md for complete API documentation. See scripts/ for ready-to-use automation scripts.