Freqtrade Backtester#

Run backtests on your trading strategies, interpret results, and iterate safely before going live.

What Backtesting Does#

Backtesting runs your strategy against historical market data to see how it would have performed. It shows you win rates, losses, drawdowns, and exit reasons — everything you need to decide if a strategy is worth trading with real money.

Download Data#

Historical data is cached, so download once and reuse it for many backtests.

⚠️ Download one pair at a time — passing multiple pairs to --pairs can cause errors. Run the command separately for each pair:

bash

docker-compose run --rm freqtrade download-data \
  --exchange kraken \
  --pairs BTC/USDT \
  --timeframe 5m \
  --timerange 20240101-

Replace the pair, timeframe, and timerange as needed. The --timerange format is YYYYMMDD-YYYYMMDD; omit the end date to download through today.

Run a Backtest#

bash

docker-compose run --rm freqtrade backtesting \
  --strategy YourStrategy \
  --timerange 20240101-20260101 \
  --export trades \
  --export-filename user_data/backtest_results/my_backtest.json

Replace YourStrategy with your actual strategy class name. The --export trades flag creates a JSON file with detailed trade logs.

Key Metrics#

• Win rate — Percentage of winning trades. >55% is decent; >60% is strong.
• Max drawdown — Largest peak-to-trough decline. Keep it <20%; above 25% indicates excessive risk.
• Sharpe ratio — Risk-adjusted return. >1.0 is acceptable; >2.0 is excellent.
• Avg profit per trade — Average win/loss size. Wins should be larger than losses.
• Exit reasons — Breakdown of why trades closed (ROI, stop-loss, trailing stop, etc.).

The Key Insight#

High win rate ≠ profitability. A 70% win rate with 5% average loss per trade loses money. A 40% win rate with 2% average wins and 1% average loss is profitable. Control your losses; the wins take care of themselves.

Example: A strategy with tight stops (-3%) outperforms one with loose stops (-7% or -8%), even if the loose version has more winners.

Iteration Pattern#

1. Run a backtest on a fixed time period (e.g., 6 months of data).
2. Change one parameter (e.g., RSI threshold, stop-loss percentage).
3. Backtest the same period again.
4. Compare results — did it improve?
5. If yes, keep it; if no, revert.
6. Repeat until satisfied.

Always test across multiple market conditions (bull runs, bear markets, sideways consolidation) before going live. A strategy that works in one environment often fails in another.

Environment Variables#

Freqtrade reads secrets from environment variables at runtime. Use the double-underscore format:

bash

export FREQTRADE__EXCHANGE__KEY=your-api-key
export FREQTRADE__EXCHANGE__SECRET=your-api-secret

In your config.json, set these fields to empty strings:

json

{
  "exchange": {
    "key": "",
    "secret": ""
  }
}

Freqtrade will populate them from the environment at startup.

References#

• Reading Results — references/reading-results.md
• Iteration Guide — references/iteration-guide.md