IBKR Trading

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.

Security Scan

The skill is largely what it claims (IBKR Client Portal automation), but the published metadata omits the sensitive credentials and local system requirements the skill actually needs — that mismatch and the scripts' handling of secrets and automated re-auth are concerning and worth review before installing.

Purpose & Capability

The skill's name/description match the included code and instructions (IBKR Client Portal + IBeam automation). However the registry metadata declares no required environment variables, no credentials, and no required binaries, while the SKILL.md and scripts clearly require Java, Chrome/Chromium + chromedriver, Xvfb, a Python venv, and explicit IBKR credentials (IBEAM_ACCOUNT, IBEAM_PASSWORD, IBKR/IBEAM-related envs). The manifest omission is an incoherence: a trading automation skill legitimately needs those local binaries and credentials, so they should be declared.

Instruction Scope

The runtime instructions and scripts direct the agent/user to download and run the IBKR Client Portal Gateway, run ibeam to perform automated login, create a plaintext ~/.env containing IBEAM_ACCOUNT and IBEAM_PASSWORD, start Xvfb, and schedule a cron keepalive that may trigger re-auth. All actions are within the stated purpose, but the instructions ask the user to store credentials in plaintext and repeatedly automate 2FA approval flows; the SKILL.md does not explicitly call out the sensitive nature of these steps. The keepalive script will automatically call authenticate.sh if the session expires, which may repeatedly launch auth flows (requiring phone approval).

Install Mechanism

There is no packaged install spec, but the setup.sh downloads the Client Portal Gateway from download2.interactivebrokers.com (an official-looking IBKR domain) and installs Python packages via pip (ibeam, requests, urllib3). No obfuscated download URLs, no pastebin/shorteners, and ZIP extraction is from an official host — this is expected for this use case. Still: users should verify the official download URL and, if possible, checksum/signature of the archive.

Credentials

The published skill declares no required env vars or primary credential, but the instructions and scripts require multiple sensitive environment variables (IBEAM_ACCOUNT, IBEAM_PASSWORD, IBEAM_GATEWAY_DIR, IBEAM_CHROME_DRIVER_PATH, IBEAM_TWO_FA_SELECT_TARGET, IBKR account id via IBKR_ACCOUNT_ID or runtime discovery). Requiring account credentials and account IDs is proportionate for a trading automation skill, but the metadata omission is a significant inconsistency. The scripts also recommend disabling TLS verification (verify=False / curl -k) for connections to the gateway (self-signed cert) — acceptable technically but increases risk if networking is not trusted.

Persistence & Privilege

The skill does not request always:true or system-wide privilege. It includes a keepalive script intended to be run via cron (user-controlled) that will call local endpoints and, if needed, spawn the authenticate script. That behavior is consistent with session management for trading automation. There is no attempt to modify other skills or global agent configuration.

What to consider before installing

Key points to consider before installing: - Metadata mismatch: The registry claims no env/credentials required, but the code and instructions require your IBKR username/password, account ID, and local binaries (Java, Chrome, chromedriver, Xvfb). Treat this omission as a red flag and expect to manually provide sensitive credentials. - Secrets handling: The setup creates a plaintext .env file containing IBEAM_ACCOUNT and IBEAM_PASSWORD. If you proceed, store credentials securely (tighten file permissions), consider using a secrets manager, and avoid reusing credentials elsewhere. - Automated 2FA: The scripts automate login via IBeam and will prompt your phone for IBKR Key approval. The keepalive/re-auth automation can launch repeated auth attempts — ensure you want phone prompts produced automatically and monitor for unexpected activity. - TLS and network: The skill disables certificate verification (verify=False / curl -k) because the gateway uses a self-signed cert. This is common for localhost gateways but increases risk if your system or network is compromised. Prefer configuring a trusted cert if possible and avoid exposing the gateway to untrusted networks. - Verify sources: The download URL appears to be IBKR's official domain, and pip packages are used for ibeam — nevertheless verify the ibeam package source/version (pip info, project homepage) and validate the clientportal archive (checksum/signature) from IBKR if available. - Run in isolation: Run this in a dedicated, least-privileged user/account or VM/container to limit blast radius. Do not run as root. Review scripts (they are included) and test in paper account mode first. - If you need the skill: ask the publisher to correct the manifest to declare required env vars/primary credential and to document security implications. If you cannot verify or trust the skill owner, prefer implementing authentication and automation yourself or use an official IBKR integration.

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.