Skip to main content

Configuration

Freqtrade uses a JSON configuration file to define all bot settings. This guide covers the essential configuration options to get your bot running.

Configuration File​

By default, Freqtrade loads configuration from config.json in the current directory. You can specify a different file using the -c/--config option:

freqtrade trade -c my_config.json

Creating Configuration​

Interactive Setup​

The easiest way to create a configuration is using the interactive setup:

freqtrade new-config --config user_data/config.json

This will ask you questions about:

  • Exchange selection
  • Trading pairs
  • Timeframes
  • Strategy selection
  • Risk management
  • API settings

Manual Configuration​

You can also create the configuration file manually. Here's a basic template:

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "stake_amount": 100,
    "tradable_balance_ratio": 0.99,
    "fiat_display_currency": "USD",
    "timeframe": "5m",
    "dry_run": true,
    "dry_run_wallet": 1000,
    "cancel_open_orders_on_exit": false,
    "trading_mode": "spot",
    "minimal_roi": {
        "60": 0.01,
        "30": 0.02,
        "0": 0.04
    },
    "stoploss": -0.10,
    "trailing_stop": false,
    "unfilledtimeout": {
        "entry": 10,
        "exit": 10,
        "exit_timeout_count": 0,
        "unit": "minutes"
    },
    "entry_pricing": {
        "price_side": "same",
        "use_order_book": true,
        "order_book_top": 1,
        "price_last_balance": 0.0,
        "check_depth_of_market": {
            "enabled": false,
            "bids_to_ask_delta": 1
        }
    },
    "exit_pricing": {
        "price_side": "same",
        "use_order_book": true,
        "order_book_top": 1
    },
    "exchange": {
        "name": "binance",
        "key": "your_exchange_key",
        "secret": "your_exchange_secret",
        "ccxt_config": {},
        "ccxt_async_config": {},
        "pair_whitelist": [
            "BTC/USDT",
            "ETH/USDT"
        ],
        "pair_blacklist": []
    },
    "pairlists": [
        {
            "method": "StaticPairList"
        }
    ],
    "telegram": {
        "enabled": false,
        "token": "your_telegram_token",
        "chat_id": "your_telegram_chat_id"
    },
    "api_server": {
        "enabled": false,
        "listen_ip_address": "127.0.0.1",
        "listen_port": 8080,
        "verbosity": "error",
        "enable_openapi": false,
        "jwt_secret_key": "your_jwt_secret",
        "CORS_origins": [],
        "username": "freqtrade",
        "password": "your_password"
    },
    "bot_name": "freqtrade",
    "initial_state": "running",
    "force_entry_enable": false,
    "internals": {
        "process_throttle_secs": 5
    }
}

Essential Configuration Options​

Trading Settings​

Basic Trading Parameters​

{
    "max_open_trades": 3,           // Maximum concurrent trades
    "stake_currency": "USDT",       // Base currency for trading
    "stake_amount": 100,            // Amount per trade
    "tradable_balance_ratio": 0.99, // Percentage of balance to use
    "timeframe": "5m"               // Candle timeframe
}

Risk Management​

{
    "stoploss": -0.10,              // 10% stop loss
    "minimal_roi": {                // Profit targets
        "60": 0.01,                 // 1% after 60 minutes
        "30": 0.02,                 // 2% after 30 minutes
        "0": 0.04                   // 4% immediately
    },
    "trailing_stop": true,          // Enable trailing stop
    "trailing_stop_positive": 0.01, // Start trailing at 1% profit
    "trailing_stop_positive_offset": 0.02 // Offset for trailing
}

Exchange Configuration​

{
    "exchange": {
        "name": "binance",          // Exchange name
        "key": "your_api_key",      // API key
        "secret": "your_api_secret", // API secret
        "sandbox": false,           // Use sandbox/testnet
        "pair_whitelist": [         // Allowed trading pairs
            "BTC/USDT",
            "ETH/USDT",
            "ADA/USDT"
        ],
        "pair_blacklist": [         // Forbidden pairs
            "BNB/USDT"
        ]
    }
}

Dry Run vs Live Trading​

Dry Run (Paper Trading)​

{
    "dry_run": true,                // Enable paper trading
    "dry_run_wallet": 1000          // Starting balance for simulation
}

Live Trading​

{
    "dry_run": false,               // Disable paper trading
    "exchange": {
        "key": "your_real_api_key",
        "secret": "your_real_api_secret"
    }
}

Advanced Configuration​

Order Types​

{
    "order_types": {
        "entry": "limit",           // Entry order type
        "exit": "limit",            // Exit order type
        "emergency_exit": "market", // Emergency exit type
        "force_exit": "market",     // Force exit type
        "force_entry": "market",    // Force entry type
        "stoploss": "market",       // Stop loss type
        "stoploss_on_exchange": false, // Place stop loss on exchange
        "stoploss_on_exchange_interval": 60 // Check interval
    }
}

Time in Force​

{
    "order_time_in_force": {
        "entry": "GTC",             // Good Till Cancelled
        "exit": "GTC"               // Good Till Cancelled
    }
}

Unfilled Timeout​

{
    "unfilledtimeout": {
        "entry": 10,                // Entry timeout (minutes)
        "exit": 10,                 // Exit timeout (minutes)
        "exit_timeout_count": 0,    // Max exit timeouts (0 = unlimited)
        "unit": "minutes"           // Time unit
    }
}

Pair Selection​

Static Pair List​

{
    "pairlists": [
        {
            "method": "StaticPairList"
        }
    ],
    "exchange": {
        "pair_whitelist": [
            "BTC/USDT",
            "ETH/USDT",
            "ADA/USDT"
        ]
    }
}

Volume-Based Pair List​

{
    "pairlists": [
        {
            "method": "VolumePairList",
            "number_assets": 20,
            "sort_key": "quoteVolume",
            "min_value": 0,
            "refresh_period": 1800
        }
    ]
}

Age Filter​

{
    "pairlists": [
        {
            "method": "VolumePairList",
            "number_assets": 50
        },
        {
            "method": "AgeFilter",
            "min_days_listed": 10
        }
    ]
}

Notifications​

Telegram Integration​

{
    "telegram": {
        "enabled": true,
        "token": "your_bot_token",
        "chat_id": "your_chat_id",
        "notification_settings": {
            "status": "silent",
            "warning": "on",
            "startup": "on",
            "entry": "silent",
            "entry_fill": "on",
            "exit": {
                "roi": "silent",
                "emergency_exit": "on",
                "force_exit": "on",
                "exit_signal": "silent",
                "trailing_stop_loss": "on",
                "stop_loss": "on",
                "stoploss_on_exchange": "on",
                "custom_exit": "silent"
            },
            "exit_cancel": "on",
            "exit_fill": "on",
            "protection_trigger": "on",
            "protection_trigger_global": "on"
        }
    }
}

Webhook Notifications​

{
    "webhook": {
        "enabled": true,
        "url": "https://your-webhook-url.com/webhook",
        "entry": {
            "value1": "{pair}",
            "value2": "{stake_amount}",
            "value3": "{open_rate}"
        },
        "exit": {
            "value1": "{pair}",
            "value2": "{profit_amount}",
            "value3": "{profit_ratio}"
        }
    }
}

Web Interface (FreqUI)​

{
    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "verbosity": "error",
        "enable_openapi": true,
        "jwt_secret_key": "your_secret_key",
        "username": "freqtrade",
        "password": "your_password",
        "ws_token": "your_ws_token"
    }
}

Environment Variables​

You can override configuration values using environment variables:

# Set stake amount
export FREQTRADE__STAKE_AMOUNT=200

# Set exchange API key
export FREQTRADE__EXCHANGE__KEY=your_api_key

# Set telegram token
export FREQTRADE__TELEGRAM__TOKEN=your_telegram_token

# Set pair whitelist
export FREQTRADE__EXCHANGE__PAIR_WHITELIST='["BTC/USDT", "ETH/USDT"]'

Multiple Configuration Files​

You can split your configuration across multiple files:

{
    "add_config_files": [
        "config-private.json",
        "config-strategy.json"
    ]
}

Configuration Validation​

JSON Schema​

Add schema validation to your configuration:

{
    "$schema": "https://schema.freqtrade.io/schema.json",
    "max_open_trades": 3
}

Validate Configuration​

Check your configuration syntax:

freqtrade show-config

Security Best Practices​

Protect Sensitive Data​

  1. Never commit API keys to version control
  2. Use environment variables for secrets
  3. Separate configuration files for sensitive data
  4. Restrict file permissions on configuration files
# Set restrictive permissions
chmod 600 config.json

Example Secure Setup​

config.json (public):

{
    "max_open_trades": 3,
    "stake_currency": "USDT",
    "add_config_files": ["config-private.json"]
}

config-private.json (private):

{
    "exchange": {
        "key": "your_api_key",
        "secret": "your_api_secret"
    },
    "telegram": {
        "token": "your_telegram_token",
        "chat_id": "your_chat_id"
    }
}

Common Configuration Patterns​

Conservative Setup​

{
    "max_open_trades": 3,
    "stake_amount": 50,
    "stoploss": -0.05,
    "minimal_roi": {
        "0": 0.02
    },
    "timeframe": "1h"
}

Aggressive Setup​

{
    "max_open_trades": 10,
    "stake_amount": 100,
    "stoploss": -0.15,
    "minimal_roi": {
        "0": 0.10
    },
    "timeframe": "5m"
}

Scalping Setup​

{
    "max_open_trades": 20,
    "stake_amount": 25,
    "stoploss": -0.02,
    "minimal_roi": {
        "0": 0.01
    },
    "timeframe": "1m"
}

Troubleshooting​

Common Issues​

Configuration not loading:

  • Check JSON syntax
  • Verify file permissions
  • Check file path

API connection errors:

  • Verify API keys
  • Check exchange status
  • Confirm IP whitelist

Strategy not found:

  • Check strategy path
  • Verify strategy name
  • Ensure strategy file exists

Debugging Commands​

# Show final configuration
freqtrade show-config

# Test exchange connection
freqtrade test-pairlist

# Validate strategy
freqtrade list-strategies

Next Steps​

After configuring your bot:

  1. Strategy Development - Create your trading strategy
  2. Backtesting - Test your configuration
  3. Bot Usage - Learn to operate the bot
  4. Telegram Usage - Set up notifications

Resources​

Last updated on by huojiabin