Interactive Brokers Setup Guide

Time: 15 minutes | Difficulty: Advanced | Market: Equities Mode: Full automation | API: TWS API + Client Portal API + IB Gateway | Docs: interactivebrokers.github.io

This guide wires an Interactive Brokers trading bot to the TWS API using the botwir3 runtime. Configure API access, connect to global equities, options, futures, forex, and fixed income markets, and run automated strategies locally.

Before you start

Verify that automated operation is permitted under Interactive Brokers' current terms of service before deploying. botwir3 provides tools for building structured automation. The user is responsible for compliance with the platform's terms and all applicable regulations.

Interactive Brokers Customer Agreement | Last verified: May 2026

What you need

• An Interactive Brokers account (paper or live)
• Trader Workstation (TWS) or IB Gateway installed
• API connections enabled in TWS/Gateway settings
• The botwir3 runtime downloaded and unzipped
• A strategy config file from the builder

Step 1: Enable API access

1. Open Trader Workstation (TWS) or IB Gateway
2. Navigate to Edit → Global Configuration → API → Settings
3. Enable Enable ActiveX and Socket Clients
4. Set the Socket port (default: 7496 for live TWS, 7497 for paper, 4001 for Gateway live, 4002 for Gateway paper)
5. Under Trusted IPs, add 127.0.0.1 (localhost)
6. Disable Read-Only API to allow order placement

Permissions required: ActiveX and Socket Clients enabled, Read-Only API disabled. Permissions to disable: IBKR API does not support withdrawal or fund transfer. These operations require the Account Management portal.

🔒 Security. The IBKR API communicates via local socket — no credentials are transmitted over the network. TWS or IB Gateway must be running on the same machine (or accessible via a local network). Withdrawal is not available through the API. Credentials are stored in a local config file and are not transmitted to botwir3 or any third party.

Step 2: Configure the adapter

Create adapter.json in the bot directory:

{
  "adapter": "ibkr",
  "credentials": {
    "host": "127.0.0.1",
    "port": 7497,
    "client_id": 1
  },
  "trading_pair": "AAPL",
  "exchange": "SMART",
  "sec_type": "STK",
  "environment": "paper",
  "rate_limit_ms": 1000
}

port: 7496 (live TWS), 7497 (paper TWS), 4001 (live Gateway), 4002 (paper Gateway).

client_id: Unique integer per concurrent connection. Use 1 for a single bot.

sec_type: "STK" (stocks), "OPT" (options), "FUT" (futures), "CASH" (forex), "BOND" (bonds).

exchange: "SMART" routes to the exchange with the optimal price. Specify a particular exchange (NYSE, NASDAQ, ARCA) if required.

API keys are not required — the TWS API uses local socket authentication. botwir3 never sees, stores, or has access to IBKR login credentials.

Step 3: Test the connection

botwir3 test --adapter ibkr

Expected output:

[botwir3] Adapter: ibkr
[botwir3] Connection: OK (TWS on 127.0.0.1:7497)
[botwir3] Client ID: 1
[botwir3] Account: paper (DU1234567)
[botwir3] Rate limit: 50 messages/second

Step 4: Start the bot

botwir3 start --config my-strategy.json

The runtime loads the strategy, computes the spec hash, connects to TWS/Gateway via the local socket, and begins evaluating signals. The gate function compares proposed actions against the configured spec. The user is responsible for monitoring the bot and verifying execution outcomes.

Rate limits and considerations

ℹ TWS vs IB Gateway. TWS is the full trading platform with a GUI. IB Gateway is a lightweight, headless version for API-only operation. For 24/7 bot operation, IB Gateway is the appropriate choice — it uses fewer resources and supports automatic restarts.

Common IBKR bot configurations include multi-asset portfolio rebalancing (stocks, bonds, ETFs), options strategies (covered calls, iron condors), futures spread trading, and global equity momentum strategies. IBKR provides access to 150+ markets in 33 countries — the broadest coverage of any retail broker. All actions and decisions are recorded in the local ledger.

Troubleshooting

Related guides

• Alpaca Setup Guide — equities, API-first, commission-free
• Schwab Setup Guide — equities, requires developer app approval
• TradingView → Broker Setup Guide — route TradingView alerts to IBKR

One bot. $129. No subscription. No $749/mo platform. → Build for Interactive Brokers