Backtest - Complete API Reference
Validate trading strategies using historical data, walk-forward analysis, and Monte Carlo simulation.
Chat Commands
Run Backtest
/backtest momentum --from 2024-01-01 --to 2024-12-31 /backtest mean-reversion --market "Trump 2028" --days 90 /backtest my-strategy --capital 10000
Quick Stats
/backtest stats momentum Show strategy metrics /backtest compare momentum arb Compare two strategies /backtest monte-carlo momentum Run Monte Carlo simulation
Results
/backtest results Show recent results /backtest stats Alias for results /backtest results <id> --detailed Detailed breakdown /backtest export Export last results as CSV
TypeScript API Reference
Create Backtest Engine
import { createBacktestEngine } from 'clodds/backtest';
const backtest = createBacktestEngine({ // Data source dataSource: 'polymarket', // or custom data provider
// Capital initialCapital: 10000,
// Fees (Polymarket: 0% on most markets; Kalshi: ~1.2% avg) fees: { maker: 0, // 0% maker fee (Polymarket most markets) taker: 0, // 0% taker fee (Polymarket most markets) // For 15-min crypto markets or Kalshi, use: taker: 0.012 },
// Slippage model slippageModel: 'realistic', // 'none' | 'fixed' | 'realistic' slippageBps: 10, });
Run Basic Backtest
const result = await backtest.run({ strategy: 'momentum', startDate: '2024-01-01', endDate: '2024-12-31', parameters: { lookbackPeriod: 14, entryThreshold: 0.02, exitThreshold: 0.01, }, });
console.log(Total Return: ${result.totalReturn}%);
console.log(Sharpe Ratio: ${result.sharpeRatio});
console.log(Max Drawdown: ${result.maxDrawdown}%);
console.log(Win Rate: ${result.winRate}%);
console.log(Profit Factor: ${result.profitFactor});
Walk-Forward Analysis
// Out-of-sample validation const wf = await backtest.walkForward({ strategy: 'momentum', startDate: '2023-01-01', endDate: '2024-12-31',
// Train/test split trainPeriod: '6M', testPeriod: '1M', step: '1M',
// Optimization optimize: ['lookbackPeriod', 'entryThreshold'], optimizationMetric: 'sharpe', });
console.log(In-Sample Sharpe: ${wf.inSampleSharpe});
console.log(Out-of-Sample Sharpe: ${wf.outOfSampleSharpe});
console.log(Overfitting Ratio: ${wf.overfitRatio});
Monte Carlo Simulation
// Stress test with randomization const mc = await backtest.monteCarlo({ strategy: 'momentum', trades: historicalTrades,
// Simulation settings simulations: 10000, confidenceLevel: 0.95,
// Randomization shuffleTrades: true, randomizeReturns: true, });
console.log(Expected Return: ${mc.expectedReturn}%);
console.log(95% VaR: ${mc.valueAtRisk}%);
console.log(Worst Case: ${mc.worstCase}%);
console.log(Best Case: ${mc.bestCase}%);
console.log(Probability of Profit: ${mc.probProfit}%);
Performance Metrics
const metrics = await backtest.getMetrics(result);
console.log('=== Performance ===');
console.log(Total Return: ${metrics.totalReturn}%);
console.log(CAGR: ${metrics.cagr}%);
console.log(Volatility: ${metrics.volatility}%);
console.log('=== Risk ===');
console.log(Sharpe Ratio: ${metrics.sharpeRatio});
console.log(Sortino Ratio: ${metrics.sortinoRatio});
console.log(Max Drawdown: ${metrics.maxDrawdown}%);
console.log(Max Drawdown Duration: ${metrics.maxDrawdownDuration} days);
console.log('=== Trading ===');
console.log(Total Trades: ${metrics.totalTrades});
console.log(Win Rate: ${metrics.winRate}%);
console.log(Profit Factor: ${metrics.profitFactor});
console.log(Avg Win: ${metrics.avgWin}%);
console.log(Avg Loss: ${metrics.avgLoss}%);
console.log(Expectancy: ${metrics.expectancy}%);
Custom Strategy
// Define custom strategy const myStrategy = { name: 'my-strategy',
onData: async (data, context) => { const price = data.price; const sma = data.indicators.sma(20);
if (price < sma * 0.95 && !context.hasPosition) {
return { action: 'buy', size: context.availableCapital * 0.1 };
}
if (price > sma * 1.05 && context.hasPosition) {
return { action: 'sell', size: 'all' };
}
return { action: 'hold' };
}, };
const result = await backtest.run({ strategy: myStrategy, startDate: '2024-01-01', endDate: '2024-12-31', });
Built-in Strategies
Strategy Description
momentum
Follow price trends
mean-reversion
Buy dips, sell rallies
arbitrage
Cross-platform price differences
breakout
Enter on range breakouts
pairs
Correlated market pairs
Metrics Explained
Metric Good Value Description
Sharpe Ratio
1.0 Risk-adjusted return
Sortino Ratio
1.5 Downside-adjusted return
Max Drawdown < 20% Worst peak-to-trough
Win Rate
50% Winning trades %
Profit Factor
1.5 Gross profit / gross loss
Expectancy
0 Expected $ per trade
Best Practices
-
Use walk-forward — Avoid overfitting
-
Include fees — Realistic cost modeling
-
Test multiple periods — Don't cherry-pick dates
-
Monte Carlo — Understand variance
-
Out-of-sample — Always validate on unseen data