⚙️ Fichiers de Configuration Freqtrade : Le Guide de référence
Tu as installé Freqtrade grâce au guide complet d'installation, mais tu te demandes comment configurer correctement tes bots ? Les fichiers de configuration déterminent comment, où et avec combien d'argent tes bots vont trader.
Ce guide détaillé te servira de référence permanente pour comprendre et maîtriser les paramètres de configuration. Garde-le dans tes favoris ! 📌
📌 Note fork : ce guide vaut pour le Freqtrade officiel comme pour mon fork freqtrade-ultimate — la syntaxe des configs est identique. Le fork t'apporte juste deux bonus côté config : des dossiers
live_configs/etbacktest_configs/déjà en place avec des exemples, et un éditeur de config directement dans FreqUI (j'en reparle plus bas). Si tu ne connais pas mes forks : le post de présentation.
🎯 Qu'est-ce qu'un fichier de configuration ?
Les fichiers de configuration (en .json) sont le tableau de bord de tes stratégies Freqtrade. Ils définissent :
💰 Le capital à utiliser et comment le répartir
📊 Les crypto-monnaies à trader
🏦 L'exchange et les identifiants de connexion (voir l'exemple Hyperliquid plus bas)
🎛️ Les paramètres de gestion des risques
🖥️ L'interface de monitoring (FreqUI)
Point crucial : pour lancer n'importe quelle action dans Freqtrade (backtest, bot live, hyperopt), tu as TOUJOURS besoin de deux fichiers : un fichier de stratégie (
.py) — la logique de trading — et un fichier de configuration (.json) — les paramètres.
Ce post compile les paramètres essentiels, mais il en existe beaucoup d'autres. Pour aller plus loin, consulte la documentation officielle Freqtrade sur les configurations.
🏗️ Architecture moderne : la méthode des 3 fichiers
Contrairement à l'approche traditionnelle d'un seul gros fichier, je te recommande une architecture modulaire en 3 fichiers (détaillée aussi dans le guide Hyperliquid). Elle offre une flexibilité maximale :
📁 Structure recommandée
freqtrade/
├── live_configs/
│ ├── _default_spot_usdc.json # Configuration de base
│ ├── _hyperliquid_freqtrade_access.json # Accès API
│ └── ma_strategie.json # Config spécifiqueCette approche permet de :
✅ Réutiliser les configurations communes
✅ Sécuriser tes clés API dans un fichier séparé
✅ Modifier facilement les paramètres par stratégie
✅ Éviter la duplication
💡 Dans freqtrade-ultimate, les dossiers
live_configs/etbacktest_configs/sont déjà créés, avec des fichiers d'exemple à dupliquer. Tu n'as plus à reconstruire l'arborescence à la main.
📋 Fichier 1 : Configuration de base (defaultspot_usdc.json)
Ce fichier contient tous les paramètres communs à tes stratégies. Place-le dans freqtrade/live_configs/ :
{
"stake_currency": "USDC",
"stake_amount": "unlimited",
"tradable_balance_ratio": 0.95,
"available_capital": 100,
"dry_run": false,
"dry_run_wallet": 0.1001,
"cancel_open_orders_on_exit": true,
"trading_mode": "futures",
"margin_mode": "isolated",
"process_only_new_candles": true,
"unfilledtimeout": {
"entry": 10,
"exit": 10,
"exit_timeout_count": 0,
"unit": "minutes"
},
"entry_pricing": {
"price_side": "same",
"price_last_balance": 1.0,
"use_order_book": true,
"order_book_top": 1
},
"exit_pricing": {
"price_side": "same",
"price_last_balance": 1.0,
"use_order_book": true,
"order_book_top": 1
},
"telegram": {
"enabled": false,
"token": "",
"chat_id": ""
},
"api_server": {
"enabled": true,
"listen_ip_address": "0.0.0.0",
"verbosity": "error",
"enable_openapi": false
},
"exchange": {
"pair_whitelist": [
"AAVE/USDC:USDC","ADA/USDC:USDC","ALGO/USDC:USDC",
"APT/USDC:USDC","ARB/USDC:USDC","ATOM/USDC:USDC",
"AVAX/USDC:USDC","BCH/USDC:USDC","BNB/USDC:USDC",
"BTC/USDC:USDC"
],
"pair_blacklist": [
"EUR/.*",
"USDT/.*",
"USDC/USDT"
],
"ccxt_async_config": {
"enableRateLimit": true,
"rateLimit": 700
}
},
"initial_state": "running",
"force_entry_enable": false
}🔍 Paramètres clés expliqués
stake_currency : "USDC" — la monnaie de base pour trader. Doit correspondre à tes fonds sur l'exchange.
Hyperliquid ne supporte que l'USDC
Binance supporte USDC et BTC, mais plus l'USDT en tant que français
stake_amount : "unlimited" — montant alloué par position.
"unlimited"= tout le capital disponible divisé parmaxopentradesUn nombre fixe (ex. 100) = montant fixe par trade
⚠️ Attention aux risques du mode unlimited — j'en ai fait un post entier
tradable_balance_ratio : 0.95 — pourcentage du solde total utilisable (0.95 = 95 %).
trading_mode : "futures" — "spot" = trading classique, "futures" = effet de levier et short possibles.
margin_mode : "isolated" — uniquement pour les futures (risque limité à la position). Laisse vide ("") en spot.
dry_run : false — true = simulation (argent fictif), false = trading réel. Toujours commencer en dry_run !
un_filled_timeout : annule un ordre non rempli après X minutes (entry/exit). Évite les ordres bloqués. (Voir le guide des ordres limite et marché.)
entry_pricing / exit_pricing : gestion des prix. "same" = même côté du carnet d'ordres, useorderbook: true = prix plus précis, orderbooktop: 1 = première ligne du carnet.
ccxt_async_config.rateLimit : 700 — fréquence à laquelle ton bot est autorisé à requêter l'exchange (en live comme en dry-run).
Valeur plus grande = bot plus lent à requêter, mais moins de risque de ban
Valeur plus petite = données plus fraîches, mais plus de requêtes
Une valeur idéale se situe généralement entre 100 et 800. Commence bas (300-500) et augmente si tu vois des erreurs dans les logs
🚦 Spécial Hyperliquid / multi-bots : si tu fais tourner beaucoup de bots sur le même exchange, le réglage de
rateLimitne suffit plus et tu vas taper le rate limit (erreurs 429). C'est LE piège du multi-bots Hyperliquid. Heureusement si tu utilises le fork freqtrade-ultimate, tu n'as pas à t'en soucier ! J'ai écrit un post entier avec la méthode complète (dont le cache partagéftpairlist) si tu veux comprendre plus en détails comment ça marche : Lancer 100 bots Freqtrade sur Hyperliquid sans jamais toucher le rate limit.
telegram : lie ton bot à un bot Telegram. Je ne l'utilise pas, mais la doc officielle détaille tout.
cancel_open_orders_on_exit : retire les ordres limites non remplis quand tu coupes le bot.
api_server : établit la connexion avec FreqUI, l'interface de monitoring dans le navigateur.
🔐 Fichier 2 : Accès API (_hyperliquid_freqtrade_access.json)
Ce fichier contient tes identifiants sensibles. Ne le partage JAMAIS (les deux autres fichiers, eux, peuvent être partagés).
{
"exchange": {
"name": "hyperliquid",
"walletAddress": "0xC111111111111111111111111111111111111111",
"privateKey": "0xVOTRE_CLE_PRIVEE_API_A_NE_JAMAIS_PARTAGER"
},
"api_server": {
"jwt_secret_key": "GENEREZ_UNE_CHAINE_ALEATOIRE",
"ws_token": "GENEREZ_UNE_AUTRE_CHAINE_ALEATOIRE",
"CORS_origins": ["http://VOTRE_IP:PORT_DU_BOT_PRINCIPAL"],
"username": "freqtrade_france",
"password": "CHOISISSEZ_UN_MOT_DE_PASSE_FORT"
}
}🔑 Configuration des accès
Pour Hyperliquid : walletAddress (ton adresse de wallet) et privateKey (la clé privée d'API). Détails dans le guide complet Hyperliquid.
Pour d'autres exchanges : "key" (ta clé API) et "secret" (ton secret API). Voir les exchanges pour Français et l'intro aux connexions API.
api_server (FreqUI) : jwtsecretkey et ws_token (génère des chaînes aléatoires), username/password (tes identifiants FreqUI), CORS_origins (IP de ta machine + port du bot principal).
⚠️ Rappel sécurité : ce fichier doit être gitignoré. Si tu publies tes configs (ou utilises l'outil d'export du fork), les clés sont à protéger absolument — ne committe jamais une clé privée.
🎯 Fichier 3 : Configuration spécifique (ma_strategie.json)
Ce fichier lie tout ensemble et définit les paramètres uniques à ta stratégie. C'est ce .json que tu passes à ton bot au lancement (live ou dry-run) :
{
"add_config_files": [
"_default_spot_usdc.json",
"_hyperliquid_freqtrade_access.json"
],
"max_open_trades": 40,
"available_capital": 500,
"tradable_balance_ratio": 0.99,
"stake_amount": "unlimited",
"trading_mode": "futures",
"margin_mode": "isolated",
"stake_currency": "USDC",
"bot_name": "simple_vwap_v1_hyperliquid",
"strategy": "simple_vwap_v1",
"db_url": "sqlite:///database/simple_vwap_v1_hyperliquid.sqlite",
"api_server": {
"listen_port": 9907
},
"pairlists": [
{
"method": "VolumePairList",
"number_assets": 60,
"sort_key": "quoteVolume",
"min_value": 0,
"refresh_period": 86400,
"lookback_days": 7
}
],
"internals": {
"process_throttle_secs": 60
}
}⚡ Paramètres critiques à personnaliser
add_config_files : liste les fichiers à fusionner. L'ordre compte (le dernier écrase les précédents).
max_open_trades : 40 — nombre maximum de positions simultanées. Plus élevé = positions plus petites = risque dilué.
available_capital : 500 — capital initial en USDC. Doit correspondre à tes fonds réels ; sert de base aux calculs de position.
bot_name : nom unique pour identifier ton bot (apparaît dans FreqUI et les logs).
strategy : le .py doit être dans user_data/strategies/ et la classe Python doit porter ce nom exact.
db_url : base de données des trades. Un fichier par bot pour éviter les conflits.
listen_port : 9907 — port d'accès à FreqUI, unique pour chaque bot (accès via http://votre-ip:9907).
pairlists : sélection des cryptos. VolumePairList = top par volume (live uniquement) ; StaticPairList = liste fixe (pour backtests).
🌊 Sur les stratégies short, freqtrade-ultimate ajoute un filtre de pairlist maison, le TrendRegularityFilter, qui exclut automatiquement les paires en tendance haussière trop linéaire (dangereuses à shorter). Tu l'ajoutes simplement dans
pairlists.
internals.process_throttle_secs : 60 — temps (en secondes) entre deux exécutions de la logique du bot. Plus ta timeframe est haute, plus tu peux mettre une grande valeur.
🧪 Configuration pour Backtesting
Pour les backtests, utilise une configuration simplifiée dans freqtrade/backtest_configs/ :
{
"max_open_trades": 40,
"stake_currency": "USDT",
"stake_amount": "unlimited",
"tradable_balance_ratio": 0.99,
"available_capital": 500,
"dry_run": false,
"trading_mode": "spot",
"exchange": {
"name": "binance",
"pair_whitelist": [
"BTC/USDT",
"ETH/USDT",
"SOL/USDT",
"BNB/USDT",
"XRP/USDT"
]
}
}📊 Différences backtest vs live
Pas de clés API : inutiles pour les données historiques. Tu n'as besoin des clés que pour passer des ordres réels.
StaticPairList obligatoire :
VolumePairListest impossible en backtest.Paramètres simplifiés : pas besoin d'
api_server, detelegram, etc.
⚠️ Rappel : un backtest ne vaut rien, ce qui vaut quelque chose c'est le live ! Un backtest est un point de départ pour dégrossir, jamais une garantie. Pour la méthodo complète, voir le guide des backtests. Et pour récupérer les données Hyperliquid (un cas un peu particulier) : le guide dédié.
🚀 Commandes pratiques
Lancer un backtest
freqtrade backtesting -c backtest_configs/futures_binance.json -s simple_vwap_v1Lancer un bot en live / dry-run
freqtrade trade -c live_configs/simple_vwap_v1.jsonVérifier la configuration (très utile pour voir la config fusionnée)
freqtrade show-config -c live_configs/simple_vwap_v1.json🖱️ Bonus fork : éditer ses configs directement dans FreqUI
Avec mon fork de FreqUI (frequi-ultimate), tu peux éditer la config d'un bot directement depuis l'interface web, sans repasser par VS Code/SFTP. L'éditeur écrit dans le fichier d'entrée du bot, et un garde-fou anti-écrasement évite de réduire ta config à néant en cas de fausse manip.
💡 Pratique pour ajuster un paramètre à chaud, mais souviens-toi : la plupart des changements de config ne sont pris en compte qu'après un redémarrage du bot.
⚠️ Erreurs courantes à éviter
❌ Oublier d'activer l'environnement Python — avant toute commande :
source ./.venv/bin/activate❌ Mauvais nom de stratégie — le nom de la classe dans le .py doit correspondre exactement au champ "strategy" de la config (sans l'extension .py).
❌ Ports en conflit — chaque bot doit avoir un listen_port unique. Deux bots sur le même port ne peuvent pas tourner ensemble. Commence à une valeur fixe (ex. 10000) et incrémente pour chaque nouveau bot.
❌ Capital insuffisant — available_capital > fonds réels = erreurs. Garde une marge de sécurité.
❌ Syntaxe JSON incorrecte — virgule manquante/en trop, guillemet non fermé… Utilise un validateur comme jsonlint.com.
💡 Bonnes pratiques
📁 Organisation des fichiers
freqtrade/
├── live_configs/
│ ├── _default_spot_usdc.json
│ ├── _default_futures_usdc.json
│ ├── _binance_access.json
│ ├── _hyperliquid_access.json
│ ├── strategie1_binance.json
│ └── strategie2_hyperliquid.json
├── backtest_configs/
│ ├── spot_5pairs.json
│ └── futures_20pairs.json🔒 Sécurité : ne partage JAMAIS les fichiers d'accès API, utilise des mots de passe forts pour FreqUI, limite les permissions API au strict minimum.
📈 Évolution progressive : commence avec peu de paires (top 5-20), un capital modeste (100-500 USDC), puis augmente progressivement en surveillant les performances.
💡 Tu peux tester une même stratégie avec différentes configs en dry-run pour mesurer l'impact d'un paramètre avant de passer en live.
🎓 Conclusion
Les fichiers de configuration sont le cœur de ton système Freqtrade. Cette architecture en 3 fichiers t'offre flexibilité, sécurité et réutilisabilité.
Prochaines étapes :
📝 Comprendre le moteur logique de tes bots : Maîtriser les fichiers de stratégies
🤖 Sur Hyperliquid : Connecter Freqtrade à Hyperliquid puis le guide anti-rate-limit
🤖 Passer en pratique : Bots en Live : Live, Dry-run et FreqUI
💡 Garde ce guide dans tes favoris et consulte-le à chaque doute sur un paramètre.
☕ Si ce guide de référence t'a aidé, tu peux me soutenir ici : buymeacoffee.com/freqtrade_france.
💡 Si tu trades sur Hyperliquid, tu peux passer par mon lien d'affiliation (réduction sur les frais).
⚠️ Je ne suis pas conseiller financier. Ce contenu reflète mon expérience personnelle. Les performances passées ne préjugent pas des performances futures. Il existe d'autres méthodes tout aussi valables.
— Mouton 🐑