Topics

#algorithmic-trading #discord #ibkr #interactive-brokers #options #python #trading-bot

Language breakdown

Python 100.0%

▸ Files click to expand

README

IBKR Options Chain Scanner - Setup Guide

📋 What You Need

Interactive Brokers Account (Paper or Live)
IB Gateway installed and running
Python 3.8+ installed
Discord Webhook URL (for alerts)

🚀 Quick Start (5 Steps)

Step 1: Install Python Dependencies

Open your terminal/command prompt and run:

pip install ib_insync requests

What this does: Installs the libraries needed to connect to IBKR and send Discord messages.

Step 2: Setup IB Gateway

Download IB Gateway from Interactive Brokers website
Login to IB Gateway with your credentials
Important Settings:

- Go to Configure → Settings → API → Settings - ✅ Enable "Enable ActiveX and Socket Clients" - ✅ Check "Read-Only API" - Set Socket Port: - 4002 for Paper Trading (recommended for testing) - 4001 for Live Trading - ✅ Check "Allow connections from localhost only" - Click OK and restart IB Gateway

Screenshot reference: The settings should look like this:

[✓] Enable ActiveX and Socket Clients [✓] Read-Only API Socket port: 4002 [✓] Allow connections from localhost only

Step 3: Create Discord Webhook

Open Discord and go to your server
Right-click the channel where you want alerts
Click "Edit Channel" → "Integrations" → "Webhooks"
Click "New Webhook"
Name it (e.g., "IBKR Scanner")
Copy the Webhook URL (looks like: https://discord.com/api/webhooks/...)

Step 4: Configure the Script

Open phase1chainscanner.py in any text editor
Find the configuration section at the top (around line 20)
Edit these values:

# REQUIRED: Add your Discord webhook URL
DISCORDWEBHOOKURL = 'https://discord.com/api/webhooks/YOURACTUALURL_HERE'
REQUIRED: Set correct IB Gateway port
IB_PORT = 4002  # Use 4002 for paper trading, 4001 for live
OPTIONAL: Adjust filters if needed
DELTA_MIN = 0.35           # Keep options with delta between 0.35-0.55
DELTA_MAX = 0.55
MAXSPREADPERCENT = 7.0   # Reject if bid-ask spread > 7%
MIN_VOLUME = 10            # Minimum daily volume
MINOPENINTEREST = 50     # Minimum open interest
SCANINTERVALSECONDS = 60 # Scan every 60 seconds

Save the file

Step 5: Run the Scanner

Make sure IB Gateway is running and logged in
Open terminal in the folder containing phase1chainscanner.py
Run:

python phase1chainscanner.py

You should see:

🚀 Starting IBKR Options Scanner 📊 Symbol: SHOP 🎯 Delta range: 0.35 - 0.55 💰 Max spread: 7.0% 📈 Min volume: 10, Min OI: 50 ⏱️  Scan interval: 60 seconds ====================================================================== 🔌 Connecting to IB Gateway at 127.0.0.1:4002... ✅ Connected to IBKR successfully! 🔍 Starting scan for SHOP...

📊 What the Scanner Does

Real-Time Process:

Connects to your IB Gateway (read-only, safe)
Fetches all SHOP option contracts (calls and puts)
Gets live market data:

- Bid/Ask prices - Delta values - Volume & Open Interest

Filters options using your criteria:

- ✅ Delta between 0.35-0.55 - ✅ Spread < 7% - ✅ Volume ≥ 10 - ✅ Open Interest ≥ 50

Sends qualifying options to Discord
Repeats every 60 seconds

🔧 Configuration Explained

Delta Filter

DELTA_MIN = 0.35
DELTA_MAX = 0.55

Delta measures how much option price moves with $1 stock move
0.35-0.55 is the "sweet spot" for balanced risk/reward
Lower delta (0.35) = cheaper, further OTM
Higher delta (0.55) = more expensive, closer to ATM

Spread Filter

MAXSPREADPERCENT = 7.0

Spread = difference between bid and ask price
7% means you reject options with wide spreads
Tight spreads = easier to enter/exit positions
If spread > 7%, the option is rejected (not liquid enough)

Liquidity Filters

MIN_VOLUME = 10
MINOPENINTEREST = 50

Volume = contracts traded today
Open Interest = total open contracts
Higher values = more liquid (easier to buy/sell)

Scan Interval

SCANINTERVALSECONDS = 60

How often the script scans for new options
60 seconds = once per minute (balanced)
Lower = more frequent updates (more API calls)
Higher = less frequent (lighter on resources)

📱 Discord Alert Format

When an option passes all filters, you'll get:

🎯 New Option Alert Stock: SHOP Type: CALL Expiry: 20250221 Strike: $85.00 Pricing: • Bid: $2.45 • Ask: $2.60 • Spread: 5.77% Greeks & Volume: • Delta: 0.452 • Volume: 125 • Open Interest: 450

Scanned at 2026-02-01 14:30:15

⚠️ Common Issues & Solutions

Issue 1: "Failed to connect to IBKR"

Solutions:

✅ IB Gateway is running and logged in
✅ Port number matches (4002 for paper, 4001 for live)
✅ "Enable ActiveX and Socket Clients" is checked in IB settings
✅ "Read-Only API" is enabled
Try restarting IB Gateway

Issue 2: "No option chains found for SHOP"

Solutions:

Market might be closed (options trade 9:30 AM - 4:00 PM ET)
Check if SHOP symbol is correct
IB Gateway might not have data permissions for options
Try with a different symbol (e.g., SPY, AAPL)

Issue 3: "Discord webhook failed"

Solutions:

✅ Webhook URL is correct (copied fully)
✅ Discord channel still exists
✅ Webhook wasn't deleted in Discord settings
Test webhook manually: Visit https://discord.com/developers/docs/resources/webhook

Issue 4: Script crashes or stops

Solutions:

Check IB Gateway didn't log out automatically
Look at error message in terminal
Run with debug mode: Change LOG_LEVEL = logging.DEBUG in config
The script has auto-reconnect, but if Gateway restarts you may need to restart script

Issue 5: No alerts being sent

Possible reasons:

No options currently meet all filter criteria (delta + spread + volume + OI)
Options were already sent (duplicate detection working)
Market is closed or low activity period
Try loosening filters temporarily to test:

DELTA_MIN = 0.20    DELTA_MAX = 0.80    MAXSPREADPERCENT = 15.0    MIN_VOLUME = 5    MINOPENINTEREST = 10

🛑 How to Stop the Scanner

Press Ctrl+C (or Cmd+C on Mac) in the terminal.

You'll see:

⚠️  Shutdown requested by user 🔌 Disconnected from IBKR 👋 Scanner stopped

📈 Performance Tips

For Better Results:

Run during market hours (9:30 AM - 4:00 PM ET)

- Options have the most activity during this time - More likely to find options meeting liquidity filters

Start with looser filters if testing

- Lower MINVOLUME and MINOPEN_INTEREST - Increase MAXSPREADPERCENT - Once you see alerts flowing, tighten them

Adjust scan interval based on needs

- 30 seconds = more real-time (higher load) - 60 seconds = balanced (recommended) - 120 seconds = lighter, slower updates

Monitor the logs

- Green ✅ = success - Yellow ⚠️ = warning (non-critical) - Red ❌ = error (needs attention)

🔒 Safety Features Built-In

✅ Read-only connection - Cannot place trades ✅ Auto-reconnect - Recovers from connection drops ✅ Error handling - Won't crash on bad data ✅ Duplicate prevention - Won't spam same option ✅ Rate limiting - Won't overwhelm Discord ✅ Market data validation - Skips incomplete data

📝 What This Script Does NOT Do

❌ No trading or order placement ❌ No AI or machine learning ❌ No trading signals or recommendations ❌ No position management ❌ No P&L tracking

This is purely a data scanner and filter.

🎯 Next Steps (After You're Comfortable)

Try different symbols - Edit SYMBOL = 'SHOP' to 'SPY', 'AAPL', etc.
Adjust filters - Tune delta range, spread limits based on what you see
Multiple instances - Run multiple scripts for different symbols
Save to file - Modify to log results to CSV for analysis

🆘 Need Help?

If something isn't working:

Check the logs - The script prints detailed info
Enable debug mode - Set LOG_LEVEL = logging.DEBUG
Test IB connection - Make sure IB Gateway shows "Connected" status
Verify Discord webhook - Send a test message using an online tool

📚 Additional Resources

IB API Documentation: https://interactivebrokers.github.io/tws-api/
ib_insync Documentation: https://ib-insync.readthedocs.io/
Discord Webhooks Guide: https://discord.com/developers/docs/resources/webhook
Interactive Brokers Gateway: https://www.interactivebrokers.com/en/trading/ibgateway-stable.php

Happy Scanning! 🚀

🔗 More in this category