# 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
```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.3 - Grid Range & Filter Fix
```cpp
// 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
```cpp
// 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
```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 <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

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

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