# BoxTheoryKillZoneScanner

`BoxTheoryKillZoneScanner` is an optional alert-only MT5 Expert Advisor for the Box Theory kill-zone workflow. It scans a configurable symbol list on a timer, builds each symbol's box from the previous completed D1 candle, classifies current price into a zone, draws box/kill-zone rectangles on the active chart symbol, and sends alerts when price moves from middle/no-trade territory into a kill zone or when confirmation scoring passes.

It does not place trades.

## Core Defaults

- `SymbolsCSV`: Deriv volatility, 1s volatility, Step, Jump, Boom, and Crash symbols.
- `ScanIntervalSeconds`: `60`.
- `EdgePct`: `0.125`, so the top and bottom kill zones are the outer 12.5% of the previous D1 range.
- `AnalysisTF`: `PERIOD_H1`.
- `ConfirmBars`: `5`.
- `EnableEmailAlerts`: `true`.
- `EnablePopupAlerts`: `true`.
- `EnablePushAlerts`: `false`.
- `EnableTelegramWebhook`: `false`.
- `FixedRiskUSD`: `20.0`, planning only.
- `DrawLabels`: `true`.
- `DrawMiniBoxes`: `true`.
- `OpenChartOnAlert`: `true`.
- `AlertChartTF`: `PERIOD_H1`.
- `EnableAutoTrading`: `false`, reserved and ignored.
- `RequireClosedCandleConfirm`: `true`.
- `MaxSpreadBoxPct`: `0.08`.
- `StateFileName`: `BoxTheoryState.csv`.

## Generated Files

These are written under MT5 `MQL5/Files`:

- `BoxTheoryState.csv`: persistent per-symbol zone state and alert timestamps.
- `BoxTheoryScannerLog.csv`: every scan/reject event.
- `BoxTheoryAlerts.csv`: fired alerts.
- `BoxTheoryRejectedSetups.csv`: rejected plans or bad data conditions.

## Alert Logic

The EA alerts when:

- Previous saved zone was `MIDDLE_NO_TRADE`, and current zone becomes `TOP_KILL_ZONE` or `BOTTOM_KILL_ZONE`.
- Current zone is a kill zone and confirmation score reaches the threshold.

Boom, Crash, and Jump symbols use the stricter `EventSpikeConfirmationThreshold`.

## Confirmation Score

The scanner scores:

- Kill-zone presence.
- Wick rejection.
- Sweep and reclaim of box high/low.
- Lower-high bearish continuation.
- Higher-low bullish continuation.
- Break of trigger candle low/high.

The trade plan is non-executing. It reports structural SL, TP1, TP2, runner instructions, fixed-dollar planned lots, actual risk, and R:R estimates.

## Symbol Scope

Set `SymbolsCSV` to a comma-separated list for a curated universe, or set it to `all` to scan all currently visible Market Watch symbols whose trading mode is not disabled.

## Chart Objects

Objects are named by symbol, source, and session date:

```text
BT_<symbol>_D1_<yyyy-mm-dd>_BOX
BT_<symbol>_D1_<yyyy-mm-dd>_TKZ
BT_<symbol>_D1_<yyyy-mm-dd>_BKZ
BT_<symbol>_D1_<yyyy-mm-dd>_MID
```

When price trades above or below the parent box, the scanner can draw `_MINI_BOX` and `_MINI_MID` objects from recent confirmation candles. Labels include the symbol, D1 session date, high, midpoint, and low.

## Sample Email

Subject:

```text
[BoxTheory] Volatility 25 Index TOP_KILL_ZONE SELL_CANDIDATE RR=2.30
```

Body excerpt:

```text
Alert type: CONFIRMATION
Symbol: Volatility 25 Index
Current price: 2546.125
Previous D1 high: 2549.000
Previous D1 low: 2484.000
Midpoint: 2516.500
Top kill zone: 2540.875 to 2549.000
Bottom kill zone: 2484.000 to 2492.125
Current zone: TOP_KILL_ZONE
Previous zone: MIDDLE_NO_TRADE
Setup type: SELL_CANDIDATE
Confirmation score: 4
Entry trigger: break_below_trigger_low_2544.250
Structural SL: 2550.000
TP1: 2516.500 RR=1.50
TP2: 2484.000 RR=2.80
Runner plan: After TP2, trail runner above lower highs; never widen stop.
Fixed risk USD: 20.00
Planned lots: 6.94
Actual risk: 19.99
Risk % of account: 0.200
Spread: 0.125
Stop-level warnings:
Reason: price_in_top_kill_zone; bearish_upper_wick_rejection; lower_high_continuation; trigger_low_break
Reason if rejected:
Timestamp: 2026.06.27 18:45:53
```

## How To Use

1. Copy `BoxTheoryKillZoneScanner.ex5` into `MQL5/Experts/Advisors`.
2. Restart MT5 or refresh the Navigator panel.
3. Attach it to any M5/H1 chart. The attached timeframe is not used for scanning; `AnalysisTF` controls confirmation.
4. Enable email in MT5 settings if you want `SendMail()` to work.
5. If using Telegram, add `https://api.telegram.org` under MT5 allowed WebRequest URLs and set `TelegramBotToken` / `TelegramChatId`.
6. Keep `EnableAutoTrading = false`; this EA is designed as a scanner only.

## Known Limitations

- Alerts depend on your broker's symbol names matching `SymbolsCSV`, unless `SymbolsCSV=all` is used.
- MT5 email/push/Telegram delivery must be configured separately in the terminal.
- The scanner draws boxes only on the active chart when that chart's symbol is part of the scan. Alerts can open or focus `AlertChartTF`.
- Fixed-risk sizing is planning-only. It is not used for execution.
- A first baseline run does not alert unless `AlertOnBaseline = true`.