--- name: backtest-4d293ce834fe description: "Test trading strategies on historical data with Monte Carlo simulation" emoji: "📈" --- # 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 --detailed Detailed breakdown /backtest export Export last results as CSV ``` --- ## TypeScript API Reference ### Create Backtest Engine ```typescript 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 ```typescript 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 ```typescript // 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 ```typescript // 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 ```typescript 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 ```typescript // 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 1. **Use walk-forward** — Avoid overfitting 2. **Include fees** — Realistic cost modeling 3. **Test multiple periods** — Don't cherry-pick dates 4. **Monte Carlo** — Understand variance 5. **Out-of-sample** — Always validate on unseen data --- Source attribution: alsk1992 Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/backtest/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 alsk1992 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: alsk1992 Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/backtest/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Finance & Accounting, Marketing Roles: Data Analyst, Financial Analyst, Growth Marketer Specialties: API Tools: Clodds Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3fa3ea2c655964d69488f861c0af4464806faeea4799990fafa58dee97f6dcbc