Quick Start Guide: US Equity Trading with IBKR

This guide will help you get started with the CGS Engine US Equity Trading System using Interactive Brokers.

Prerequisites

  1. Python 3.9+ installed
  2. Interactive Brokers account (paper trading or live)
  3. IBKR Trader Workstation (TWS) or IBKR Gateway installed
  4. PostgreSQL database

Step 1: Install IBKR Software

Option A: Install Trader Workstation (TWS)

# Download from:
https://www.interactivebrokers.com/en/index.php?f=16042

# Download from:
https://www.interactivebrokers.com/en/index.php?f=16457

Step 2: Configure IBKR

For TWS:

  1. Open TWS
  2. Go to Configure → API → Settings
  3. Enable Enable ActiveX and Socket Clients
  4. Set Socket port to 7497 (paper trading) or 7496 (live trading)
  5. Add your IP address to Trusted IPs (use 127.0.0.1 for localhost)

For IBKR Gateway:

  1. Launch IBKR Gateway
  2. Login with your credentials
  3. API settings are automatically configured

Step 3: Install System Dependencies

# Navigate to project directory
cd cgs_tech

# Create virtual environment
python -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-ibkr.txt

Step 4: Configure Environment

# Copy example environment file
cp env_example .env

# Edit .env file with your configuration
nano .env  # or use your preferred editor

Update the following in .env:

IBKR_HOST=127.0.0.1
IBKR_PORT=7497  # 7497 for paper, 7496 for live
IBKR_CLIENT_ID=1
TRADING_MODE=paper
TRADING_SYMBOLS=AAPL,MSFT,GOOGL

Step 5: Test Connection

# Start TWS or IBKR Gateway
# Wait for it to connect

# Test the connection
python -c "
from ib_insync import IB
ib = IB()
ib.connect('127.0.0.1', 7497, clientId=1)
print('Connected successfully!')
print('Account values:', ib.accountValues())
ib.disconnect()
"

If successful, you should see account information.

Step 6: Setup Database

# Create PostgreSQL database
createdb cgs_trading

# Or using psql:
psql -U postgres
CREATE DATABASE cgs_trading;
CREATE USER cgs_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE cgs_trading TO cgs_user;
\q

# Update .env with database credentials
DB_HOST=localhost
DB_PORT=5432
DB_NAME=cgs_trading
DB_USER=cgs_user
DB_PASSWORD=your_password

Step 7: Run the System

Paper Trading Test

# Start TWS/Gateway (already running from Step 5)

# Run the example trading system
python examples/ibkr_equity_trading_example.py

Monitor Trading Dashboard (Optional)

In a separate terminal:

# Start the dashboard
python src/app.py

# Access at http://localhost:8081

Common Symbols for Testing

# Large-cap stocks
AAPL  # Apple
MSFT  # Microsoft
GOOGL # Google
TSLA  # Tesla

# ETFs
SPY   # S&P 500
QQQ   # NASDAQ
DIA   # Dow Jones

# Tech stocks
NVDA  # NVIDIA
META  # Meta/Facebook
AMZN  # Amazon

Troubleshooting

Connection Issues

Problem: Cannot connect to IBKR

Error: Connection refused

Solutions:

  1. Ensure TWS/Gateway is running
  2. Check port number (7497 for paper, 7496 for live)
  3. Verify API is enabled in TWS settings
  4. Check firewall settings

Permission Errors

Problem: Orders rejected due to permissions

Solutions:

  1. Enable API permissions in TWS settings
  2. Check account permissions in IBKR
  3. Ensure account has sufficient buying power

Data Issues

Problem: No historical data available

Solutions:

  1. Request more historical data (increase duration)
  2. Check if market data subscription is active
  3. Verify symbol is tradeable

Next Steps

  1. Backtest your strategy: Use notebooks/VBT_cgs_base.ipynb to backtest strategies
  2. Optimize parameters: Use SHAP analysis to optimize strategy parameters
  3. Monitor performance: Use the dashboard to monitor real-time performance
  4. Adjust risk settings: Fine-tune risk parameters in .env

Safety Checklist

Before going live:

Getting Help

Important Notes

⚠️ Never trade with real money before extensive testing

⚠️ Always monitor your system when live

⚠️ Use appropriate risk management at all times

⚠️ Start with small position sizes

⚠️ Keep emergency stop procedures ready

Support

For questions or issues:

Happy Trading! 🚀