Start Here: Run QuantForge in 5 Minutes

Welcome! This page shows the fastest path from zero to your first QuantForge run: install the CLI, sync market candles, run a backtest, and understand the difference between dry-run and live mode before connecting anything real.

What is QuantForge?

QuantForge is a CLI-first trading systems framework written in Rust.

It is built for developers who want a deterministic workflow for:

syncing market data into a local SQLite database,
running reproducible backtests,
testing strategies in dry-run mode,
and, when ready, connecting to live execution paths with explicit safeguards.

Think of it as a Rust-native path from:

idea → data → backtest → dry-run → live trading, only when explicitly enabled

Official resources:

GitHub: https://github.com/formaldehid/quantforge
crates.io: https://crates.io/crates/quantforge
docs.rs: https://docs.rs/quantforge/latest/quantforge/

Quickstart: the absolute minimum

1. Install QuantForge

If you want the installed CLI:

cargo install quantforge

For the most reliable first run while the project is moving quickly, you can also run directly from the repository:

git clone https://github.com/formaldehid/quantforge.git
cd quantforge
cargo run -- --help

The examples below use the repository style:

cargo run -- ...

If you installed the binary with cargo install quantforge, you can usually replace:

cargo run -- ...

with:

quantforge ...

2. Minimal data sync

Sync candles into a local SQLite database:

cargo run -- \
  --db data/market.sqlite \
  data sync \
  --symbol BTCUSDT \
  --interval 1m

This creates or updates a local market database at:

data/market.sqlite

For a first run, keep the example simple. Use BTCUSDT and 1m candles first, then change the symbol and interval once the basic flow works.

3. Validate the stored candles

Before running a backtest, validate the stored series:

cargo run -- \
  --db data/market.sqlite \
  data validate \
  --symbol BTCUSDT \
  --interval 1m

This helps catch data gaps or unexpected candle issues before they affect your strategy results.

4. Minimal backtest

Run the built-in SMA crossover backtest:

cargo run -- \
  --db data/market.sqlite \
  backtest \
  --symbol BTCUSDT \
  --interval 1m \
  --fast 20 \
  --slow 50 \
  --cash 10000 \
  --fee-bps 10

This gives you the first complete QuantForge loop:

sync candles → validate data → run backtest

That is the fastest path from zero to a useful local result.

Dry-run vs live mode

QuantForge is designed to make the difference between simulated execution and live execution explicit.

Dry-run mode

Dry-run mode lets you run the strategy loop without sending real orders.

Use it to test:

strategy logic,
order generation,
risk assumptions,
operational behavior,
and whether the bot behaves as expected against live-updating data.

Example dry-run command:

cargo run -- \
  --db data/market.sqlite \
  trade run \
  --symbol BTCUSDT \
  --interval 1m \
  --fast 20 \
  --slow 50 \
  --quote-order-qty 100 \
  --mode dry-run \
  --poll-secs 5

Use dry-run mode first. Use it many times. Treat it as the default development path.

Live mode

Live mode can place orders through a configured exchange or broker integration.

In the current public QuantForge path, live trading requires explicit --mode live and Binance credentials from environment variables.

Example environment setup:

export QF_BINANCE_API_KEY="..."
export QF_BINANCE_API_SECRET="..."
export QF_BINANCE_BASE_URL="https://testnet.binance.vision/"

Example live command:

cargo run -- \
  --db data/market.sqlite \
  trade run \
  --symbol BTCUSDT \
  --interval 1m \
  --fast 20 \
  --slow 50 \
  --quote-order-qty 100 \
  --mode live \
  --bootstrap-enter \
  --poll-secs 5

Start with Binance Spot testnet or paper-style environments first. Never connect real funds until you fully understand the configuration and have tested the system repeatedly in dry-run mode.

Useful operator commands

Inspect balances, open orders, and recent trades:

cargo run -- \
  --db data/market.sqlite \
  monitor status \
  --symbol BTCUSDT

Cancel an order manually:

cargo run -- \
  --db data/market.sqlite \
  monitor cancel-order \
  --symbol BTCUSDT \
  --order-id 123456789 \
  --yes

Close a bot-managed position manually:

cargo run -- \
  --db data/market.sqlite \
  trade close \
  --symbol BTCUSDT \
  --yes

Safety disclaimer

QuantForge is engineering software. It is not financial advice, investment advice, or a promise of profitability.

Trading involves significant risk, including loss of principal. You are responsible for your own decisions, infrastructure, credentials, risk controls, exchange rules, and legal obligations.

Before using live mode:

run dry-run mode extensively,
use testnet or paper-style environments first,
start with minimal size,
never commit API keys to source control,
use conservative risk limits,
and verify whether your configuration sends paper orders or real orders.

Where to go next

Star the repo: https://github.com/formaldehid/quantforge
Read the README: https://github.com/formaldehid/quantforge
Browse the crate: https://crates.io/crates/quantforge
Read the Rust docs: https://docs.rs/quantforge/latest/quantforge/
Open an issue: https://github.com/formaldehid/quantforge/issues
Follow the build log: https://github.com/formaldehid/quantforge/actions

If you try the quickstart, open an issue with your first question, bug, or friction point. The best way to improve QuantForge is to make the first run smoother for the next developer.

⭐ Star the repo, try the quickstart, and help shape the project.

Command Palette