Backtesting Guide
This guide describes how backtesting works in MangroveAI, including data sources, execution flow, persistence, and integration with the AI Copilot workflow.Data Sources
Market Data API (Primary)
Provider: CoinAPI (default) or CoinGecko (alternative)data_source="api"in backtest request- Supports assets like
ETH-USDT,BTC - Intervals:
1h,4h,1d - Default lookback: 12 months
Local CSV Files (Alternative)
For testing, custom data, or offline backtesting:data_source="file"in backtest request- CSV must contain:
timestamp,open,high,low,close,volume
Execution Flow
1. Request Validation
The endpoint validates required parameters including asset, interval, risk parameters, and strategy JSON format. Entry rules must have exactly 1 TRIGGER + 1 FILTER signal.2. Market Data Loading
Data is fetched from CoinAPI for the specified date range. The number of bars depends on the interval and date range.3. Strategy Execution
The backtesting engine:- Iterates through each bar in the historical data
- Evaluates entry signals when no position is open
- Evaluates exit conditions (signals, stop-loss, take-profit, time-based) when a position is open
- Tracks positions, orders, and trades
4. Metrics Calculation
After all bars are processed, performance metrics are computed:| Metric | Description |
|---|---|
sharpe_ratio | Risk-adjusted return (annualized) |
sortino_ratio | Downside risk-adjusted return |
calmar_ratio | Return / max drawdown |
irr_annualized | Internal rate of return |
max_drawdown | Largest peak-to-trough decline |
max_drawdown_duration | Longest drawdown period (bars) |
win_rate | Percentage of profitable trades |
Date Range Modes
| Mode | Parameters | Example |
|---|---|---|
| Explicit Range | start_date + end_date | Jan 1 to Jun 1, 2025 |
| From Date to Now | start_date only | Jun 1, 2025 to present |
| Lookback from End | end_date + lookback_months | 6 months back from Dec 31 |
| Recent History | lookback_months only | Last 9 months |
Integration with AI Copilot
When backtesting is invoked through the AI Copilot’sbacktest state:
- The copilot assembles a strategy configuration
- A backtest run record is created and linked to the strategy
- The backtest executes with the assembled parameters
- Results are stored in
context.backtest_results - Performance is evaluated against thresholds from
threshold_spec.json - On PASS: strategy status updates from
drafttoinactive - On FAIL: the copilot may attempt parameter optimization (up to 4 attempts)
Bulk Backtesting
The bulk endpoint (POST /api/v1/backtesting/backtest/bulk) evaluates multiple strategies over a shared date range. Market data is fetched once per unique (asset, timeframe) pair and reused across strategies.
For example, four BTC strategies using 1h data result in a single CoinAPI call. The data_fetches field in the response shows how many unique API calls were made.
ATR Parameter Handling
ATR parameters (atr_period, atr_volatility_factor) belong in execution_config, not in strategy_json. They are injected into the Strategy object at runtime. If execution_config is omitted, defaults from trading_defaults.json are used (atr_period=14, atr_volatility_factor=2.0).