# 428 Backtester — Integral (Freqtrade)

Local Freqtrade scaffold for backtesting on **Binance Futures BTC/USDT:USDT**, **15m** (+ **6h** informative data), built around the Integral workflow.

No Jupyter. Reports come from Freqtrade CLI + HTML plots (`plot-profit`, trade chart).

Ship a **SampleStrategy** by default. Drop your own strategy under `user_data/strategies/` and point scripts at it with `STRATEGY=YourClassName`.

## Requirements

- **Preferred:** Docker + Docker Compose (`freqtradeorg/freqtrade:stable_plot`)
- **Fallback:** Python 3.12 venv with `freqtrade` + `plotly` (scripts use this automatically if Docker is missing)
- ~2+ GB disk for OHLCV history

### Local venv setup (no Docker)

```bash
/opt/homebrew/opt/python@3.12/bin/python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip 'freqtrade[hyperopt]' plotly
```

## Quick start

```bash
# 1) Download futures candles (15m + 6h). Default timerange from 2024-07-01.
./scripts/download_data.sh

# 2) Run baseline backtest (SampleStrategy; full history from 2024-07-01)
./scripts/backtest.sh

# 3) Hyperopt buy/sell params on in-sample range (default 20240701-20260101)
./scripts/hyperopt.sh
# EPOCHS=200 LOSS=SharpeHyperOptLossDaily ./scripts/hyperopt.sh

# 4) Apply best epoch params, then OOS backtest (default 20260101-)
./scripts/apply_hyperopt_params.sh
TIMERANGE=20260101- ./scripts/backtest.sh

# 5) Equity + trade charts (pick a shorter range for readable plots)
TIMERANGE=20250101-20250201 ./scripts/plot.sh
```

Scripts auto-detect Docker; if absent they use `.venv/bin/freqtrade`.

### Your strategy

```bash
# Place YourStrategy.py in user_data/strategies/
STRATEGY=YourStrategy ./scripts/backtest.sh
STRATEGY=YourStrategy ./scripts/hyperopt.sh
```

Or set `"strategy": "YourStrategy"` in `user_data/config.json` / `docker-compose.yml`.

### Custom timerange

```bash
TIMERANGE=20240101-20250601 ./scripts/download_data.sh
TIMERANGE=20240101-20250601 ./scripts/backtest.sh
```

### Direct docker compose

```bash
docker compose run --rm freqtrade download-data \
  --config /freqtrade/user_data/config.json \
  --trading-mode futures -t 15m 6h -p BTC/USDT:USDT --timerange 20240701-

docker compose run --rm freqtrade backtesting \
  --config /freqtrade/user_data/config.json \
  --strategy SampleStrategy --timeframe 15m --timerange 20240701-
```

## Project layout

| Path | Role |
|------|------|
| [`user_data/strategies/SampleStrategy.py`](user_data/strategies/SampleStrategy.py) | Placeholder strategy (replace with yours) |
| [`user_data/config.json`](user_data/config.json) | Binance futures dry-run / backtest config |
| [`scripts/`](scripts/) | download / backtest / hyperopt / plot helpers |
| [`docker-compose.yml`](docker-compose.yml) | `freqtradeorg/freqtrade:stable_plot` |

## Optimization

Primary tool: **Freqtrade Hyperopt** (Optuna TPE) over strategy `IntParameter` / `DecimalParameter` spaces.

Default split used by scripts:

- **IS / hyperopt:** `TIMERANGE=20240701-20260101`
- **OOS backtest:** `TIMERANGE=20260101-`

```bash
./scripts/hyperopt.sh                          # IS search
./scripts/apply_hyperopt_params.sh             # write user_data/strategies/<Strategy>.json
TIMERANGE=20260101- ./scripts/backtest.sh      # OOS with best params
# Defaults again: remove the JSON override
rm -f user_data/strategies/SampleStrategy.json
```

If optimizable params change `populate_indicators` (not only entry/exit columns), keep `--analyze-per-epoch` (default in `hyperopt.sh`). Without it every epoch can repeat the baseline result.

## Notes

- **Fees / funding:** `config.json` sets `fee: 0.0005` (5 bps). Funding rates download with futures data when available; treat equity as approximate.
- **Private logic:** proprietary strategies and run artifacts stay local (see `.gitignore`). Do not commit them to this repo.