freqtrade - Moses Yebei

The Problem

Manually trading crypto across multiple exchanges is slow and error-prone. Freqtrade solves this by providing a Python-based trading bot that automates strategy execution, backtesting, and portfolio management, with support for spot and futures markets on major exchanges like Binance, Bybit, and Kraken.

What This Does

Freqtrade is a full trading lifecycle tool. It handles data download (freqtrade/commands/data_commands.py), strategy backtesting (freqtrade/optimize/backtesting.py), hyperparameter optimization (freqtrade/optimize/hyperopt_tools.py), and live trading via freqtrade/worker.py. It also includes FreqAI (freqtrade/freqai/), a machine-learning subsystem for adaptive prediction models.

The bot persists all state to SQLite via freqtrade/persistence/trade_model.py and exposes control through Telegram, a REST API (freqtrade/rpc/), and a web UI. Configuration flows through freqtrade/configuration/, with examples in config_examples/.

How It Is Wired

Execution starts at main in freqtrade/main.py, which routes to run in freqtrade/worker.py. That entry point reaches 381 functions. run calls _worker, then startup, then set_startup_time, which queries the database via Trade.session.query(Trade).order_by(Trade.open_date.asc()) — three hops from process start to a database read.

The architecture centers on a few high-blast-radius modules. freqtrade/exceptions.py is imported by 146 modules; changing OperationalException (called from 127 places) ripples everywhere. freqtrade/enums/__init__.py (128 importers) and freqtrade/constants.py (127 importers) are similarly central. The exchange layer (freqtrade/exchange/__init__.py) participates in an import cycle with freqtrade/util/__init__.py and freqtrade/configuration/__init__.py, which makes isolated changes to those files risky.

Key file responsibilities:

freqtrade/exchange/exchange.py — 166 functions, the exchange abstraction; get_patched_exchange is called from 280 places.
freqtrade/persistence/trade_model.py — trade lifecycle, DB writes, 112 functions.
freqtrade/data/dataprovider.py — feeds strategy code with market data.
freqtrade/strategy/interface.py — strategy base class and callback contract.

The code touches the outside world in 126 file operations, 21 network calls, 50 database interactions, and 6 cryptographic operations. Shortest path from main to filesystem is main -> main_exec -> load_config -> file.open.

How To Use It

git clone https://github.com/moses-y/freqtrade
cd freqtrade
pip install -r requirements.txt
freqtrade create-userdir --userdir user_data
freqtrade new-config --config config.json
freqtrade backtesting --strategy SampleStrategy --config config.json
freqtrade trade --strategy SampleStrategy --config config.json

Configuration lives in config.json (see config_examples/config_full.example.json). Docker users can use docker-compose.yml. The bot runs in dry-run mode by default — no API keys required until you set "dry_run": false and add exchange credentials.

Real-World Use

A common pattern: download historical data, backtest a strategy, then deploy it live. For example, a user running a mean-reversion strategy on Binance futures would:

Download OHLCV data with freqtrade download-data.
Validate the strategy with freqtrade backtesting.
Run freqtrade trade with "trading_mode": "futures" and "margin_mode": "isolated" in the config.

Code Health & Issues

Static analysis found 342 issues: 190 high, 147 medium, 5 low. Key findings:

High — Oversized files: tests/conftest.py at 3,177 lines; freqtrade/freqai/data_kitchen.py and freqtrade/optimize/backtesting.py are similarly large. Hard to hold in one head; changes ripple.
High — 25 import-cycle members, including freqtrade/util/__init__.py and freqtrade/exchange/__init__.py. Circular imports make refactoring these modules expensive.
High — 12 hub modules with 100+ dependents each (freqtrade/exceptions.py, freqtrade/enums/__init__.py). Churn here is high-blast-radius.
Medium — Broad exception handling in freqtrade/__init__.py and freqtrade/exchange/exchange.py; a file opened without a context manager in freqtrade/optimize/hyperopt_tools.py.
High — No lockfile for ft_client/pyproject.toml; non-reproducible builds.
Medium — Container base image not pinned by digest; no dependency vulnerability scan in CI; two large binaries (17MB wheel, 10MB feather) committed; GitHub token persists after checkout.

The Bottom Line

This is a mature, well-documented trading bot with a large feature surface and solid test coverage (213 test files). The main risks are architectural — hub modules and import cycles make core changes slow — and supply-chain hygiene is weaker than it should be for a tool that moves money. Use it for strategy research and dry-run validation; treat live trading as a serious deployment requiring careful review of the exchange and persistence layers.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

772 files

Python478
Markdown98
JSON26
YAML19
Shell3
HTML2

DjangoDockerPyTorchpandas

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["freqtrade 324 modules"] g1["tests 136 modules"] g2["ft_client 5 modules"] g3["build_helpers 5 modules"] g4["scripts 2 modules"] g1 -->|466| g0 g3 -->|3| g0 g1 -->|2| g2

Module dependencies

The 10 most depended-upon modules of 473, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_freqtrade_exceptions["exceptions"] n1_freqtrade_enums___init__["__init__"] n2_freqtrade_constants["constants"] n3_freqtrade_util___init__["__init__"] n4_tests_conftest["conftest"] n5_freqtrade_exchange___init__["__init__"] n6_trade_configuration___init__["__init__"] n7_eqtrade_persistence___init__["__init__"] n8_rade_exchange_exchange_types["exchange_types"] n9_freqtrade_misc["misc"] n2_freqtrade_constants --> n1_freqtrade_enums___init__ n8_rade_exchange_exchange_types --> n1_freqtrade_enums___init__ n9_freqtrade_misc --> n1_freqtrade_enums___init__ n4_tests_conftest --> n1_freqtrade_enums___init__ n4_tests_conftest --> n5_freqtrade_exchange___init__ n4_tests_conftest --> n7_eqtrade_persistence___init__ n4_tests_conftest --> n3_freqtrade_util___init__ classDef cyc stroke:#ef4444,stroke-width:2px; class n3_freqtrade_util___init__,n5_freqtrade_exchange___init__,n6_trade_configuration___init__,n7_eqtrade_persistence___init__ cyc;

Dependencies

2 of 41 declared dependencies are a major version behind. Resolved 41 of 41 against the registry.

Package	Declared	Latest	Behind
`python-telegram-bot`	>=20.1	22.8	2 major
`pandas`	>=2.2.0,<4.0	3.0.5	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds ft_client/pyproject.toml
LowSecret-shaped paths present; the code-health audit confirms or clears them freqtrade/configuration/config_secrets.py

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium5

low1

Commit a lockfile beside the manifesthigh

ft_client/pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Pin the container base image by digestmedium

.github/.devcontainer/Dockerfile

freqtradeorg/freqtrade:develop_freqairl

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

build_helpers/pyarrow-23.0.1-cp311-cp311-linux_armv7l.whl

2 blobs over 5MB: pyarrow-23.0.1-cp311-cp311-linux_armv7l.whl 17.0MB, populate_dataframe_with_trades_TRADES.feather 10.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy-docs.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Pin the resolution so a vulnerable version cannot installmedium10 occurrences

no lockfile, and the declared ranges reach pydantic@2.2.0 CVE-2024-3772 (critical) +1 more; requests@2.26.0 CVE-2024-47081 (high) +7 more

The range includes versions with published advisories and nothing in the repository records which one was resolved, so two installs a month apart can differ in whether they are vulnerable and neither is reproducible from what is committed.

Fix: Commit the lockfile, which fixes the resolution and makes this answerable.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.