From baaac18b84e800b44c03d77eab44337c5da93870 Mon Sep 17 00:00:00 2001 From: Garfield Date: Mon, 30 Mar 2026 00:22:17 -0400 Subject: [PATCH] Add comprehensive documentation for AI handoff - AGENTS.md: Technical context for AI assistants - QUICKREF.md: Quick reference card - README.md: Updated with version history and performance - conversation-history/README.md: Updated session index - 2026-03-30-weekend-gap-short-signal-fix.md: Session notes --- AGENTS.md | 150 +++++++++++++++++++++++++++++++++++++++ QUICKREF.md | 54 ++++++++++++++ README.md | 197 +++++++++++++++++++++++++++++++++++----------------- 3 files changed, 339 insertions(+), 62 deletions(-) create mode 100644 AGENTS.md create mode 100644 QUICKREF.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0f02e7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,150 @@ +# AI Agent Context - MQL Trading Bots + +This file provides context for AI assistants working on this codebase. + +## Project Overview + +- **Type:** MetaTrader 5 Expert Advisors (EAs) for automated forex trading +- **Language:** MQL5 (C++ like) +- **Platform:** MT5 via Wine on Ubuntu server +- **Repository:** https://git.fetcherpay.com/garfield/mql-trading-bots + +## Active EAs + +### 1. MultiSignal_Confluence_EA.mq5 (PRIMARY) +- **Purpose:** Trades based on confluence of 3 signals (Pivot, Candlestick, Harmonic) +- **Current Version:** v1.14 +- **Strategy:** BUY when 2+ signals agree, strength >= 0.90 +- **Key Settings:** + - `InpMagicNumber = 777777` + - `InpMinConfluence = 2` + - `InpMinStrength = 0.90` + - `InpUseVolatilityFilter = true` + - `InpUseADXFilter = true` + - `InpMaxDailyDrawdown = 3.0` + +### 2. OrdersEA_Smart_Grid.mq5 +- **Purpose:** Grid trading around daily pivot levels +- **Current Version:** v3.1 +- **Key Settings:** + - `MagicNum = 333` + - `UseAutoPivots = true` + - `InpCloseBeforeWeekend = true` (v3.1 new!) + - `MaxLevels = 10` + +## Common Tasks + +### Deploying EAs to MT5 +```bash +# Copy to MT5 +cp /home/garfield/mql-trading-bots/MultiSignal_Confluence_EA.mq5 \ + ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Experts/ + +cp /home/garfield/mql-trading-bots/OrdersEA_Smart_Grid.mq5 \ + ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Experts/ +``` + +### Verifying Short Signals +```bash +cd /home/garfield/mql-trading-bots +python3 verify-short-signals.py +``` + +### Checking MT5 Status +```bash +cd ~/mt5-docker && ./STATUS.sh +``` + +### Viewing Reports +```bash +# Direct browser access (no VM crash!) +file:///home/garfield/mt5-docker/config/.wine/drive_c/users/abc/Desktop/ReportHistory-104125640.html +``` + +## Critical Bugs Fixed (DO NOT REVERT) + +### v1.11 - Stop Loss Cross-Symbol Contamination +```cpp +// WRONG (uses global CSymbolInfo that gets contaminated) +double sl = SymbolInfo.Ask() - InpStopLoss * SymbolInfo.Point(); + +// CORRECT (uses _Symbol directly) +double ask = SymbolInfoDouble(_Symbol, SYMBOL_ASK); +double point = SymbolInfoDouble(_Symbol, SYMBOL_POINT); +double sl = ask - InpStopLoss * point; +``` + +### v1.14 - Short Signal Detection +```cpp +// WRONG (restrictive - blocks shorts when price above pivot) +if(nearResistance || (rejectedFromResistance && belowPivot)) + +// CORRECT (mirrors BUY logic) +if(nearResistance || rejectedFromResistance) +``` + +### v3.1 - Weekend Gap Protection +```cpp +// Must check Friday before market close +if(dt.day_of_week == FRIDAY && dt.hour >= InpWeekendCloseHour) { + CloseAllPositions("Weekend protection"); + CancelAllOrders("Weekend protection"); +} +``` + +## MT5 Compilation Errors (Common) + +| Error | Fix | +|-------|-----| +| `undeclared identifier 'trade'` | Add `#include ` | +| `undeclared identifier '_Symbol'` | Use `_Symbol` directly (built-in) | +| `invalid stops` | Ensure SL/TP at correct distance from price | +| `cross-symbol contamination` | Use `SymbolInfoDouble(_Symbol, SYMBOL_*)` | + +## File Locations + +| Item | Path | +|------|------| +| Repository | `/home/garfield/mql-trading-bots/` | +| MT5 Experts | `~/mt5-docker/config/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Experts/` | +| MT5 Logs | `~/mt5-docker/config/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Logs/` | +| MT5 Reports | `~/mt5-docker/config/.wine/drive_c/users/abc/Desktop/` | +| Settings (.set) | `~/mt5-docker/config/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Presets/` | + +## MT5 Docker Commands + +```bash +# Check status +cd ~/mt5-docker && ./STATUS.sh + +# Start MT5 +cd ~/mt5-docker && ./start.sh + +# View latest log +tail -100 ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Logs/*.log +``` + +## Performance Metrics + +- **Account 104125640:** ~15-19% return (March 2026) +- **Win Rate:** 46-87% +- **Largest Win:** $8,091 +- **Largest Loss:** -$805 + +## Conversation History + +Before working on this codebase, read: +``` +conversation-history/2026-03-21-mql-trading-bots.md +conversation-history/2026-03-29-session-save.md +conversation-history/2026-03-30-weekend-gap-short-signal-fix.md +``` + +## Notes for AI Agents + +1. **MQL5 is NOT Python** - it's C++ like, with different syntax +2. **Always use `_Symbol`** - never use global SymbolInfo objects +3. **Test compilation** - always verify code compiles before deploying +4. **Copy to MT5** - git commits don't automatically sync to MT5 +5. **Weekend protection** - always enable for Grid EA +6. **Push to Gitea** - use HTTPS with credentials or SSH diff --git a/QUICKREF.md b/QUICKREF.md new file mode 100644 index 0000000..378adea --- /dev/null +++ b/QUICKREF.md @@ -0,0 +1,54 @@ +# MQL Trading Bots - Quick Reference Card + +## Deploy EA to MT5 +```bash +cp MultiSignal_Confluence_EA.mq5 ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Experts/ +cp OrdersEA_Smart_Grid.mq5 ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Experts/ +``` + +## Check MT5 Status +```bash +cd ~/mt5-docker && ./STATUS.sh +``` + +## View Latest Log +```bash +tail -100 ~/mt5-docker/config/.wine/drive_c/Program\ Files/MetaTrader\ 5/MQL5/Logs/*.log +``` + +## View Trading Report +```bash +# Direct browser access +file:///home/garfield/mt5-docker/config/.wine/drive_c/users/abc/Desktop/ReportHistory-104125640.html +``` + +## Verify Short Signals +```bash +python3 verify-short-signals.py +``` + +## Git Commands +```bash +git add -A +git commit -m "description" +git push # May need credentials +``` + +## Current Versions +| EA | Version | +|----|---------| +| MultiSignal_Confluence_EA.mq5 | **v1.14** | +| OrdersEA_Smart_Grid.mq5 | **v3.1** | + +## Critical Reminders +1. ✅ Use `_Symbol` directly (not CSymbolInfo) +2. ✅ Always add `#include ` +3. ✅ Copy files to MT5 after git commit +4. ✅ Enable weekend protection on Grid EA +5. ✅ Test compilation before deploying + +## Key Files +- `AGENTS.md` - AI context (read first!) +- `README.md` - Project overview +- `conversation-history/` - Session notes +- `.set` files - Pair-specific settings diff --git a/README.md b/README.md index 13ccf5b..72f07d2 100644 --- a/README.md +++ b/README.md @@ -2,89 +2,162 @@ Collection of MetaTrader 4/5 Expert Advisors and Indicators for automated forex trading. -## 🎯 Main Strategy: MultiSignal Confluence +## 🎯 Main Strategies -The flagship system combines three proven strategies for high-probability trades: - -1. **Pivot Point Trading** - Support/Resistance levels -2. **Harmonic Pattern Recognition** - AB=CD, Gartley patterns -3. **Candlestick Pattern Analysis** - Hammers, Engulfing, etc. - -### Confluence Logic -``` -When 2+ signals align = HIGH PROBABILITY TRADE +### 1. MultiSignal Confluence EA (PRIMARY) +Combines Pivot Points + Candlestick Patterns + Harmonic Patterns +```cpp Signal Strength: - 1 signal = 0.75 (NO TRADE) - 2 signals = 0.90 (TRADE) - 3 signals = 1.00 (STRONG TRADE) ``` -## 📁 Files +### 2. OrdersEA_Smart_Grid EA +Grid trading around daily pivot levels with RSI/ADX filters -### Primary EAs -| File | Description | Status | -|------|-------------|--------| -| `MultiSignal_Confluence_EA.mq5` | Main confluence trading EA | ✅ Active | -| `MultiSignal_Confluence.mq5` | Indicator version | ✅ Active | +--- -### Component Systems -| File | Description | -|------|-------------| -| `HarmonicPatternFinderV2_Optimized.mq5` | Optimized harmonic pattern detection | -| `CandlestickPatternEA_Fixed.mq5` | Candlestick pattern trading (fixed) | -| `FadePivot2_v4_Fixed.mq5` | Pivot fade strategy (fixed) | +## 📁 File Structure -### Bot Series -| File | Description | -|------|-------------| -| `Bot10001.mq5` | Bot series v1 | -| `Bot10002.mq5` | Bot series v2 | -| `EnhancedEA.mq5` | Enhanced features EA | +``` +mql-trading-bots/ +├── MultiSignal_Confluence_EA.mq5 # PRIMARY EA - Confluence trading (v1.14) +├── OrdersEA_Smart_Grid.mq5 # Grid trading EA (v3.1) +├── MultiSignal_Confluence.mq5 # Indicator version +├── HarmonicPatternFinderV2_Optimized.mq5 +├── CandlestickPatternEA_Fixed.mq5 +├── FadePivot2_v4_Fixed.mq5 +├── confluence-*.set # Settings for Confluence EA (11 pairs) +├── grid-*.set # Settings for Grid EA (14 pairs) +└── verify-short-signals.py # Verification script +``` -## 💰 Performance +--- -**Account 104125640 (March 2026)** -- Starting Balance: $100,000 -- Net Profit: ~$15,000 (15%) -- Win Rate: 46% -- Largest Win: $8,091 -- Largest Loss: -$805 +## 📊 Performance -**Account 103477358 (February 2026)** -- Net Profit: ~$4,155 (4%) +| Account | Period | Return | Win Rate | Status | +|---------|--------|--------|----------|--------| +| 104125640 | March 2026 | ~15-19% | 46-87% | Active | +| 103477358 | February 2026 | ~4% | - | Closed | -## ⚙️ Settings +**Starting Balance:** $100,000 +**Current Balance:** ~$115,000+ +**Largest Win:** $8,091 +**Largest Loss:** -$805 -### Risk Management -- Lot Size: 0.01 (1% risk per trade) -- Stop Loss: 100 points -- Take Profit: 200 points -- Max Positions: 3 per symbol +--- -### Confluence Settings -- Min Confluence: 2/3 signals -- Min Strength: 0.90 -- Require Agreement: Yes (no conflicting signals) +## ⚙️ EA Versions + +### MultiSignal_Confluence_EA.mq5 +| Version | Date | Changes | +|---------|------|---------| +| v1.14 | 2026-03-30 | Fixed short signal detection (removed restrictive belowPivot check) | +| v1.13 | 2026-03-29 | Added daily drawdown protection | +| v1.12 | 2026-03-21 | Added volatility/ADX filters | +| v1.11 | 2026-03-21 | Fixed stop loss cross-symbol contamination | + +### OrdersEA_Smart_Grid.mq5 +| Version | Date | Changes | +|---------|------|---------| +| v3.1 | 2026-03-30 | Added weekend gap protection | +| v3.0 | 2026-03-29 | Fixed daily forced closure bug | + +--- ## 🚀 Deployment -1. Copy EA files to `MQL5/Experts/` -2. Copy Indicator files to `MQL5/Indicators/` -3. Compile in MetaEditor -4. Attach to charts (H1 recommended) +### MT5 Location +``` +~/mt5-docker/config/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Experts/ +``` -## 📝 Notes +### Deployment Steps +1. Copy `.mq5` files to MT5 `MQL5/Experts/` +2. Compile in MetaEditor (F7) +3. Attach to charts (H1 recommended) +4. Load corresponding `.set` file for each pair -- EAs run on MT5 via Wine on Ubuntu server -- Docker container: `mt5-docker` -- Gitea backup ensures code is preserved - -## 🔧 Version History - -- **v1.11** - Fixed stop loss bug (cross-symbol contamination) -- **v1.10** - Initial stable release -- **v1.00** - First profitable version +### MT5 Docker +- **Location:** `~/mt5-docker/` +- **Config:** `mt5-docker/config/.wine/drive_c/Program Files/MetaTrader 5/` +- **Wine Version:** 9.17 (DO NOT upgrade to 10.0+) --- -*Last Updated: March 2026* + +## 🔧 Key Features + +### Confluence EA Settings +```cpp +InpMinConfluence = 2 // Min signals to trade +InpMinStrength = 0.90 // Min signal strength +InpUseVolatilityFilter = true // ATR filter +InpUseADXFilter = true // ADX filter +InpMaxDailyDrawdown = 3.0 // Daily loss limit % +``` + +### Grid EA Settings +```cpp +UseAutoPivots = true // Auto-calculate daily pivots +InpCloseBeforeWeekend = true // Close Friday before weekend +InpWeekendCloseHour = 17 // 5 PM broker time +MaxLevels = 10 // Grid levels +``` + +--- + +## ⚠️ Known Issues & Solutions + +| Issue | Solution | Version | +|-------|----------|---------| +| Stop loss cross-symbol contamination | Use `_Symbol` directly instead of CSymbolInfo | v1.11 | +| Short signals not firing | Removed `belowPivot` restriction | v1.14 | +| Weekend gap risk | Added Friday close option | v3.1 | +| Daily drawdown | Added `CheckDailyDrawdown()` protection | v1.13/v3.0 | + +--- + +## 📈 Recommended Pair Setups + +### Conservative (7 charts) +- USDJPY, EURJPY, EURUSD, AUDUSD, USDCAD (Confluence) +- EURCHF, EURUSD (Grid) + +### Aggressive (12 charts) +Add: GBPUSD, NZDUSD, USDCHF (Confluence) + GBPUSD, USDJPY (Grid) + +### Full Portfolio (15 charts) +Add: GBPJPY, XAUUSD (both EAs) + +--- + +## 🔑 Important Notes + +1. **Symbol-specific positions** - EAs track positions per `_Symbol` +2. **Magic Number** - Confluence: 777777, Grid: 333 +3. **Only LONG trades** - Confluence EA was biased long (v1.13), fixed in v1.14 +4. **Weekend risk** - Always enable `InpCloseBeforeWeekend=true` +5. **Daily DD** - Set `InpMaxDailyDrawdown=3.0` to limit losses + +--- + +## 📂 Conversation History + +See `conversation-history/` directory for session notes: +- `2026-03-21-mql-trading-bots.md` - Initial verification & migration +- `2026-03-29-session-save.md` - Settings library & bug fixes +- `2026-03-30-weekend-gap-short-signal-fix.md` - Weekend protection & short signal fix + +--- + +## 🔗 Links + +- **Gitea:** https://git.fetcherpay.com/garfield/mql-trading-bots +- **MT5 Reports:** `~/mt5-docker/config/.wine/drive_c/users/abc/Desktop/ReportHistory-*.html` + +--- + +*Last Updated: 2026-03-30*