mirror of
https://github.com/dinethlive/dbasket-EA.git
synced 2026-08-17 12:48:16 +00:00
281 lines
7.4 KiB
Markdown
281 lines
7.4 KiB
Markdown
# D-Basket EA - Documentation Index
|
||
|
||
Welcome to the D-Basket EA documentation. This folder contains comprehensive documentation for the three-pair correlation hedging Expert Advisor.
|
||
|
||
---
|
||
|
||
## 📚 Documentation Files
|
||
|
||
### 1. [QUICK_START.md](QUICK_START.md)
|
||
**Start here if you want to get the EA running quickly.**
|
||
|
||
- Installation instructions
|
||
- Essential parameter configuration
|
||
- Pre-flight checklist
|
||
- First backtest setup
|
||
- Troubleshooting common issues
|
||
- Best practices
|
||
|
||
**Best for**: New users, quick reference
|
||
|
||
---
|
||
|
||
### 2. [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md)
|
||
**Deep dive into the EA's architecture and implementation.**
|
||
|
||
- Architecture overview with diagrams
|
||
- Module specifications (v1.0 + v2.0)
|
||
- Data flow diagrams
|
||
- Signal processing pipeline
|
||
- Risk management system
|
||
- v2.0 optimization modules
|
||
- Implementation details
|
||
- Testing guidelines
|
||
|
||
**Best for**: Developers, advanced users, understanding internals
|
||
|
||
**Includes**:
|
||
- 🎨 Mermaid diagrams for architecture
|
||
- 📊 Flowcharts for signal processing
|
||
- 🔄 Sequence diagrams for basket execution
|
||
- 📈 State machine diagrams for circuit breaker
|
||
- 🆕 v2.0 statistical optimization diagrams
|
||
|
||
---
|
||
|
||
### 3. [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md)
|
||
**Complete project history and development process.**
|
||
|
||
- Project overview
|
||
- Development phases (planning → implementation → testing → v2.0 optimization)
|
||
- Architecture highlights
|
||
- Code statistics
|
||
- Testing recommendations
|
||
- Configuration examples
|
||
- Known limitations
|
||
- Next steps
|
||
|
||
**Best for**: Project managers, understanding what was built and why
|
||
|
||
---
|
||
|
||
## 🗂️ Additional Documentation
|
||
|
||
### In Project Root (`MQL5/`)
|
||
|
||
#### [README.md](../MQL5/README.md)
|
||
- User-facing documentation
|
||
- Feature overview
|
||
- Installation guide
|
||
- Parameter reference
|
||
- Backtesting guide
|
||
- Risk warnings
|
||
|
||
### In Brain Folder
|
||
|
||
#### [implementation_plan.md](../../brain/490e5c3e-afaa-482f-8a7e-1c62e5a238e8/implementation_plan.md)
|
||
- v2.0 implementation plan
|
||
- Advanced optimization features
|
||
- Expected performance improvements
|
||
|
||
#### [walkthrough.md](../../brain/490e5c3e-afaa-482f-8a7e-1c62e5a238e8/walkthrough.md)
|
||
- v2.0 implementation walkthrough
|
||
- New modules summary
|
||
- Testing instructions
|
||
|
||
#### [task.md](../../brain/490e5c3e-afaa-482f-8a7e-1c62e5a238e8/task.md)
|
||
- Development task breakdown
|
||
- v2.0 optimization phases
|
||
- Progress tracking
|
||
|
||
---
|
||
|
||
## 🎯 Quick Navigation
|
||
|
||
### I want to...
|
||
|
||
**...install and run the EA**
|
||
→ Start with [QUICK_START.md](QUICK_START.md)
|
||
|
||
**...understand how the EA works**
|
||
→ Read [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md)
|
||
|
||
**...see what was built and why**
|
||
→ Review [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md)
|
||
|
||
**...configure parameters**
|
||
→ See [QUICK_START.md](QUICK_START.md) → Essential Parameters
|
||
→ Or [README.md](../MQL5/README.md) → Input Parameters
|
||
|
||
**...troubleshoot issues**
|
||
→ Check [QUICK_START.md](QUICK_START.md) → Troubleshooting
|
||
|
||
**...optimize the EA**
|
||
→ See [QUICK_START.md](QUICK_START.md) → Parameter Optimization
|
||
→ Or [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) → Testing & Validation
|
||
|
||
**...understand the code structure**
|
||
→ See [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) → Architecture Overview
|
||
|
||
**...see the development process**
|
||
→ Read [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md) → Development Process
|
||
|
||
**...learn about v2.0 optimizations**
|
||
→ See [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) → v2.0 Optimization Modules
|
||
|
||
---
|
||
|
||
## 📊 Visual Documentation
|
||
|
||
All diagrams are embedded in the markdown files using Mermaid syntax. They will render automatically in:
|
||
- GitHub
|
||
- GitLab
|
||
- VS Code (with Mermaid extension)
|
||
- Most modern markdown viewers
|
||
|
||
### Diagram Types Included
|
||
|
||
1. **Architecture Diagrams** - Module relationships and dependencies
|
||
2. **Flowcharts** - Signal processing and decision flows
|
||
3. **Sequence Diagrams** - Basket execution and trade flow
|
||
4. **State Machines** - Circuit breaker states
|
||
5. **Data Flow Diagrams** - OnTick event processing
|
||
6. **🆕 v2.0 Statistical Diagrams** - Cointegration, Half-Life, ATR flows
|
||
|
||
---
|
||
|
||
## 🔍 Key Concepts
|
||
|
||
### Three-Pair Correlation Strategy
|
||
|
||
The EA exploits the mathematical relationship:
|
||
```
|
||
AUDNZD ≈ AUDCAD / NZDCAD
|
||
```
|
||
|
||
When this relationship diverges (measured by z-score), the EA enters a hedged basket expecting mean reversion.
|
||
|
||
### Basket Trading
|
||
|
||
A "basket" consists of 3 coordinated positions:
|
||
- **AUDNZD** - Reference leg
|
||
- **AUDCAD** - Hedge leg 1
|
||
- **NZDCAD** - Hedge leg 2
|
||
|
||
All 3 legs are opened/closed together as a single unit.
|
||
|
||
### 🆕 v2.0 Optimization Features
|
||
|
||
#### Cointegration Filter (ADF Test)
|
||
Only trades when spread is statistically proven to be mean-reverting (p < 0.05).
|
||
|
||
#### Half-Life Exit Timing
|
||
Calculates optimal holding time using Ornstein-Uhlenbeck process. Exits at 2× half-life or if spread diverges further.
|
||
|
||
#### ATR Position Sizing
|
||
Balances risk across all 3 legs using inverse volatility weighting. High-volatility pairs get smaller lots.
|
||
|
||
### Circuit Breaker
|
||
|
||
Automatic risk control system that halts trading when:
|
||
- Drawdown exceeds 15%
|
||
- Daily loss exceeds limit
|
||
- Margin level drops below 200%
|
||
- 6 consecutive losses occur
|
||
|
||
---
|
||
|
||
## 📈 Project Statistics
|
||
|
||
| Metric | v1.0 | v2.0 |
|
||
|--------|------|------|
|
||
| Total Files | 12 | 15 |
|
||
| Lines of Code | ~2,880 | ~3,950 |
|
||
| Documentation Pages | 6 | 7 |
|
||
| Diagrams | 10+ | 15+ |
|
||
| Compilation Status | ✅ 0 errors | ✅ 0 errors |
|
||
|
||
---
|
||
|
||
## ⚠️ Critical Information
|
||
|
||
### Hedging Account Required
|
||
|
||
> **This EA requires a hedging account. It will NOT work on netting accounts.**
|
||
|
||
The EA validates this in `OnInit()` and will fail initialization if the account is not in hedging mode.
|
||
|
||
### Broker Requirements
|
||
|
||
- ✅ Hedging account type
|
||
- ✅ All 3 symbols available (AUDCAD, NZDCAD, AUDNZD)
|
||
- ✅ Spreads < 3 pips per symbol
|
||
- ✅ Fast execution
|
||
- ✅ No hedging restrictions
|
||
|
||
---
|
||
|
||
## 🚀 Getting Started Checklist
|
||
|
||
- [ ] Read [QUICK_START.md](QUICK_START.md)
|
||
- [ ] Install EA files to MT5
|
||
- [ ] Compile in MetaEditor (verify 0 errors)
|
||
- [ ] Configure broker symbol suffix (if needed)
|
||
- [ ] Choose EA version (v1.0 or v2.0)
|
||
- [ ] Run backtest on 1 year of data
|
||
- [ ] Review [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md) for understanding
|
||
- [ ] Optimize parameters
|
||
- [ ] Deploy to demo account
|
||
- [ ] Monitor for 1+ month
|
||
- [ ] Review [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md) for context
|
||
|
||
---
|
||
|
||
## 📝 Version History
|
||
|
||
### v2.00 (2025-12-28)
|
||
- 🆕 **Cointegration Filter** - ADF test for spread stationarity
|
||
- 🆕 **Half-Life Exit Timing** - Ornstein-Uhlenbeck process
|
||
- 🆕 **ATR Position Sizing** - Risk-parity lot allocation
|
||
- ✅ 3 new optimization modules
|
||
- ✅ Enhanced documentation
|
||
- ✅ Expected win rate: 75-82% (up from ~60%)
|
||
|
||
### v1.00 (2025-12-28)
|
||
- ✅ Initial release
|
||
- ✅ Complete implementation
|
||
- ✅ Comprehensive documentation
|
||
- ✅ All diagrams and guides
|
||
|
||
---
|
||
|
||
## 📞 Support
|
||
|
||
For technical questions or issues:
|
||
1. Check [QUICK_START.md](QUICK_START.md) → Troubleshooting
|
||
2. Review [TECHNICAL_DOCUMENTATION.md](TECHNICAL_DOCUMENTATION.md)
|
||
3. Enable DEBUG logging and check log files
|
||
4. Review [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md) → Known Limitations
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
Copyright © 2025 D-Basket EA. All rights reserved.
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 📄 License & Copyright
|
||
|
||
**Copyright © 2025 Dineth Pramodya**
|
||
**Website**: [www.dineth.lk](https://www.dineth.lk)
|
||
**All rights reserved.**
|
||
|
||
---
|
||
|
||
*Last Updated: December 28, 2025*
|
||
*Documentation Version: 2.00*
|
||
*Developed by: Dineth Pramodya*
|