FreqAI explained: machine-learning trading bots in freqtrade

FreqAI is the machine-learning module built into freqtrade. Instead of fixed rules such as "buy when RSI is below 30", a FreqAI strategy trains a model on indicators you choose, asks it to predict something about the future (for example, the price change over the next few hours), and trades on those predictions. The model retrains itself as new data arrives.

That makes FreqAI one of the most capable free AI crypto trading bots available. It also makes it easier to fool yourself, so this guide covers both how it works and where it goes wrong.

What FreqAI does

According to the official documentation, FreqAI handles the parts of machine learning that are tedious to build yourself:

• Self-adaptive retraining. Models retrain on a schedule during live or dry-run trading, in a background thread.
• Feature engineering. You define a few base indicators and FreqAI can expand them across timeframes, shifted candles and correlated pairs into thousands of features.
• Realistic backtesting. Backtests retrain the model on a sliding window, the way it would happen live.
• Data cleaning and normalisation, outlier removal and optional dimensionality reduction (PCA).
• Model choice. Ready-made LightGBM and XGBoost regressors and classifiers, PyTorch models, and reinforcement learning.

The project states that FreqAI is not-for-profit and open source, has no token and sells no signals. If someone sells you "FreqAI signals", they are not from the freqtrade project.

Key terms in plain English

How a FreqAI strategy is structured

A FreqAI strategy is a normal freqtrade strategy with a few extra methods:

1. feature_engineering_* methods create the features, such as RSI or MFI over several periods.
2. set_freqai_targets defines the label, for example the mean close price label_period_candles into the future.
3. populate_indicators calls self.freqai.start(...), which trains or loads the model and returns predictions.
4. populate_entry_trend / populate_exit_trend trade on those predictions, for example "enter long if the predicted return is above 1% and the prediction is not an outlier".

Labels deliberately look into the future during training. That is correct for training, but it is exactly why features must never do the same.

Installing FreqAI

With Docker (easiest): change the image in docker-compose.yml:

image: freqtradeorg/freqtrade:stable_freqai

For PyTorch models use stable_freqaitorch, and for reinforcement learning stable_freqairl.

Native install:

pip install -r requirements-freqai.txt

Try the example

Freqtrade ships with an example strategy, model and config. The official quick start runs it in dry-run:

freqtrade trade --config config_examples/config_freqai.example.json \
  --strategy FreqaiExampleStrategy --freqaimodel LightGBMRegressor \
  --strategy-path freqtrade/templates

The documentation is clear that this example is for demonstrating features and benchmarking, not for production trading.

Backtesting FreqAI

FreqAI backtests retrain models for each window inside your timerange, so they take much longer than normal backtests:

freqtrade backtesting --strategy FreqaiExampleStrategy \
  --strategy-path freqtrade/templates \
  --config config_examples/config_freqai.example.json \
  --freqaimodel LightGBMRegressor --timerange 20240101-20240401

Download extra data before the start of the timerange. The model needs train_period_days of history to train before it can predict the first candle. Unlike dry-run, backtesting does not download this data automatically.

Key config values to understand:

"freqai": {
    "enabled": true,
    "identifier": "my-first-model",
    "train_period_days": 30,
    "backtest_period_days": 7,
    "feature_parameters": {
        "include_timeframes": ["5m", "15m", "4h"],
        "label_period_candles": 24
    }
}

backtest_period_days controls how often the model retrains during the backtest. Change identifier whenever you change features or targets, or FreqAI may reuse old models.

Hardware: what FreqAI needs

FreqAI is far heavier than a normal strategy. Every pair gets its own model, and features multiply quickly: indicator periods × timeframes × shifted candles × correlated pairs.

• Small experiments: 4 vCPU and 8 GB RAM.
• Many pairs or many features: 8+ vCPU and 16 GB RAM or more.
• PyTorch and reinforcement learning: more RAM again, and optionally a GPU.

Run FreqAI backtests on a strong home computer when you can, and size your server for live trading separately. Our VPS guide covers server choices.

Common FreqAI mistakes

Look-ahead bias in features. Only labels may use future data. A feature that uses shift(-1) or a centred rolling window will make backtests look impossibly good. Run freqtrade lookahead-analysis on your strategy.

Too many features, too little data. Thousands of features trained on 30 days of 5m candles will fit noise. Start small and add features only when they improve out-of-sample results.

Trusting one backtest. Test several periods, including a falling market. Compare with a simple non-AI strategy on the same data, like those on our leaderboard.

Ignoring outliers. Use FreqAI's dissimilarity index or outlier detection so the bot does not trade on inputs unlike anything the model has seen.

Skipping dry-run. Live retraining behaves differently from backtests. Run in dry-run for weeks first.

Is FreqAI better than a normal strategy?

Not automatically. Machine learning can find relationships that fixed rules miss, but it can also memorise noise very convincingly. A simple strategy that you understand, tested properly, is often a better starting point. Treat FreqAI as a research tool: use it when a regular strategy is already working and you want to test whether a model adds something.

Frequently asked questions

Is FreqAI free? Yes. FreqAI is part of freqtrade, which is open-source software under the GPL-3.0 licence. You pay only for your server and exchange fees.

Which FreqAI model is best for beginners? LightGBMRegressor is the usual starting point. It is fast, works on normal hardware and is used in the official examples.

Can FreqAI run on a Raspberry Pi? Small tests can run on a Raspberry Pi, but it is slow, and CatBoost is not installed on ARM devices. A regular computer or VPS is far more practical.

Does FreqAI guarantee profits? No. It is a tool for building and testing models. Results depend entirely on your features, targets and testing, and past results do not predict future returns.

Do I need to know machine learning? You need the basics: features, labels, training and overfitting. The FreqAI documentation explains these, and Python experience helps a lot.

Related guides

• Freqtrade hyperopt guide: optimise a strategy without over-fitting itHow freqtrade hyperopt works, which spaces and loss functions to use, how to apply the results, and how to check that the optimised strategy still works on new data.
  3 min read
• Freqtrade backtesting tutorial: run, read and trust your resultsHow to download data, run freqtrade backtesting, read every important metric and avoid the mistakes that make backtests look better than reality.
  4 min read
• Best VPS for freqtrade: what you need and how to chooseHow much server you need for freqtrade, where to host it relative to your exchange, which providers people use, and how to secure the server before you trade.
  4 min read