MidasBot/CLAUDE.md

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

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