swing_bot — IBKR Pre-Breakout Swing Trade Scanner

Connects to Interactive Brokers Gateway (or TWS), scans US major-exchange stocks for pre-breakout setups, scores each one, builds a trade plan, and produces a self-contained HTML report.

SCAN_ONLY = True by default. No orders are ever placed.

---

Project structure

swing_bot/
    __init__.py     Package description
    config.py       All user-tunable settings (edit here)
    indicators.py   SMA and ATR calculations
    scanner.py      IBKR scanner requests and candidate ranking
    analyzer.py     Pre-breakout scoring, trade plan, probabilities
    report.py       HTML report generator
    main.py         Main loop (connect → scan → analyse → report)
run.py              Top-level launcher
README.md           This file

---

Requirements

• Python 3.10+
• ib_insync library

pip install ib_insync

• Interactive Brokers Gateway (or TWS) running and logged in
• An IBKR account with market data subscriptions for US equities

---

Setup

1. Start IBKR Gateway

Open IB Gateway (or TWS) and log in. In Settings → API → Settings make sure:

• Enable ActiveX and Socket Clients is checked
• Socket port matches PORT in config.py (default: 4002)
• Allow connections from localhost only is checked (security)

2. Configure the bot

Open swing_bot/config.py and verify:

HOST      = "127.0.0.1"
PORT      = 4002        # 4002 = Gateway; 7497 = TWS paper; 7496 = TWS live
CLIENT_ID = 10

SCAN_ONLY = True        # Keep True — change only if you want live trading

Adjust any filters to suit your strategy:

Setting	Default	Meaning
MIN_PRICE	10	Minimum stock price
MAX_PRICE	500	Maximum stock price
MAX_DISTANCE_TO_HIGH	0.035	Max gap from 20-day high (3.5%)
MAX_VOLUME_RATIO	1.80	Max volume vs 20-day avg
MIN_PRE_BREAKOUT_SCORE	65	Minimum composite score
MAX_RISK_PERCENT	0.07	Max stop distance (7% of entry)

3. Run

From the project root (E:/CLAUDE/Jts/):

python run.py

Or invoke the package directly:

python -m swing_bot.main

---

Output

The script prints live progress to the console and, when finished, writes pre_breakout_trade_plan.html to the project root and opens it automatically in your default browser.

Report columns

Column	Description
Status	TRADE PLAN (all filters passed) or WATCH ONLY
Score	Composite pre-breakout score (0–105)
Entry	Planned buy-stop price just above resistance
Stop	Technical stop below price structure
Risk %	Stop distance as % of entry
Target 1/2/3	1R, 2R, 3R price levels
Probability	Model estimate for reaching each target
Resistance	20-day high used as breakout level
Distance	Gap between current close and resistance
Volume ratio	Today's volume vs 20-day average
Trend	Close > SMA20 > SMA50
Volatility contraction	Recent 5-day range < 85% of prior 15-day range
Risk OK	Risk % within MAX_RISK_PERCENT

---

Scoring model

Condition	Points
Near breakout (within 3.5% of 20-day high)	+30
Uptrend confirmed (Close > SMA20 > SMA50)	+25
Volatility contraction (VCP-style)	+20
Volume not exhausted	+10
Close in upper 40% of today's candle	+10
Scanner rank bonus (capped)	+10
Maximum possible	105

A setup is marked TRADE PLAN when:

• Score >= 65
• Stop risk <= 7% of entry
• Target 2 R/R >= 1.80

---

Safety notes

• SCAN_ONLY = True is enforced by default. The codebase contains no order-placement calls — adding them would require deliberate code changes.
• Probability estimates are heuristic model outputs, not financial advice.
• Always verify signals manually before trading.