Freqtrade: Local AI Trading Assistant for Cryptocurrency

A Complete Technical and Practical Guide

1. Overview

Freqtrade is an open-source, Python-based cryptocurrency trading bot that can run entirely on local hardware. It supports fully automated trading strategies, integrates AI/ML models for signal generation, and can connect to multiple exchanges using API keys.

Key characteristics:

• Local Execution – All code runs on your machine, no dependency on external servers.

• Customizable Strategies – Strategies are just Python scripts you can fully modify.

• AI/ML Support – Integration with TensorFlow, PyTorch, and Scikit-learn for predictive models.

• Backtesting & Hyperparameter Optimization – Built-in simulation tools.

• Exchange Support – Works with Binance, KuCoin, Bybit, Kraken, OKX, and more via CCXT.

2. Core Technical Architecture

Freqtrade consists of several core modules:

1. Data Handler

   • Collects OHLCV candles and order book data via the CCXT library.

   • Supports multiple timeframes (1m, 5m, 1h, etc.).

   • Can store data locally in SQLite or JSON.

2. Strategy Engine

   • Reads market data, applies technical indicators or AI predictions.

   • Generates buy/sell signals based on your Python strategy code.

3. Order Manager

   • Places, modifies, and cancels orders through the exchange API.

   • Handles retries, rate limits, and order confirmations.

4. Risk & Money Management Module

   • Enforces stop-loss, take-profit, trailing stops, max open trades, and capital allocation rules.

5. Backtesting & Optimization Engine

   • Runs strategies on historical data.

   • Supports hyperopt for automated parameter tuning.

6. Machine Learning Integration

   • Load pre-trained ML models from .pkl (Scikit-learn) or .pt/.onnx (PyTorch).

   • Can train models directly on your dataset using the freqai module.

3. System Requirements

Minimum:

• CPU: 4 cores

• RAM: 4 GB

• Storage: 20 GB SSD

• OS: Linux (Ubuntu/Debian recommended), macOS, Windows (WSL2 recommended)

Recommended for AI models:

• CPU: 8 cores or more

• RAM: 8–16 GB

• GPU: NVIDIA RTX series with CUDA support

• Storage: 100 GB+ SSD

Dependencies:

• Python 3.9–3.11

• Pipenv or Poetry (for dependency management)

• Git

• Docker (optional but useful)

4. Installation Guide (Linux Example)

# 1. Install dependencies
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-pip git

# 2. Clone the repository
git clone https://github.com/freqtrade/freqtrade.git
cd freqtrade

# 3. Checkout the stable branch
git checkout stable

# 4. Create virtual environment
python3 -m venv .env
source .env/bin/activate

# 5. Install required packages
pip install -U pip
pip install -e .

# 6. Create a new configuration
freqtrade new-config --config config.json

# 7. Verify installation
freqtrade --version

5. Initial Configuration

After creating config.json, you must edit it to add your exchange API keys and bot settings:

{
  "max_open_trades": 3,
  "stake_currency": "USDT",
  "stake_amount": "100",
  "dry_run": true,
  "exchange": {
    "name": "binance",
    "key": "YOUR_API_KEY",
    "secret": "YOUR_API_SECRET",
    "ccxt_config": {},
    "ccxt_async_config": {},
    "pair_whitelist": ["BTC/USDT", "ETH/USDT"],
    "pair_blacklist": []
  },
  "telegram": {
    "enabled": true,
    "token": "YOUR_TELEGRAM_BOT_TOKEN",
    "chat_id": "YOUR_TELEGRAM_CHAT_ID"
  }
}

• dry_run: true means paper trading mode (no real orders).

• stake_amount is the amount per trade.

6. Creating and Using a Trading Strategy

In Freqtrade, strategies are Python classes stored in the user_data/strategies/ folder.
Here’s an example of a simple moving average crossover strategy:

user_data/strategies/SmaCross.py

from freqtrade.strategy import IStrategy
import talib.abstract as ta

class SmaCross(IStrategy):
    # Strategy parameters
    timeframe = '5m'
    minimal_roi = {"0": 0.02}
    stoploss = -0.01
    trailing_stop = True

    def populate_indicators(self, dataframe, metadata):
        # Calculate SMA
        dataframe['sma_short'] = ta.SMA(dataframe, timeperiod=10)
        dataframe['sma_long'] = ta.SMA(dataframe, timeperiod=50)
        return dataframe

    def populate_buy_trend(self, dataframe, metadata):
        dataframe.loc[
            (dataframe['sma_short'] > dataframe['sma_long']),
            'buy'
        ] = 1
        return dataframe

    def populate_sell_trend(self, dataframe, metadata):
        dataframe.loc[
            (dataframe['sma_short'] < dataframe['sma_long']),
            'sell'
        ] = 1
        return dataframe

Steps to use this strategy:

# Place the strategy file in the correct folder
mkdir -p user_data/strategies
cp SmaCross.py user_data/strategies/

# Test the strategy with backtesting
freqtrade backtesting --config config.json --strategy SmaCross

# Optimize parameters
freqtrade hyperopt --config config.json --strategy SmaCross --hyperopt-loss SharpeHyperOptLoss

7. AI/ML Model Integration (FreqAI)

Freqtrade has a FreqAI module for integrating machine learning models:

• Supports classification and regression models for predicting price movement.

• Works with Scikit-learn, TensorFlow, and PyTorch models.

• Can retrain periodically using fresh market data.

Example: using an AI model to predict 15-minute BTC price movement

1. Train your model using historical OHLCV data.

2. Save it as a .pkl (Scikit-learn) or .pt/.onnx (PyTorch/ONNX).

3. Load it inside your strategy:

import joblib
from freqtrade.strategy import IStrategy

class AIPredictor(IStrategy):
    timeframe = '15m'

    def __init__(self, config: dict) -> None:
        super().__init__(config)
        self.model = joblib.load('models/btc_predictor.pkl')

    def populate_indicators(self, dataframe, metadata):
        dataframe['pred'] = self.model.predict(dataframe[['open', 'high', 'low', 'close', 'volume']])
        return dataframe

    def populate_buy_trend(self, dataframe, metadata):
        dataframe.loc[dataframe['pred'] == 1, 'buy'] = 1
        return dataframe

    def populate_sell_trend(self, dataframe, metadata):
        dataframe.loc[dataframe['pred'] == -1, 'sell'] = 1
        return dataframe

8. Running the Bot

Paper Trading Mode:

freqtrade trade --config config.json --strategy SmaCross

Live Trading (Real Money):

freqtrade trade --config config.json --strategy SmaCross --dry-run False

The bot will log trades in user_data/trades and optionally send updates via Telegram.

9. Backtesting Example

freqtrade backtesting --config config.json --strategy SmaCross --timerange 20230101-20230601

Output Example:

==================================================  
BACKTESTING REPORT  
==================================================  
Total trades:  125  
Wins:          79 (63.2%)  
Losses:        46 (36.8%)  
Total profit:  12.4%  
Avg trade:     0.09%  
Max drawdown:  3.2%  
==================================================

10. Security Best Practices for Local AI Bot

• Store API keys in .env or encrypted key vault.

• Run bot on a dedicated machine or VPS without browsing.

• Always test new strategies in dry_run mode first.

• Keep your freqtrade repo updated:

git pull
pip install -e .

Backup strategies, config, and model files regularly.

11. Advanced Features of Freqtrade for Professionals

11.1 Multiple Timeframe Analysis (MTA)

Freqtrade allows you to combine signals from different timeframes to improve accuracy.
Example: trade on 5m timeframe, confirm signals with 1h trend.

def populate_indicators(self, dataframe, metadata):
    # Current timeframe indicators
    dataframe['ema_fast'] = ta.EMA(dataframe, timeperiod=12)
    dataframe['ema_slow'] = ta.EMA(dataframe, timeperiod=26)

    # Load higher timeframe data
    informative = self.dp.get_pair_dataframe(pair=metadata['pair'], timeframe='1h')
    informative['ema_1h'] = ta.EMA(informative, timeperiod=50)
    dataframe = merge_informative_pair(dataframe, informative, self.timeframe, '1h', ffill=True)
    return dataframe

11.2 Pairlist Management

Dynamic pairlists let you trade only the most volatile or trending pairs:

• VolumePairList – top pairs by 24h volume.

• AgeFilter – exclude new coins without enough history.

• PerformanceFilter – select best-performing pairs over X days.

Example in config.json:

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

11.3 Custom Order Types

Freqtrade supports:

• Market orders

• Limit orders

• Stop-loss limit

• Trailing stop

Example in config:

"order_types": {
    "buy": "limit",
    "sell": "limit",
    "stoploss": "market",
    "stoploss_on_exchange": true
}

11.4 Web Interface Dashboard

Freqtrade has a local web UI for monitoring trades:

freqtrade webserver --config config.json

• Accessible at http://localhost:8080

• View charts, open positions, PnL, strategy logs.

• Can control the bot (start/stop) from the dashboard.

12. AI-Specific Features with FreqAI

12.1 Automatic Model Training

FreqAI can automatically retrain models every X days using fresh market data.

Example config addition:

"freqai": {
    "enabled": true,
    "train_period_days": 14,
    "model_type": "classification",
    "target": "future_price_direction"
}

12.2 Feature Importance Analysis

• Helps identify which indicators matter most for predictions.

• Useful for reducing overfitting and improving inference speed.

13. Deployment Scenarios

1. Local PC (Development & Testing)

   • Ideal for strategy creation, backtesting, AI training.

   • Run in dry_run mode to avoid real losses.

2. Local Server / Home NAS

   • Always-on operation without renting cloud services.

   • Use tools like tmux or screen to keep the bot running.

3. Raspberry Pi or Jetson Nano

   • Low-power solution for 24/7 trading.

   • Suitable for lightweight strategies without heavy AI models.

4. High-Performance GPU Workstation

   • For professional AI-based trading with large datasets.

   • Can train complex LSTM/Transformer models locally.

14. Example: Full AI-Powered BTC Strategy

1. Data Gathering

freqtrade download-data --exchange binance --timeframe 15m --days 365

• Model Training (External)
  Train with PyTorch or Scikit-learn using downloaded data.

• Integration
  Load model inside a strategy as shown earlier (AIPredictor class).

• Live Run

freqtrade trade --config config.json --strategy AIPredictor --dry-run False

5. Monitoring
   Use Telegram or Web UI to watch trades in real time.

15. Conclusion

Freqtrade is one of the most powerful and flexible local AI-assisted cryptocurrency trading platforms available today.
It provides:

• Full control over strategies.

• AI/ML integration for predictive models.

• Complete backtesting, optimization, and live trading capabilities.

• 100% local execution, keeping your trading logic private.

For professional traders and developers, it is a foundation that can be extended into a highly sophisticated, AI-powered trading infrastructure without relying on external providers.