mql-trading-bots/AGENTS.md

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: v5.0
• Key Settings:
  • MagicNum = 333
  • UseAutoPivots = true
  • InpCloseBeforeWeekend = true (v3.1)
  • GridHigh/GridLow now correctly uses ATR bands (v3.3 fix)
  • MaxLevels = 10

Common Tasks

Deploying EAs to MT5

# 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

cd /home/garfield/mql-trading-bots
python3 verify-short-signals.py

Checking MT5 Status

cd ~/mt5-docker && ./STATUS.sh

Viewing Reports

# 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

// 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

// WRONG (restrictive - blocks shorts when price above pivot)
if(nearResistance || (rejectedFromResistance && belowPivot))

// CORRECT (mirrors BUY logic)
if(nearResistance || rejectedFromResistance)

v3.3 - Grid Range & Filter Fix

// WRONG (uses PivotR1/S1, ignores ATR bands)
double actualHigh = (InpManualHigh > 0) ? InpManualHigh : PivotR1;
double actualLow = (InpManualLow > 0) ? InpManualLow : PivotS1;

// CORRECT (uses ATR-based GridHigh/GridLow)
double actualHigh = (InpManualHigh > 0) ? InpManualHigh : GridHigh;
double actualLow = (InpManualLow > 0) ? InpManualLow : GridLow;

v5.0 - Edge Position Cleanup

// WRONG (range filter cancels grid but leaves stranded positions)
if(!IsRangingMarket())
  {
   CancelAllOrders("Range filter tripped");
   gridPlaced = false;
   return;  // positions bleed in the R2/S2 gap
  }

// CORRECT (close wrong-side positions when price exits grid)
if(!IsRangingMarket())
  {
   CancelAllOrders("Range filter tripped");
   gridPlaced = false;
   if(currentPrice > actualHigh)
      ClosePositionsBySide(POSITION_TYPE_SELL, "Edge cleanup — above GridHigh");
   else if(currentPrice < actualLow)
      ClosePositionsBySide(POSITION_TYPE_BUY, "Edge cleanup — below GridLow");
   return;
  }

v3.1 - Weekend Gap Protection

// 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 <Trade\Trade.mqh>
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

# 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

DevOps / Infrastructure

Server infrastructure details saved in: /home/garfield/devops/INFRASTRUCTURE.md

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
~/conversation-history/2026-03-30-dns-whitelist.md
~/conversation-history/2026-04-07-confluence-ea-diagnosis.md
~/conversation-history/2026-04-13-new-account-grid-issue.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