XAUUSD Pattern Scanner

01 — Overview

The XAUUSD Pattern Scanner is a real-time technical analysis engine that connects to your MetaTrader 5 terminal and continuously scans XAUUSD (Gold) across four timeframes simultaneously. It detects over 70 patterns, calculates a multi-factor confluence score, grades setups A/B/C, and presents only the highest-probability opportunities — eliminating the noise of contradictory BUY/SELL signals.

What it does in one sentence

Every 8 seconds it scans M1, M5, M15, and H1, runs 15 different detection engines, scores the results with a 14-category confluence system, and shows you only the setups where enough independent evidence agrees — with entry, stop loss, take profit, R:R, and lot size already calculated.

Architecture summary

02 — Quick Start

Prerequisites

• Windows PC (MT5 is Windows-only)
• MetaTrader 5 installed and logged into your broker
• XAUUSD visible in MT5 Market Watch
• Python 3.10 or higher installed

Step-by-step setup

Two modes available

03 — File Structure

xauusd_scanner/
├── server.py              ← Main entry point — run this
├── patterns.py            ← All 70+ pattern detectors (1895 lines)
├── database.py            ← SQLite storage engine
├── mt5_feed.py            ← MT5 connection and data feed
├── backtest.py            ← Historical backtest engine
├── alerts.py              ← Sound, desktop, log alerts
├── scanner.py             ← GUI mode entry point
├── dashboard.py           ← Terminal (ANSI) dashboard
├── gui_dashboard.py       ← Tkinter GUI dashboard
├── dashboard.html         ← Web UI (main interface)
├── backtest.html          ← Standalone backtest analytics
├── DOCS.html              ← This documentation file
├── requirements.txt       ← Python dependencies
├── START.bat              ← Web mode launcher
├── START_SCANNER.bat      ← GUI mode launcher
├── data/                  ← Auto-created
│   ├── scanner.db         ← SQLite database
│   ├── setups_export.json ← Auto-exported setups
│   ├── signals_export.json← Auto-exported signals
│   └── analytics_export.json
└── logs/                  ← Auto-created
    └── signals_YYYYMMDD.log

04 — Requirements

Install all at once: pip install -r requirements.txt

05 — Dashboard Layout

The web dashboard at http://localhost:5000 is divided into three columns plus a top bar.

Killzone Timer (top bar)

Shows the countdown to the next ICT Killzone. 🟢 LON 45m 12s = London Killzone active with 45 minutes remaining. ⏳ NY 22m = NY Killzone opens in 22 minutes. 🔴 London in 3h40m = no active killzone.

06 — Signal List (Left Column)

The signal list shows all patterns detected in the current scan, filtered by your selected timeframe tab and strategy filter.

Reading a signal card

┌─ BUY ─── M1 ─── Triple Bottom ──────────────── 86% ─┐
│  E:$4835.20   SL:$4830.10   TP:$4852.80   1:3.5 R:R  │
└─────────────────────────────────────────────────────┘

07 — Best Setups Panel (⚡ Tab)

The Best Setups panel is the core feature that solves the "contradictory signals" problem. Instead of showing every BUY and SELL simultaneously, it uses a 14-category confluence engine to find setups where multiple independent signal types agree on one direction.

How a setup qualifies

• One timeframe has >57% of confidence mass pointing one direction
• At least 3 independent confluence categories agree
• Best signal has R:R ≥ 1.5 (filter adjustable)
• Setup is not expired (adjustable timer, default 30 min)

Setup card anatomy

┌── BUY  London KZ — Swept Asian Low  M5  H1✓  Grade A  2m ──┐
│  ⚠ Wednesday — FOMC risk. Reduce size.                      │
│  Confluence: ●●●●●●○○○○ 6/14  78% bull                     │
│  Strategy · Killzone · Fibonacci  📍 At Support (3 pip)     │
│  E: $4835.20   SL: $4830.10   TP: $4852.80   1:3.5 R:R     │
│  📊 Similar: 62% WR · 18 trades · +12.4R total             │
└─────────────────────────────────────────────────────────────┘

Filter controls

08 — Backtest Tab (📊)

The Backtest tab shows real performance data from YOUR live trading sessions. Unlike the standalone /backtest page which runs a simulation on MT5 history, this tab reads from the local SQLite database where every Best Setup is automatically saved and its outcome tracked.

How outcomes are determined

1. MT5 bars (primary): After a setup fires, the scanner checks subsequent OHLCV bars on that timeframe. If the High hits TP or Low hits SL → resolved as win/loss
2. Live ticks (fallback): If MT5 data isn't available, live price ticks are used instead
3. Expired (24h): Setups that hit neither TP nor SL within 24 hours are marked expired

What the tab shows

Use the ↺ Refresh button to update. Use ⬇ JSON to export all data to data/ folder. Use 🗑 to clear history and start fresh.

09 — Position Size Calculator

Located in the right panel above the tabs. Click any signal in the signal list or setup panel to auto-fill entry and SL.

Formula used

Risk Amount ($) = Account Balance × Risk %
SL Distance (pips) = |Entry - Stop Loss|
Lot Size = Risk Amount ÷ (SL Pips × Pip Value per Lot)

10 — Killzone Timer

The live countdown in the top bar shows which ICT Killzone is active or approaching. Killzones are the specific hours of day when institutional order flow is highest and the highest-probability setups occur.

11 — Candlestick Patterns

Detected by detect_candles() in patterns.py. Applied to every timeframe on every scan. All use ATR-based SL/TP.

12 — Chart Patterns

Detected by detect_chart() using scipy.signal.argrelextrema to find swing highs and lows, then checking geometric relationships.

13 — SMC / ICT Concepts

Detected by detect_smc(). Smart Money Concepts and ICT methodology — the most powerful patterns in the scanner.

14 — Technical Indicators

Detected by detect_indicators(). All calculated on the raw OHLCV data — no external libraries needed.

15 — Support & Resistance

Detected by detect_sr(). Automatically finds and merges swing highs/lows, plus gold-specific psychological round numbers.

16 — Volume Intelligence

Detected by detect_volume(). MT5 provides tick volume which correlates well with real volume for direction confirmation.

17 — Bill Williams Indicators

Detected by detect_bill_williams(). Bill Williams' market structure theory — Alligator, Awesome Oscillator, Fractals, Market Facilitation Index.

18 — ICT Killzones

Detected by detect_killzones(). The most important concept from ICT (Inner Circle Trader) methodology — specific time windows when institutional order flow dominates and the highest-probability setups occur.

London Killzone (07:00–09:00 UTC)

New York Killzone (12:00–14:00 UTC)

19 — Fibonacci OTE (Optimal Trade Entry)

Detected by detect_fibonacci(). ICT's most precise entry technique — enter at the 61.8%–78.6% retracement of a clear impulse move.

Why 61.8%–78.6% is special

The golden ratio (61.8%) is where institutional orders are placed for pullback entries. 78.6% is the deepest acceptable retracement before the move is considered failed. Between these levels: highest probability, best R:R, tightest SL.

20 — HTF Daily Bias

Detected by detect_htf_bias() on H1, H4, and D1 only. Reads higher timeframe direction before you trade lower timeframes. ICT's #1 rule: trade WITH the higher timeframe bias, never against it.

Strong bias (85%) = both EMA alignment AND swing structure agree. Moderate (74%) = only one confirms. Use the H1→M5 confirm toggle in the Setups panel to automatically block any setup that contradicts the H1 bias.

21 — Win Probability Score

Detected by detect_probability_score(). Aggregates all available factors into a single composite score and grade.

Scoring factors

22 — S/R Flip Retest (Playbook Strategy 1)

Entry rules

• Level must have been tested ≥2 times before the break
• Break must be confirmed with 15+ pip expansion
• Enter on rejection candle (long wick back at the level) — NOT on the break
• SL: 3–5 pips beyond the level
• Target: R:R 1:3 minimum

23 — Consolidation Breakout (Playbook Strategy 2)

Target calculation

Project the range height from the breakout level. If range was 30 pips and broke upward at $4850, target = $4850 + $30 = $4880.

24 — EMA Trend Pullback (Playbook Strategy 3)

25 — Stop-Hunt Reversal (Playbook Strategy 4)

Identification rules

• Must have ≥2 equal highs (Buy-Side Liquidity) or equal lows (Sell-Side Liquidity)
• Spike must be 5–50 pips beyond the pool level (not too small, not news-driven)
• Wick above/below but body closed back inside the range
• Enter on close of first reversal candle after the spike — act within 1–3 minutes
• SL above wick extreme + 3–5 pips (very tight)

26 — Scalping with the Scanner

The scalper's daily routine with this scanner

• 6:30 AM UTC — Open scanner. Note Asian range H/L shown in Killzone signals. This is today's liquidity map.
• 6:55 AM UTC — Check H1 HTF Bias. If bullish → only take BUY setups today. If bearish → only SELL.
• 7:00–7:20 AM UTC — London KZ opens. WATCH for the Asian range sweep signal (88% confidence). This is your best trade of the day.
• 7:20–9:00 AM UTC — If sweep happened, trade continuation. Enable H1→M5 confirm toggle. Look for Grade A on M5.
• 9:00–12:00 AM UTC — Avoid. Low-probability window. Review signals, check backtest tab.
• 11:30 AM UTC — Pre-NY alert fires. Check London direction. Decide: continuation or reversal?
• 12:00–14:00 UTC — NY KZ. Second opportunity. If London was strong, continuation trade. If London stalled, reversal.
• After 14:00 UTC — Done for the day. No more entries.

27 — Scalp Setup A: Killzone Asian Sweep

Best setup in the scanner. Fires at 07:00–08:30 UTC. Win rate in ideal conditions: ~65–72%.

28 — Scalp Setup B: Fibonacci Golden Zone Bounce

Works all day but best in killzones. Fires after any clean impulse move. Win rate: ~60–68%.

29 — Scalp Setup C: Order Block Retest

High-precision entry. Fires throughout the day. Win rate when fresh OB: ~63–70%.

30 — Scalp Setup D: Stop-Hunt Reversal

Fastest R:R setup. Must act within 1–3 minutes of signal. Win rate when confirmed: ~60–65%.

31 — Pre-Trade Checklist

Run through this before every trade. If any RED item fails, do not enter.

32 — Best Trading Times (UTC)

Day of week quality

33 — Hard Rules for Profitable Scalping

34 — Confluence Engine

The 14-category confluence engine is the core of the Best Setups panel. It prevents double-counting by allowing each category to contribute at most 1 point, regardless of how many signals of that type fire.

Minimum to show setup: 3/14. Grade A: ≥6/14 AND confidence ≥82%. Grade B: ≥4/14 AND confidence ≥75%.

35 — Database & Storage

The database.py module manages a local SQLite database at data/scanner.db.

Tables

JSON exports (auto-generated hourly)

Click ⬇ JSON in the Backtest tab to trigger an immediate export. Exports update automatically every hour while the scanner is running.

36 — API Reference

All endpoints served by server.py on port 5000.

Pages

Live Scanner

Position Sizing

Database / Setup Backtest

MT5 Backtest Engine

37 — Alerts System

Deduplication

The same pattern + direction + timeframe will not alert again within 15 minutes (configurable via --cooldown flag). This prevents alert spam when the same pattern fires repeatedly.

38 — Configuration

server.py defaults

TIMEFRAMES    = ["M1", "M5", "M15", "H1"]   # Timeframes to scan
SCAN_INTERVAL = 8                              # Seconds between scans
MIN_CONFIDENCE = 68.0                          # Minimum confidence to include signal

scanner.py command-line flags (GUI mode)

Scalping configuration (recommended)

python scanner.py --tfs M1,M5 --interval 5 --minconf 72

Scans M1 and M5 every 5 seconds with a higher minimum confidence, giving you only the cleanest scalp signals.

39 — Troubleshooting

40 — Changelog

v3.2.1 (Current — Hotfix)

• Fixed: np2 is not defined crash in detect_htf_bias
• Fixed: Scanner connecting to MetaQuotes demo terminal instead of broker terminal on reconnect

v3.2

• Multi-TF confirmation toggle (H1→M5 confirm)
• Setup expiry timer (5–60 min slider)
• Grade A browser notification + audio beep + in-app toast
• Key level proximity detection on every setup card
• News risk filter (CPI/NFP/FOMC/ECB time windows)
• Setup replay stats from DB backtest on every card
• H1 ✓/✗ HTF match badge on setup cards

v3.1

• London & NY Killzone detector with Asian sweep logic
• Fibonacci Golden Zone (61.8–78.6%) OTE detector
• HTF Daily Bias (H1/H4/D1)
• Win Probability composite score
• Position Size Calculator
• Killzone countdown timer in top bar
• New filter tabs: Killzones, Fibonacci, Win Probability

v3.0

• Auto-retry MT5 connection every 15s (never exits on failure)
• SQLite database for setup tracking and outcome resolution
• All signals saved to all_signals table
• Outcome resolution via MT5 bars + live tick fallback
• JSON auto-export (hourly) to data/ folder
• Backtest tab in right panel (DB-backed, no MT5 needed)
• Diagnostics panel (4-step fix guide when MT5 disconnects)
• Error recovery: auto-reconnect after 5 consecutive errors

v2.2 and earlier

• Best Setups panel with 14-category confluence engine
• Smart noise filter (contradictory BUY+SELL eliminated)
• 4 playbook strategies: S/R Flip, Breakout, EMA Pullback, Stop-Hunt
• scan_all double-override fix
• Alerts dedup direction fix
• R:R ≥ 1.5 minimum filter
• Flask server with web dashboard
• MT5 backtest engine with Monte Carlo and regime detection