# Oil Trading Bot (MT5, WTI)

Algorithmischer **WTI-Öl-Trading-Bot** auf MetaTrader 5 mit headless FastAPI-Backend
und Mobile-PWA. Analyse, Strategie, Backtests und LLM-Copilot laufen in Python; MQL5
ist nur eine dünne Zeichen-Schicht fürs Desktop-Terminal.

> **Hinweis:** Interne Doku, Antworten und UI-Texte sind auf Deutsch. Die
> ausführliche Entwickler-/Strategie-Dokumentation steht in [`CLAUDE.md`](CLAUDE.md)
> und [`docs/`](docs/).

## Überblick

- **`server.py` + `core/engine.py`** — headless FastAPI-Web-Backend, das die
  **Mobile-PWA** in [`web/`](web/) bedient (Zugriff vom Handy z. B. via WireGuard).
- **Eine** Oberfläche: die PWA. Das frühere Tkinter-Widget wurde entfernt.
- ⚠ Immer nur **eine** Server-Instanz gegen dasselbe MT5-Terminal laufen lassen
  (zwei TrailingManager = Konflikt).

## Architektur (`core/`)

| Modul | Aufgabe |
|-------|---------|
| `mt5data.py` | Preis / Trend / Konto |
| `trader.py` | Orders + SL/TP |
| `trailing.py` | Trailing / Teil-Exit / Time-Stop |
| `wave_rec.py` | Empfehlung (EMA12/50-Trendfolge, Squeeze-Breakout, Gates) |
| `elliott.py` | Elliott-Wellen / FVG |
| `structure.py` | Marktstruktur (HH/HL/LH/LL, BOS, Regressionskanal — Anzeige) |
| `daily_levels.py` | Tages-Prognose (Web-Recherche) |
| `gaps.py` | D1-Kurslücken |
| `candle_logger.py` | M1-Candle-Log → `candles_m1` |
| `agent.py` | KI-Copilot (LLM) |
| `history.py` | SQLite-Persistenz |
| `config.py` | Konstanten + `oil_widget_config.ini`-Loader |
| `engine.py` | headless Motor: fährt die Loops als Threads, liefert `snapshot()` |

`engine._verdict()` aggregiert die Module zur **Gesamtempfehlung** (`verdict` im
Snapshot) — Details: [`docs/gesamtempfehlung.md`](docs/gesamtempfehlung.md).

## Voraussetzungen

- **Windows** (das `MetaTrader5`-Python-Wheel ist Windows-only; das Backend läuft
  neben dem MT5-Terminal).
- **Python 3.12** mit `fastapi`, `uvicorn`, `MetaTrader5` (+ weitere Abhängigkeiten,
  die die Module importieren).
- Ein laufendes **MetaTrader-5-Terminal** mit dem WTI-Symbol des Brokers
  (z. B. `SpotCrude` bei Pepperstone).

## Einrichtung

1. Repo klonen.
2. Config-Vorlage kopieren und mit echten Keys füllen:
   ```bash
   cp oil_widget_config.ini.example oil_widget_config.ini
   ```
   Dann `oil_widget_config.ini` ausfüllen (LLM-/News-/Telegram-/Graph-Keys, WTI-Symbol,
   Trading-Schalter). **Diese Datei enthält Live-Secrets und ist per `.gitignore`
   vom Repo ausgeschlossen — niemals committen.** Erläuterungen zu allen
   `[trading]`-Schaltern stehen als Kommentare in [`core/config.py`](core/config.py).
3. MT5-Terminal starten und einloggen.

## Starten

```bash
# Änderungen aktivieren / Server (neu) starten:
restart_server.bat
```

Auto-Start ist als Windows-Aufgabe `OilTradingServer` (Login-Trigger, versteckt via
VBS) eingerichtet. Die PWA ist danach unter `http://<host>:8000/` erreichbar.

## Strategie in Kürze

- **Richtung** = EMA12 vs. EMA50 (`wave_rec.py`), mit Totband, Anti-Überdehnung,
  S/R- und Session-Konfidenz.
- **Volatilitäts-Squeeze-Breakout** = additiver, backtest-validierter Auto-Entry
  (Kompression → Ausbruch); optional autonom (`auto_squeeze`).
- **Gates**: ATR-Breakout-Bestätigung, Entry-Raum, Mindest-Konfidenz, Higher-TF-
  Gegen-Trend, EIA-Blackout.
- **Exit**: SL-Band ~2×ATR, Breakeven ab +1,3×ATR, Trailing, Time-Stop, sowie ein
  kalibriertes **P(Durchbruch)-Modell** für den S/R-Close am Gegenlevel.

> **Methodik:** Strategie-Änderungen werden per **2-Stichproben-Backtest** (zwei
> Zeiträume/Regime) mit **echten Kosten** belegt, bevor sie live gehen — „erst
> messen, dann umbauen". Die zahlreichen `backtest_*.py`-Skripte dokumentieren
> geprüfte und verworfene Ideen.

## Nützliche Skripte

| Befehl | Zweck |
|--------|-------|
| `python backtest_signal.py [TF] [N] [K]` | Empfehlungs-Edge messen (ereignisbasiert) |
| `python analyze_execution.py` | Spread-/Slippage-/MAE-MFE-Kalibrierung |
| `python weekly_review.py` | Wochenreport (Live-Stats vs. Backtest-Erwartung) |
| `python -m py_compile <datei>` | Syntaxprüfung vor „fertig" |

## Web-Assets

Der Browser cacht hart: bei jeder JS/CSS-Änderung in `web/index.html` die
Asset-Version `?v=N` **hochzählen**. Der Server sendet `Cache-Control: no-store`.

## Datenhaltung

- **`oil_widget_history.db`** (SQLite): `trades`, `recommendations`, `candles_m1` u. a.
  Nicht im Repo (per `.gitignore`) — vor Eingriffen Backup (`*.bak-<datum>`).
- Laufzeit-State (`emergency_state.json`, `runtime_state.json`, `report_state.json`)
  wird vom Server erzeugt und ist ebenfalls nicht versioniert.

## Lizenz

Privates Projekt — keine Lizenz vergeben.