Freqtrade Backtester

Run Freqtrade backtests for cryptocurrency trading strategies, interpret results, and iterate. Use when downloading historical data, running a backtest, read...

Security Scan

The skill is an instruction-only Freqtrade backtester that coherently requires docker/docker-compose and provides backtesting instructions; it does not request unrelated privileges, though it advises using exchange API keys via environment variables (which the registry metadata does not list).

Purpose & Capability

Name/description match the instructions: the SKILL.md only tells the agent to run docker-compose commands for downloading data and backtesting, which reasonably requires docker and docker-compose as declared. There are no unrelated binaries or credentials requested by the registry metadata.

Instruction Scope

Instructions are narrowly scoped to backtesting tasks (download-data, backtesting, exporting JSON) and provide guidance on iterating and reading results. They reference only expected files/paths (config.json, user_data/backtest_results/*) and do not instruct reading unrelated system files or sending data to external endpoints.

Install Mechanism

No install spec and no code files—this is instruction-only, so nothing is written to disk by the skill itself. Risk here depends on the user's docker-compose setup (the skill assumes a freqtrade service is present).

Credentials

Registry metadata lists zero required env vars, but the SKILL.md explicitly instructs users to provide FREQTRADE__EXCHANGE__KEY and FREQTRADE__EXCHANGE__SECRET via environment variables for exchange access. This is not malicious, but it's an inconsistency: the skill will rely on sensitive credentials if the user follows the instructions, so users should be aware and only supply exchange API keys they trust.

Persistence & Privilege

always:false and no special privileges requested. The skill is user-invocable and does not request persistent or cross-skill configuration changes.

Assessment

This instruction-only skill appears to do what it says: run Freqtrade inside docker-compose and help you interpret results. Before installing/using it: (1) ensure you have a trusted freqtrade docker-compose project (the skill assumes the service exists and will pull/run images), (2) do not expose exchange API keys in shared or public environments—use a secure shell/session or a secrets manager, and only provide keys with the minimum permissions needed (read-only or small-trade/test keys if available), (3) the registry metadata did not declare env vars but the docs instruct setting FREQTRADE__EXCHANGE__KEY and SECRET — treat this as expected behavior but be intentional about what credentials you supply, and (4) review your docker-compose file and pulled images before running to confirm they come from the official/expected sources.

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:

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

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:

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

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

{
  "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