Add professional README with full project documentation

2026-05-30 20:47:53 -05:00
parent 0cfe101e74
commit 44c2fde111
1 changed files with 117 additions and 2 deletions
@@ -1,2 +1,117 @@
-# mql5-order-blocks-ea
-Order Blocks Expert Advisor for MetaTrader 5, converted from Pine Script v6 with mathematical indicator parity (Wilder ATR, custom Stochastic). Validated on 12 years of EURUSD M30 historical data.
+# Order Blocks Expert Advisor — EURUSD M30 (MetaTrader 5)
+
+> Pine Script v6 → MQL5 cross-platform conversion with full mathematical indicator parity. Validated on 12 years of EURUSD M30 historical data (~3,300 operations).
+
+---
+
+## Overview
+
+This Expert Advisor detects bullish **Order Blocks (OB)** on EURUSD M30 and executes long entries when price returns to a valid OB zone, with dynamic risk management and an optional dynamic Take Profit based on opposing bearish Order Blocks.
+
+The project was originally written in **Pine Script v6** for TradingView and fully converted to **MQL5 native** for MetaTrader 5, with custom-coded indicators to guarantee mathematical parity across platforms — a non-trivial problem that breaks most naïve conversions.
+
+---
+
+## Key technical features
+
+### Cross-platform mathematical parity
+- Custom `PineATR()` implementing Wilder's RMA (Running Moving Average) — matches `ta.atr()` of Pine Script bit-by-bit, instead of relying on MT5's `iATR()` which differs in initial seed
+- Custom `PineStoch()` with SMA-smoothed %K — matches `ta.sma(ta.stoch(...), 3)` of Pine
+- Manual Choppiness Index implementation (no MT5 native equivalent)
+
+### Modular filter architecture
+Each filter block can be independently enabled/disabled for clean optimization:
+- **Oscillators** (RSI + ADX + CHOP, range-bound)
+- **Candle confirmation** (wicks, body solidity, volume, size vs ATR)
+- **Premium/Discount filter** with persistent impulse tracking
+- **Stochastic confirmation** (separate buy/sell thresholds)
+- **Dead-hour session filter** (configurable GMT offset)
+
+### Risk management
+- Dynamic position sizing based on equity % risk per trade
+- Configurable max simultaneous positions
+- Daily drawdown circuit-breaker
+- Fixed SL at OB bottom − ATR offset
+- Dynamic TP: nearest opposing bearish OB level (with fallback ratio)
+
+### OnTester custom optimization criteria
+Custom max function rejects optimization runs that fail any of:
+- Minimum trades threshold
+- Maximum equity drawdown
+- Minimum Profit Factor
+- Minimum net profit
+- Minimum Sharpe Ratio
+- Minimum Recovery Factor
+
+When all thresholds pass, the optimizer maximizes `profit / equity_DD$` (recovery factor) — explicit reward for return-per-unit-of-pain.
+
+### Visual auditing
+- Live OB boxes (green/red) that extend in time while active
+- Boxes are **frozen on retirement** (not deleted):
+  - **Aqua solid border** = OB that triggered an entry
+  - **Gray dotted border** = OB invalidated without entry
+- This allows post-test forensic review of every signal
+
+---
+
+## Validation methodology
+
+This EA was tested with rigor that is uncommon in retail trading code:
+
+- **Calibration period:** 2025 (in-sample)
+- **Out-of-sample 1:** 2026 H1 (same parameters)
+- **Out-of-sample 2:** 2014–2024 (full multi-régime test, never seen during calibration)
+- **Cross-timeframe validation:** same parameters applied to H1 and H4 without re-tuning
+
+### Honest results — full 12-year backtest
+
+The system shows clear positive performance during periods that match its design regime (trend / range-rotation on bullish EURUSD) and degrades during sustained bearish regimes (2015, 2017, 2019, 2021, 2024). The system is **long-only**, which is structurally insufficient for forex without a macro-regime filter.
+
+Full 12-year backtest summary:
+- Total trades: 3,347
+- Profit Factor: 0.97
+- Win Rate: 50.9%
+- Net result: negative on full period
+- Best year: 2025 (PF 1.92)
+- Worst year: 2015 (bearish EURUSD)
+
+**Conclusion documented in the validation:** the EA's logic is sound, its risk management produced no catastrophic individual losses (largest loss < 0.5R), but a directional system without macro-regime filter cannot be deployed live in forex as-is. A planned v2 will add a daily-SMA200 macro filter and optional symmetric short logic.
+
+This README publishes the negative finding intentionally — the work of validating across 12 years and reporting the result honestly is more relevant to engineering quality than cherry-picked single-year results.
+
+---
+
+## File structure
+
+| File | Purpose |
+|------|---------|
+| `OB_EURUSD_30M_2026_v107.mq5` | Main EA, V1.07 with modular block toggles |
+| `LICENSE` | MIT |
+| `README.md` | This document |
+
+---
+
+## Tech stack
+
+- **MQL5** (MetaTrader 5 native)
+- Originally **Pine Script v6** (TradingView)
+- Validation done on broker M1 data and on OANDA feed cross-check
+
+---
+
+## About the author
+
+**Brayan Rivas Campero** — MQL5 / Pine Script developer based in Cancún, México.  
+8 years building algorithmic trading systems across multiple instruments (Forex, indices, gold) and timeframes (M5, M30, H1, H4).  
+Specialized in cross-platform conversion (TradingView ↔ MetaTrader 5), quantitative validation, and out-of-sample multi-régime analysis.
+
+- LinkedIn: [linkedin.com/in/brayan-rivas-campero-70373b30b](https://www.linkedin.com/in/brayan-rivas-campero-70373b30b/)
+- Email: brivascampero@gmail.com
+
+Available for freelance projects — MQL5 development, Pine Script → MQL5 conversion, strategy optimization, backtesting and validation reports.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).