# PROJECT_CONTEXT.md — crypto_trading_bot > À lire avant toute intervention sur ce repo. Ce bot exécute des ordres réels > (spot, Kraken). Une modification incorrecte a un coût financier direct. > Ce fichier est la source de vérité principale pour ce dossier serveur. > Il est **volontairement exclu de Git** (`.gitignore` : règle `*.md`, comme > tous les `.md` du repo, et `config.py` est exclu séparément). Ce n'est pas > une anomalie à corriger : ne pas forcer son ajout avec `git add -f`, il est > local au serveur par choix (comme `config.py`, qui contient les clés API). ## Source de vérité / priorité - `PROJECT_CONTEXT.md` est le document principal pour les règles de sécurité, l’architecture et le périmètre des fichiers critiques. - En cas de divergence avec `CLAUDE.md`, `PROJECT_CONTEXT.md` prévaut pour les décisions de sécurité et de périmètre. ## Règle n°1 — Ne jamais déplacer, renommer ou modifier sans validation humaine explicite Ces fichiers sont **actifs en production** (process tournant en continu sur le VPS) : - `trading_bot.py` — bot principal, exécute les ordres réels - `market_spy.py` — détection de surges/entrées, place des ordres - `dashboard_api_server.py` — API du dashboard (redémarré automatiquement toutes les 5 min par `watchdog_dashboard.sh` via cron, avec un **chemin absolu** — ne pas déplacer sans mettre à jour ce script en même temps, dans le même commit) - `bot_watchdog.py` — surveillance du bot principal - `auto_updater_service.py` — alimente `historical_data/` en continu - `config.py` — **contient les clés API et les paramètres de risque** Chaîne IA/scoring (tous importés directement par `ai_predictor.py`, actifs) : `ai_advanced_scorer.py`, `ai_compatibility_scorer.py`, `ai_sell_predictor.py`, `advanced_feature_engineering.py`, `advanced_strategies.py`, `correlation_analyzer.py`, `ensemble_ml.py`, `ensemble_predictor.py`, `feature_engineering.py`, `long_term_trend_analyzer.py`, `lstm_reversal_predictor.py`, `monte_carlo_simulator.py`, `multi_timeframe_analyzer.py`, `outlier_detection.py`, `performance_analyzer.py`, `risk_adjusted_scorer.py`, `smart_entry_criteria.py`, `smart_rotation.py`, `technical_analyzer.py`, `time_pattern_analyzer.py`, `volatility_scorer.py`, `volume_profile_analyzer.py`, `market_context.py`, `market_regime_detector.py`, `ai_predictor.py` Modules d'optimisation/ré-entraînement également actifs (appelés depuis le dashboard ou l'auto-updater) : `ai_optimizer.py`, `ai_optimized_config.py`, `optimized_config.py`, `ai_self_optimizer.py`, `ai_realtime_service.py`, `train_ai_model.py`, `ai_adaptive_retrainer.py`. Autres fichiers cœur : `market_safety.py`, `market_behavior.py`, `market_regime.py`, `market_regime_detector.py`, `dynamic_sltp.py`, `pattern_manager.py`, `smart_entry_criteria.py`, `smart_rotation.py`, `execution_logger.py`, `signal_aggregator.py`, `signals_consumer.py`, `trade_logger.py`, `analyze_trade_logs.py`, `spy_exit_analyzer.py`, `spy_param_patcher.py`, dossier `api/` entier. Scripts manuels destructifs (à utiliser en connaissance de cause, jamais via une IA sans confirmation) : `sell_all.py` (vend toutes les positions), `Reset_trading.py` (reset complet de l'état de trading). Données live (jamais toucher, jamais recopier leur contenu dans un fichier versionné) : `positions.json`, `positions_backup*.json`, `watchlist.json`, `bot_settings.json`, `trading_profiles.json`, `trading_pause.json`, `bot.pid`, `market_spy.pid`, `signal_aggregator.pid`, `spy_prod.pid`, `spy_testnet.pid`, `watchdog.pid`, `auto_updater.pid`, `.api_token`, `.dashboard_auth`, `.freeze_reset_time`, `bot.disabled`. ## Pièges connus du repo - **`legacy/outils_ponctuels/cleanup_obsolete_files.py`** contient une liste `OBSOLETE_FILES` **périmée** qui cite à tort des fichiers actifs (`config.py`, `trading_bot.py`, `market_regime_detector.py`...) comme obsolètes. Ne jamais s'y fier ni l'exécuter tel quel. - **`crypto_trading_prod/`** est un déploiement créé en vue d'un passage en trading réel, arrêté suite à des résultats catastrophiques en test. **Hors périmètre** de ce repo — ne pas le documenter, ne pas le réorganiser en même temps que `crypto_trading_bot/`. Contient sa propre copie de `market_spy.py` ; vérifier manuellement qu'aucun process n'y tourne encore avant toute action dessus. - Aucun système de supervision type systemd/pm2/tmux/screen n'est en place pour les process actifs autres que `dashboard_api_server.py` (couvert par le cron `watchdog_dashboard.sh`). Un redémarrage serveur nécessite un relancement manuel des 5 autres process — vérifier avant toute intervention qui touche à leur disponibilité. - Une référence trouvée par simple recherche texte ne veut pas dire "vivant" : beaucoup de références historiques pointent vers des `.md` aujourd'hui archivés dans `docs_archive/`. Le seul critère fiable est la chaîne d'import réelle depuis un des 5 process actifs. - `spy_optimizer/` : sous-système actif mais volontairement non audité avec le reste — traiter dans un audit dédié si nécessaire. - **`sell_all.py` n'est PAS migré vers Kraken (vérifié 08/08/2026)** : ce script destructif critique importe encore `from binance.client import Client` et s'authentifie avec `Client(config.BINANCE_API_KEY, config.BINANCE_API_SECRET, testnet=config.TESTNET_MODE)`. Or `BINANCE_API_KEY/SECRET` ne sont plus que des alias vers les vraies clés Kraken (voir `config.py`) : un appel réel à `sell_all.py` tentera de s'authentifier sur le vrai Binance (testnet ou prod) avec des clés Kraken et échouera très probablement. **Ne pas supposer que `sell_all.py --force` fonctionne** tant qu'il n'a pas été migré et testé explicitement. - **`volatility_scorer.py` n'est pas migré non plus** (toujours `binance.client.Client`), alors qu'il est activement importé en lazy-import par `ai_predictor.py` (`VOLATILITY_SCORER_AVAILABLE`). Les endpoints publics Binance restent accessibles sans clé valide, donc ce module continue de tourner mais lit des données de marché **Binance**, potentiellement décorrélées des prix réellement tradés sur Kraken. ## Infrastructure - Backend dashboard : `routes.py`, `security.py` (gère `.api_token`), `services.py`, `models.py`, `utils.py`, `dashboard.html`, `mobile.html`, `telegram_notifier.py` - Récupération de données : `historical_data_updater.py`, `fetch_historical_data.py`, `crypto_data_fetcher.py` - Modèles ML actifs : `models/lstm_reversal.pt`, `models/predictor.pt` - Logs et exécutions réelles (source de vérité, ne jamais supprimer) : `exec_logs/`, `trade_logs/` ## Dossiers d'archive existants (contenu inerte, hors périmètre d'analyse) `scripts_debug/` (`checks/`, `analyzers/`, `backtests/`, `diagnostics/`, `maintenance_manuelle/`, `monitoring_ponctuel/`), `docs_archive/` (`analyses/`, `fixes/`, `guides/`, `rapports/`), `legacy/` (`freqai_experiment/`, `outils_ponctuels/`, `test_optimisation/`), `archive_legacy/`, `legacy_windows_scripts/` (non exécutables sur ce serveur Linux), `backups_archive/`, `logs_archive/`, `debug_output_archive/`, `data_archive_ponctuelle/` Sous-projet séparé, à auditer indépendamment si besoin : `spy_optimizer/` (2.7 Go, sous-système GPU actif). ## Environnement de trading - **Bascule Binance → Kraken effectuée dans la chaîne active (vérifié 08/08/2026 par lecture directe du code, pas par supposition).** `config.py` définit désormais `KRAKEN_API_KEY`/`KRAKEN_API_SECRET` comme vraies clés ; `BINANCE_API_KEY`/ `BINANCE_API_SECRET` ne sont plus qu'un **alias temporaire** vers ces mêmes valeurs (commentaire explicite dans `config.py`), gardé pour ne pas casser les fichiers non encore migrés. Cet alias est prévu pour être supprimé une fois la migration totale. - Fichiers confirmés migrés vers `api.kraken.com` : `trading_bot.py`, `market_spy.py`, `dashboard_api_server.py`, `api/routes.py`, `api/services.py`, `crypto_data_fetcher.py`, `market_regime.py`, `smart_rotation.py`, `historical_data_updater.py`, `fetch_historical_data.py`, `Reset_trading.py`, `ai_predictor.py` (partiel, voir ci-dessous pour `volatility_scorer.py`). - **`TESTNET_MODE` a changé de sens avec la migration** : Kraken Spot n'a pas de testnet public. `TESTNET_MODE = True` signifie désormais **DRY-RUN** (lecture de données réelles, mais aucun ordre envoyé), et non plus un endpoint testnet séparé comme sous Binance. - Fichiers confirmés **non migrés**, encore sur le SDK `python-binance` réel : voir la section "Pièges connus" (`sell_all.py`, `volatility_scorer.py`). Les scripts dans `scripts_debug/` et `legacy/` utilisant aussi `binance.client` sont hors périmètre actif (inertes), pas de risque immédiat. - Le passage du testnet (dry-run) au réel se fait uniquement après validation manuelle des résultats — jamais automatique. ## Méthodologie attendue de toute IA travaillant sur ce repo 1. **Recherche avant action** : cartographier/comprendre avant de proposer un changement. 2. **Aucune modification directe sur un fichier de la Règle n°1** sans confirmation explicite, même en mode agent autonome. 3. Pour tout fichier classé "inconnu" (rôle incertain) : vérifier par recherche de référence dans tout le repo (imports, appels shell, cron) avant de le déplacer. La vérification cron/systemd/process actifs côté serveur reste à la charge de l'utilisateur, aucun outil IA n'y a accès depuis l'éditeur. 4. Archiver plutôt que supprimer (déplacement vers un dossier dédié, jamais de suppression directe sans période d'observation). 5. Ne pas halluciner de structure de code (noms de variables, dictionnaires de paramètres, endpoints Kraken) sans l'avoir lue explicitement dans le fichier réel — vérifier l'existence exacte d'un identifiant avant de proposer un changement dessus.