# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Vue d'ensemble

MidasBot est un bot de trading/arbitrage crypto assisté par IA, en **dry-run** (aucune clé d'échange réelle, aucun risque). Trois briques découplées par Redis :

- **Freqtrade** (moteur) — backtesting, dry-run, FreqUI, connecteurs CEX. Tourne en **conteneurs Docker**.
- **Couche IA** (`ai_analyzer/`) — Claude produit un "biais de marché" qui peut filtrer une stratégie. **Via le CLI `claude` (abonnement), PAS l'API facturée.**
- **Arbitrage** (`arbitrage/`) — scan d'écarts inter-CEX (dry-run).

## ⚠️ Contraintes d'environnement non-évidentes

- **Python local = 3.9** (trop ancien pour Freqtrade qui exige 3.11+). → **Tout passe par Docker.** Le `.venv` (3.9) ne sert qu'aux scripts hôte légers (`ai_analyzer`, `arbitrage`, `dashboard`, parsing) qui n'importent pas Freqtrade.
- **Image Freqtrade custom** : `freqtrade/Dockerfile` = image officielle + `redis` (pour qu'`AiBiasStrategy` lise les biais en live). `docker compose build freqtrade` après modif.
- **Ports hôte** : freqtrade/FreqUI `8080`, dashboard `8500`, redis **`6380`** (le 6379 est pris par un autre projet ; les conteneurs internes utilisent quand même `redis:6379`).
- **Secrets via env** : Freqtrade lit `FREQTRADE__SECTION__CLE` depuis `.env` (ex. `FREQTRADE__API_SERVER__JWT_SECRET_KEY`, ≥32 car.). Jamais de secret dans les `config_*.json`.

## Commandes

```bash
# Stack par défaut (freqtrade dry-run live + redis + dashboard)
docker compose up -d
docker compose --profile ai --profile arb up -d     # + ai-analyzer + arbitrage
docker compose logs -f freqtrade

# Backtest / hyperopt / data : TOUJOURS via `run --rm --no-deps freqtrade ...`
docker compose run --rm --no-deps freqtrade backtesting \
  --config /freqtrade/user_data/<CONFIG>.json --strategy <STRAT> \
  --timeframe 1h --timerange 20260101- --breakdown month
docker compose run --rm --no-deps freqtrade download-data \
  --config /freqtrade/user_data/<CONFIG>.json --timeframes 1h 4h 1d \
  --days 365 --prepend --trading-mode futures
docker compose run --rm --no-deps freqtrade hyperopt \
  --config /freqtrade/user_data/<CONFIG>.json --strategy <STRAT> \
  --hyperopt-loss SharpeHyperOptLoss --spaces buy sell roi stoploss trailing \
  --timeframe 1h --timerange <TRAIN> --epochs 200 -j 4
docker compose run --rm --no-deps freqtrade list-strategies --config /freqtrade/user_data/<CONFIG>.json

# Exécuter du Python DANS l'image freqtrade (l'ENTRYPOINT est `freqtrade`) :
docker compose run --rm --no-deps --entrypoint python3 freqtrade -c "..."

# Walk-forward (train glissant -> test OOS sur 9 folds)
bash scripts/walkforward.sh            # baseline ; variantes : _chop.sh, _vol.sh

# Couche IA (hôte, utilise le `claude` déjà connecté à l'abonnement)
cd ai_analyzer && REDIS_URL=redis://localhost:6380/0 ../.venv/bin/python analyzer.py --once
../.venv/bin/python backfill.py --start 20260101 --step-hours 24   # génère l'historique de biais
# Setup venv : python3 -m venv .venv && .venv/bin/pip install -r ai_analyzer/requirements.txt
```

**Hyperopt → backtest** : `hyperopt` écrit `<Strategy>.json` (les meilleurs params) que le `backtesting` suivant **auto-charge**. Re-hyperopter **écrase** ce `.json` ; sauvegarder (`cp <S>.json <S>.best.json`) avant un nouveau round. `IchimokuLS` fait exception : ses params sont **figés en dur** (pas de dépendance `.json`).

## Configs (chaque fichier a un usage précis)

| Config | Usage |
|---|---|
| `config_live.json` | **Dry-run live actuel** : futures, `IchimokuLS`, FreqUI ON |
| `config.json` | Spot dry-run, `AiBiasStrategy`, FreqUI |
| `config_futures.json` | Futures 4 majors, FreqUI off (backtests) |
| `config_ich.json` / `config_ich15.json` | Futures wallet 100, 1h / 15m (tests d'optimisation) |
| `config_nfi.json` | Spot 5m, 30 paires (NostalgiaForInfinity) |

Backtests **futures** : pairs suffixées `:USDT`, `trading_mode: futures`, et besoin des données informatives (15m/4h/1d selon la stratégie — NFI exige 5m+15m+1h+4h+1d, sinon **0 trade**).

## Stratégies (`freqtrade/user_data/strategies/`)

- **`IchimokuLS`** — LE keeper. Long/short futures, Ichimoku + filtre macro EMA200. **Validé** train/test + données vierges (+21,6 %) + walk-forward (+17 % OOS composé, 6/9 folds positifs). En dry-run live. Les shorts portent l'edge ; les longs ont besoin d'un marché haussier.
- `IchimokuHyper` / `IchimokuHyper2` / `IchimokuHyper3` — variantes hyperoptables (params dans `.json`).
- `MTFIchimoku` — S/R multi-timeframe (Tenkan/Kijun 1h comme support/résistance sur 15m). Bon Sharpe sur le test mais **overfit** (perd sur données vierges).
- `IchimokuChop`, `IchimokuHyperVol`, `BBMeanRev` — expériences **rejetées** (filtre anti-chop dégrade, vol-targeting neutre, mean-reversion sans edge). Ne pas re-litiger sans nouvelle donnée.
- `AiBiasStrategy` — lit le biais Claude : **Redis en live/dry-run, CSV historisé en backtest** (`merge_asof` par timestamp, aiguillage via `self.dp.runmode`).
- `SampleStrategy` — baseline EMA/RSI. `NostalgiaForInfinityX6` — code tiers, **gitignoré** (re-télécharger depuis github.com/iterativv/NostalgiaForInfinity).

## Couche IA — détails

`ai_analyzer/claude_client.py` invoque `claude -p "<prompt>" --output-format json --json-schema <schema>` en sous-processus. **Auth = abonnement** : `CLAUDE_CODE_OAUTH_TOKEN` ; **ne JAMAIS définir `ANTHROPIC_API_KEY`** (bascule sur la facturation au token — un garde-fou lève une erreur si présent). Modèle léger par défaut (`claude-sonnet-4-6`), cadence basse (1 appel batch/cycle couvrant toutes les paires) pour ménager les limites d'usage. `signal_store.py` écrit dans Redis (`bias:{pair}`, TTL) **et** dans un CSV horodaté (`freqtrade/user_data/ai_bias_history/`) pour backtester l'IA. `.mcp.json` déclare un MCP TradingView optionnel.

## Méthodo de validation (le principe directeur du projet)

L'edge ne se juge **jamais** au gain in-sample (montant indéfiniment = overfitting). Toujours : **train/test séparés**, **walk-forward** (`scripts/walkforward.sh`), et idéalement **données vierges jamais chargées**. Le ratio ajusté du risque (Sharpe/Calmar) plafonne ; au-delà, "plus de gain" = plus de risque ou de l'overfitting. Le dry-run live est le test final.