Skip to content

Your first FLOX backtest

This tutorial gets you from a clean Python environment to a backtest running on real BTC 1m data. Three commands.

Prerequisites

  • Python 3.10+
  • pip on PATH

1. Install

pip install flox-py

The wheel includes the compiled C++ engine and a flox console script.

2. Scaffold a project

flox new my-strategy
cd my-strategy

flox new writes main.py, main.ipynb, requirements.txt, a README, and a data/btcusdt_sample.csv with 500 real BTC/USDT 1-minute bars (timestamp,open,high,low,close,volume). The default template is research: a single-file SMA(10/30) crossover.

3. Run

pip install -r requirements.txt
python main.py

Output:

backtest on btcusdt_sample.csv
  return : -1.2103%
  trades : 187  win=66.3%
  sharpe : -4.5746
  max DD : 1.5030%
  net PnL: -121.0296
  report : /path/to/my-strategy/report.html

The last line is an HTML report the template always writes next to main.py, with the equity curve and the trades table. Open it in a browser.

That is the actual result of an SMA(10/30) crossover on 500 minutes of BTC. 66% of trades closed in the green, but small wins do not pay for fees and the few losers — net result is a 1.2% drawdown. Useful as a sanity check and a baseline; also useful as a reminder that "SMA crossover" is not a strategy.

This is the unrealistic baseline

The research template wires a bare BacktestRunner with a flat fee rate and no funding, liquidation, rate limits, or queue position. Numbers come back, but they ignore most of what makes a real perp account lose money. For a backtest you can trust enough to risk capital against, switch to the venue-realistic stack: see Realistic backtest in one call.

The strategy class

main.py is one file. The class you edit:

class my_strategy_strategy(flox.Strategy):
    def on_trade(self, ctx, trade):
        fv = self.fast.update(trade.price)
        sv = self.slow.update(trade.price)
        if fv is None or sv is None or not self.slow.ready:
            return
        if fv > sv and ctx.is_flat():
            self.market_buy(0.01)
        elif fv < sv and ctx.is_long():
            self.close_position()

Use your own data

Set MY_STRATEGY_DATA (the env-var prefix is the upper-cased project slug + _DATA) to a CSV with the same columns:

MY_STRATEGY_DATA=/path/to/your/btcusdt_1h.csv python main.py

Next steps