gavindiaz/dbasket-EA

Fork 0

mirror of https://github.com/dinethlive/dbasket-EA.git synced 2026-07-27 18:57:45 +00:00

Files

T

dinethlive d096485f7c Initial commit: D-Basket EA v2.0 Pro

2025-12-28 03:37:48 +05:30

15 KiB

Raw Permalink Blame History

D-Basket EA v2.0 - Technical Documentation

Architecture Overview
v1.0 Core Modules
🆕 v2.0 Optimization Modules
Data Flow
Signal Processing Pipeline
Risk Management System
Implementation Details
Testing & Validation

Architecture Overview

The D-Basket EA v2.0 implements a modular, event-driven architecture with 11 core modules (8 from v1.0 + 3 new optimization modules).

graph TB
    subgraph "Main EA"
        EA[DBasketEA_v2.mq5]
    end
    
    subgraph "v1.0 Core Modules"
        CE[Correlation Engine]
        SE[Signal Engine]
        PM[Position Manager]
        RM[Risk Manager]
        TW[Trade Wrapper]
        LOG[Logger]
    end
    
    subgraph "🆕 v2.0 Optimization Modules"
        COINT[Cointegration Engine]
        HL[Half-Life Engine]
        ATR[Volatility Balancer]
    end
    
    subgraph "Foundation"
        DEF[Defines]
        STRUCT[Structures]
    end
    
    EA --> CE
    EA --> SE
    EA --> PM
    EA --> RM
    EA --> COINT
    EA --> HL
    EA --> ATR
    
    SE --> COINT
    SE --> HL
    PM --> ATR
    
    style EA fill:#4CAF50
    style COINT fill:#FF6B6B
    style HL fill:#FF6B6B
    style ATR fill:#FF6B6B

File Structure

MQL5/
├── Experts/
│   ├── DBasketEA.mq5                       # v1.0 EA (547 LOC)
│   └── DBasketEA_v2.mq5                    # 🆕 v2.0 EA (736 LOC)
└── Include/
    └── DBasket/
        ├── DBasket_Defines.mqh             # Constants & Enums (149 LOC)
        ├── DBasket_Structures.mqh          # Data Structures (524 LOC)
        ├── DBasket_Logger.mqh              # Logging System (424 LOC)
        ├── DBasket_CorrelationEngine.mqh   # Correlation Calc (401 LOC)
        ├── DBasket_SignalEngine.mqh        # Signal Generation (401 LOC)
        ├── DBasket_TradeWrapper.mqh        # Trade Execution (400 LOC)
        ├── DBasket_PositionManager.mqh     # Basket Management (572 LOC)
        ├── DBasket_RiskManager.mqh         # Risk Control (424 LOC)
        ├── 🆕 DBasket_CointegrationEngine.mqh  # ADF Test (450 LOC)
        ├── 🆕 DBasket_HalfLifeEngine.mqh       # O-U Half-Life (465 LOC)
        └── 🆕 DBasket_VolatilityBalancer.mqh   # ATR Sizing (360 LOC)

Total Lines of Code: ~5,307 (v1.0: ~2,880 | v2.0 additions: ~2,427)

v1.0 Core Modules

1. Correlation Engine

Purpose: Calculate rolling correlation and z-score for the three-pair relationship.

Key Features:

Circular buffer for price history
Pearson correlation coefficient
Z-score computation
Cache optimization (30s validity)

Mathematical Foundation:

Synthetic Ratio = AUDCAD / NZDCAD
Spread = ratio - AUDNZD
Z-Score = (spread - μ) / σ

2. Signal Engine

Purpose: Generate entry/exit signals with 8-stage validation.

Entry Filters:

Data validity
No existing basket
Trading hours check
Rollover avoidance
Spread validation
Correlation threshold
Volatility check
Z-score threshold

3. Position Manager

Purpose: Execute coordinated 3-leg basket trades.

Basket Configurations:

Direction	AUDNZD	AUDCAD	NZDCAD
LONG	BUY	SELL	BUY
SHORT	SELL	BUY	SELL

4. Risk Manager

Purpose: Monitor risk limits and circuit breaker.

Risk Limits:

Drawdown: 8% warning, 15% trip
Daily Loss: $100 or 5%
Margin: 500% warning, 200% trip
Consecutive Losses: 6 trips breaker

🆕 v2.0 Optimization Modules

1. Cointegration Engine (ADF Test)

Purpose: Validate that the spread is statistically mean-reverting before trading.

Algorithm:

flowchart LR
    A[Price Data] --> B[OLS Regression]
    B --> C[Extract Residuals]
    C --> D[AR1 Regression]
    D --> E[Calculate ADF Statistic]
    E --> F{ADF < -2.86?}
    F -->|Yes| G[Cointegrated ✓]
    F -->|No| H[Not Cointegrated ✗]

Mathematical Details:

Step 1: OLS Regression

AUDNZD = α + β × (AUDCAD/NZDCAD) + ε

Extract residuals ε (the spread)

Step 2: ADF Test on Residuals

Δε_t = α + γ × ε_{t-1} + noise
ADF Statistic = γ / SE(γ)

Step 3: Critical Values

ADF Value	P-Value	Interpretation
< -3.43	0.01	Strong cointegration
< -2.86	0.05	Valid cointegration ✓
< -2.57	0.10	Weak cointegration
> -2.57	> 0.10	Not cointegrated ✗

Impact: Only trades when p < 0.05 (default), filtering out non-stationary spreads.

Expected Improvement: Win rate +8-15%

2. Half-Life Engine (Ornstein-Uhlenbeck)

Purpose: Calculate optimal exit timing based on mean-reversion speed.

Algorithm:

flowchart LR
    A[Spread Series] --> B[AR1 Regression]
    B --> C[Extract λ]
    C --> D{λ < 0?}
    D -->|Yes| E[Calculate Half-Life]
    D -->|No| F[Non-Reverting ✗]
    E --> G[τ = -ln2 / λ]
    G --> H[Max Hold = 2 × τ]

Mathematical Details:

Step 1: AR(1) Regression

Δspread_t = α + λ × spread_{t-1} + ε

Step 2: Half-Life Calculation

Half-Life (τ) = -ln(2) / λ

Where:

λ < 0 indicates mean reversion
τ = number of bars for 50% reversion

Step 3: Exit Logic

Max Holding Time = 2 × τ bars
Stop Loss = Entry Z-Score + 1.5σ

Example:

If λ = -0.05, then τ = 13.9 bars
Max hold = 27.8 bars (~28 bars)
If spread diverges further by 1.5σ, exit immediately

Impact: Prevents holding positions too long or exiting too early.

Expected Improvement: Drawdown -15-20%

3. Volatility Balancer (ATR-Based)

Purpose: Balance risk across all 3 legs using inverse volatility weighting.

Algorithm:

flowchart LR
    A[Get ATR14] --> B[Calculate Weights]
    B --> C[w_i = 1/ATR_i]
    C --> D[Normalize Σw = 1]
    D --> E[Lots_i = Base × w_i × 3]

Mathematical Details:

Step 1: ATR Calculation

ATR_i = 14-period Average True Range for symbol i

Step 2: Inverse Volatility Weights

weight_i = (1 / ATR_i) / Σ(1 / ATR_j)

Step 3: Lot Allocation

lots_i = base_lots × weight_i × 3

Example:

Symbol	ATR	1/ATR	Weight	Base=0.01	Final Lots
AUDCAD	0.0050	200	0.40	0.01	0.012
NZDCAD	0.0040	250	0.50	0.01	0.015
AUDNZD	0.0080	125	0.10	0.01	0.003

Result: High-volatility AUDNZD gets smaller lot, low-volatility NZDCAD gets larger lot.

Impact: Equal risk contribution from each leg.

Expected Improvement: Sharpe ratio +10-15%

Data Flow

v2.0 OnTick Event Processing

flowchart TD
    START([OnTick]) --> RM[Risk Check]
    RM --> UPDATE[Update Prices]
    UPDATE --> CORR[Calculate Correlation]
    
    CORR --> NEWBAR{New Bar?}
    NEWBAR -->|Yes| COINT[Update Cointegration]
    COINT --> HL[Update Half-Life]
    HL --> ATR[Update ATR Weights]
    NEWBAR -->|No| SKIP[Skip Updates]
    
    ATR --> BASKET{Basket Open?}
    SKIP --> BASKET
    
    BASKET -->|Yes| CHECK_EXIT{Exit Signal?}
    CHECK_EXIT -->|Standard| CLOSE1[Close Basket]
    CHECK_EXIT -->|Half-Life Time| CLOSE2[Close Basket]
    CHECK_EXIT -->|Half-Life SL| CLOSE3[Close Basket]
    CHECK_EXIT -->|Coint Break| CLOSE4[Close Basket]
    CHECK_EXIT -->|No| HOLD[Hold]
    
    BASKET -->|No| PREFILTER{Cointegrated?}
    PREFILTER -->|No| REJECT[Skip Trade]
    PREFILTER -->|Yes| HLVALID{Half-Life Valid?}
    HLVALID -->|No| REJECT
    HLVALID -->|Yes| SIGNAL[Check Signal]
    SIGNAL --> OPEN{Signal?}
    OPEN -->|Yes| CALC_LOTS[ATR Weighted Lots]
    CALC_LOTS --> EXECUTE[Open Basket]
    OPEN -->|No| REJECT
    
    style COINT fill:#FF6B6B
    style HL fill:#FF6B6B
    style ATR fill:#FF6B6B
    style CALC_LOTS fill:#FF6B6B

Signal Processing Pipeline

v2.0 Entry Validation

flowchart TD
    START([Entry Signal Request]) --> F1{Data Valid?}
    F1 -->|No| REJECT[❌ Reject]
    F1 -->|Yes| F2{🆕 Cointegrated?}
    F2 -->|No| REJECT
    F2 -->|Yes| F3{🆕 Half-Life Valid?}
    F3 -->|No| REJECT
    F3 -->|Yes| F4{Trading Hours?}
    F4 -->|No| REJECT
    F4 -->|Yes| F5{Spread OK?}
    F5 -->|No| REJECT
    F5 -->|Yes| F6{Correlation > Min?}
    F6 -->|No| REJECT
    F6 -->|Yes| F7{|Z-Score| > Entry?}
    F7 -->|No| REJECT
    F7 -->|Yes| ACCEPT[✅ Accept Signal]
    
    style F2 fill:#FF6B6B
    style F3 fill:#FF6B6B
    style ACCEPT fill:#4CAF50
    style REJECT fill:#f44336

v2.0 Exit Logic

flowchart TD
    START([Check Exit]) --> E1{Z-Score Reverted?}
    E1 -->|Yes| EXIT1[Mean Reversion Exit]
    E1 -->|No| E2{P&L ≥ TP?}
    E2 -->|Yes| EXIT2[Take Profit]
    E2 -->|No| E3{P&L ≤ SL?}
    E3 -->|Yes| EXIT3[Stop Loss]
    E3 -->|No| E4{🆕 Bars > 2×HalfLife?}
    E4 -->|Yes| EXIT4[Half-Life Time Exit]
    E4 -->|No| E5{🆕 Z > Entry+1.5σ?}
    E5 -->|Yes| EXIT5[Half-Life Variance SL]
    E5 -->|No| E6{🆕 Coint p > 0.10?}
    E6 -->|Yes| EXIT6[Cointegration Break]
    E6 -->|No| E7{Correlation < 0.5?}
    E7 -->|Yes| EXIT7[Correlation Break]
    E7 -->|No| HOLD[Hold Position]
    
    style E4 fill:#FF6B6B
    style E5 fill:#FF6B6B
    style E6 fill:#FF6B6B

Implementation Details

v2.0 Input Parameters

// === v2.0 OPTIMIZATION SETTINGS ===

// Cointegration Filter
input bool     InpCointEnabled = true;      // Enable?
input double   InpCointPValue = 0.05;       // P-Value Threshold
input int      InpCointUpdateBars = 50;     // Update Interval (bars)
input int      InpCointADFLags = 1;         // ADF Lags

// Half-Life Exits
input bool     InpHLEnabled = true;         // Enable?
input int      InpHLUpdateBars = 20;        // Update Interval (bars)
input int      InpHLMinValue = 10;          // Min Half-Life (bars)
input int      InpHLMaxValue = 500;         // Max Half-Life (bars)
input double   InpHLExitMultiplier = 2.0;   // Max Hold Multiplier
input double   InpHLStopLossSigma = 1.5;    // SL Distance (sigma)

// ATR Position Sizing
input bool     InpATREnabled = true;        // Enable?
input int      InpATRPeriod = 14;           // ATR Period
input double   InpATRMinWeight = 0.15;      // Min Weight per Symbol
input double   InpATRMaxWeight = 0.50;      // Max Weight per Symbol

v2.0 Data Structures

CointegrationData

struct CointegrationData {
    double adfStatistic;        // ADF test statistic
    double pValue;              // Approximate p-value
    double beta;                // Hedge ratio from OLS
    double alpha;               // Intercept
    double residualStdDev;      // Residual std dev
    datetime lastUpdateTime;
    bool isCointegrated;        // p < threshold
    bool isValid;
};

HalfLifeData

struct HalfLifeData {
    double lambda;              // AR(1) coefficient
    double halfLife;            // Calculated half-life (bars)
    double sigma;               // Residual std dev
    double ouVariance;          // O-U variance
    datetime lastUpdateTime;
    bool isMeanReverting;       // lambda < 0
    bool isValid;
};

VolatilityData

struct VolatilityData {
    double atr[NUM_SYMBOLS];    // ATR values
    double weights[NUM_SYMBOLS]; // Inverse vol weights
    double adjustedLots[NUM_SYMBOLS]; // Final lots
    datetime lastUpdateTime;
    bool isValid;
};

Testing & Validation

Compilation Status

✅ v1.0: Successfully compiled with 0 errors, 0 warnings
✅ v2.0: Successfully compiled with 0 errors, 0 warnings

v2.0 Expected Performance

Metric	v1.0 Baseline	v2.0 Target	Improvement
Win Rate	~60%	75-82%	+15-22%
Profit Factor	~0.9	1.5-2.0	+67-122%
Max Drawdown	~15%	8-12%	-20-47%
Trade Frequency	High	-30-40%	Quality over quantity
Sharpe Ratio	~0.5	0.8-1.2	+60-140%

Testing Workflow

flowchart TD
    START([Start]) --> COMPILE[Compile v2.0]
    COMPILE --> BACKTEST[Backtest 3 Years]
    BACKTEST --> COMPARE{Better than v1.0?}
    
    COMPARE -->|No| DEBUG[Debug/Adjust]
    DEBUG --> BACKTEST
    
    COMPARE -->|Yes| OPTIMIZE[Optimize Parameters]
    OPTIMIZE --> WALKFORWARD[Walk-Forward Analysis]
    WALKFORWARD --> DEMO[Demo Account 1+ Month]
    
    DEMO --> VALIDATE{Matches Backtest?}
    VALIDATE -->|No| REVIEW[Review Execution]
    REVIEW --> OPTIMIZE
    
    VALIDATE -->|Yes| LIVE[Consider Live]
    
    style START fill:#4CAF50
    style LIVE fill:#4CAF50

Key Validation Points

Cointegration: p-value should be < 0.05 for 60-80% of potential trades
Half-Life: Should range 10-200 bars for most spreads
ATR Weights: Should vary between 0.15-0.50 per symbol
Win Rate: Should exceed 70% in backtests
Profit Factor: Should exceed 1.5 in backtests

Configuration Guidelines

v2.0 Conservative Settings

// Cointegration
InpCointPValue = 0.01          // Very strict
InpCointUpdateBars = 30        // Frequent updates

// Half-Life
InpHLExitMultiplier = 1.5      // Earlier exits
InpHLStopLossSigma = 1.0       // Tighter SL

// ATR
InpATRPeriod = 20              // Longer period

v2.0 Moderate Settings (Default)

// Cointegration
InpCointPValue = 0.05          // Standard
InpCointUpdateBars = 50        // Balanced

// Half-Life
InpHLExitMultiplier = 2.0      // Standard
InpHLStopLossSigma = 1.5       // Balanced

// ATR
InpATRPeriod = 14              // Standard

v2.0 Aggressive Settings

// Cointegration
InpCointPValue = 0.10          // More permissive
InpCointUpdateBars = 100       // Less frequent

// Half-Life
InpHLExitMultiplier = 3.0      // Longer holds
InpHLStopLossSigma = 2.0       // Wider SL

// ATR
InpATRPeriod = 10              // Shorter period

Version History

v2.00 (2025-12-28)

🆕 Cointegration Engine - ADF test for spread stationarity
🆕 Half-Life Engine - Ornstein-Uhlenbeck mean-reversion timing
🆕 Volatility Balancer - ATR-based risk parity sizing
✅ 3 new optimization modules (~1,275 LOC)
✅ Enhanced entry/exit logic
✅ Comprehensive v2.0 documentation
✅ Expected win rate: 75-82%

v1.00 (2025-12-28)

✅ Initial implementation
✅ 8 modular components
✅ Circuit breaker system
✅ Comprehensive logging
✅ Fixed MQL5 deprecations

Support & Resources

Documentation Files

README.md - Documentation index
QUICK_START.md - Installation and setup
DEVELOPMENT_SUMMARY.md - Project history
TECHNICAL_DOCUMENTATION.md - This file

Source Code

MQL5/Experts/DBasketEA.mq5 - v1.0 EA
MQL5/Experts/DBasketEA_v2.mq5 - v2.0 EA
MQL5/Include/DBasket/*.mqh - All modules

External References

MQL5 Documentation: https://www.mql5.com/en/docs
Cointegration Theory: Engle-Granger (1987)
Ornstein-Uhlenbeck Process: Statistical mean reversion
ATR Indicator: Wilder (1978)

📄 License & Copyright

Last Updated: December 28, 2025
Documentation Version: 2.00
Developed by: Dineth Pramodya

15 KiB Raw Permalink Blame History Unescape Escape

D-Basket EA v2.0 - Technical Documentation

Table of Contents

Architecture Overview

File Structure

v1.0 Core Modules

1. Correlation Engine

2. Signal Engine

3. Position Manager

4. Risk Manager

🆕 v2.0 Optimization Modules

1. Cointegration Engine (ADF Test)

2. Half-Life Engine (Ornstein-Uhlenbeck)

3. Volatility Balancer (ATR-Based)

Data Flow

v2.0 OnTick Event Processing

Signal Processing Pipeline

v2.0 Entry Validation

v2.0 Exit Logic

Implementation Details

v2.0 Input Parameters

v2.0 Data Structures

CointegrationData

HalfLifeData

VolatilityData

Testing & Validation

Compilation Status

v2.0 Expected Performance

Testing Workflow

Key Validation Points

Configuration Guidelines

v2.0 Conservative Settings

v2.0 Moderate Settings (Default)

v2.0 Aggressive Settings

Version History

v2.00 (2025-12-28)

v1.00 (2025-12-28)

Support & Resources

Documentation Files

Source Code

External References

📄 License & Copyright

15 KiB

Raw Permalink Blame History