# Backtester Status (Dec 2025)

## Current Scope
- Python package under `backtester/` (isolated from trading bot)
- CSV loader (`data_loader.py`) validates OHLCV inputs with timestamp filtering
- Math utilities (`math_utils.py`) implement RMA, ATR, ADX helpers
- Money Line indicator module (`indicators/money_line.py`) provides:
  - Configurable inputs for v9/v10 parity (`MoneyLineInputs` dataclass)
  - Primary + momentum signal detection (flip threshold, MA gap, ADX/volume filters)
  - Output `MoneyLineSignal` records with full metric context
- Strategy simulator (`simulator.py`) that consumes OHLCV data + indicator signals and reproduces the ATR-based TP1/TP2 runner logic (including ADX runner stops, trailing stop, MAE/MFE tracking, and placeholder quality filters)
- Command-line runner (`cli.py`) to execute quick tests against CSV data, print performance stats, and export trade logs
- Binance OHLC exporter (`scripts/export_binance_ohlcv.py`) for refreshing SOL/USDT candle sets straight from the public REST API

## Next Steps
1. Wire production quality scoring + adaptive leverage gating into the simulator so backtests align with live trade filters
2. Build batching utilities for multi-symbol / multi-parameter sweeps and persist the results to CSV/Parquet for analysis
3. Compare Binance-derived backtests vs. Drift trade history to calibrate slippage/latency assumptions
4. Extend CLI to accept saved indicator scores from the database once we export them (blocked signals, 1m data feed)

## Simulator Plan
- **Core engine (`backtester/simulator.py`)**: iterate through OHLCV rows, feed them to the Money Line indicator, and execute trades using the same ATR TP1/TP2 runner + adaptive leverage stack used in production.
- **Position model**: store entry price, size, ATR snapshot, TP1/TP2 levels, runner state, and MAE/MFE tracking so analytics match the bot’s database fields.
- **Execution hooks**: reuse config helpers (quality scoring thresholds, adaptive leverage tiers) to determine whether signals become trades, ensuring apples-to-apples results for v9 vs v10.
- **Metrics output**: aggregate PnL, win rate, profit factor, MAE/MFE distributions, and per-parameter summaries so sweeps can compare settings quickly.
- **Parameter sweeps**: now that the simulator is deterministic, the remaining work is orchestration (CLI wrapper + reporting) so we can explore grids quickly.

## Data Acquisition
- Use the helper script to pull candles (example grabs ~4 months of SOL/USDT 5m bars):

```bash
source .venv/bin/activate
python scripts/export_binance_ohlcv.py \
  --symbol SOLUSDT \
  --interval 5m \
  --start 2025-08-01 \
  --end 2025-11-28 \
  --output data/solusdt_5m.csv
```

- The script paginates Binance’s REST API (1000-candle chunks), pauses between requests to respect rate limits, and writes timestamped OHLCV columns that `backtester.data_loader` already expects.
- Re-run the export whenever we want fresh data; adjust `--start/--end` to widen the window or target different regimes.

## CLI Usage
Run a standalone backtest from the project root:

```bash
python -m backtester.cli \
  --csv data/solusdt_5m.csv \
  --symbol SOL-PERP \
  --timeframe 5 \
  --start 2025-09-01 \
  --end 2025-09-30 \
  --position-size 2500 \
  --max-bars 300 \
  --export-trades results/sol_sep.csv
```

The script uses the CSV loader (timestamped OHLCV data), Money Line indicator defaults, and simulator to print summary metrics. Exported CSVs contain per-trade fields (entry/exit, PnL, TP flags, MAE/MFE) for further analysis.

## Notes
- Package intentionally avoids dependencies beyond pandas/numpy for portability
- No trading bot files modified; all work lives under `backtester/`
- Update this document as modules (scoring, simulator, reporting) come online; immediate next edits should cover quality filters + sweep tooling once implemented.