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:

Keepalive cron - Ping /v1/api/tickle every 5 min
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.

ibkr-trading