tradelab 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-06-26
+
+### Added
+
+- **Metrics correctness and annualization**
+  - `sharpeAnnualized` and `sortinoAnnualized` fields in `buildMetrics` output, scaled by `sqrt(periodsPerYear)`.
+  - `annualizationPeriods` field exposing the computed periods-per-year used for scaling.
+  - All ratio metrics (`profitFactor`, `sharpe`, `calmar`, etc.) now clamped to a finite sentinel via `clampFinite`; metrics JSON never emits `Infinity` or `NaN`.
+  - Benchmark statistics (`alpha`, `beta`, `correlation`, `informationRatio`, `trackingError`) available in `metrics.benchmark` when `benchmarkReturns` is passed to `buildMetrics`.
+  - New top-level exports: `clampFinite`, `BIG_NUMBER`, `periodsPerYear`, `benchmarkStats`.
+
+- **`tradelab/ta` indicator namespace** (new subpath export)
+  - Oscillators: `rsi`, `macd`, `stochastic`.
+  - Channels: `bollinger`, `donchian`, `keltner`.
+  - Trend: `supertrend`, `vwap`.
+  - Re-exports from core: `ema`, `atr`, `swingHigh`, `swingLow`, `detectFVG`, `lastSwing`, `structureState`.
+  - All indicators return full-length arrays aligned to input (warmup positions are `undefined`).
+
+- **Async and agent signals**
+  - `backtestAsync(options)` — async sibling of `backtest()` where `signal()` may return a `Promise`; accepts `signalBudgetMs` to race each bar's signal against a timeout.
+  - `LlmSignal` class — wraps an async `resolve(context)` function with per-bar caching, a configurable `budgetMs` timeout, a no-lookahead candle proxy, and a `log` array of every bar decision.
+  - `backtestTicks()` now accepts a `seed` option for reproducible probabilistic limit fills.
+  - `LiveEngine` awaits async signals, so `LlmSignal` can be used directly in live/paper execution.
+
+- **`tradelab/mcp` MCP server** (new subpath export)
+  - `tradelab-mcp` binary — starts an MCP stdio server exposing tradelab tools to any MCP-capable agent (Claude Desktop, Cursor, etc.).
+  - Server exposes tools: `list_strategies`, `fetch_candles`, `run_backtest`, `walk_forward`.
+  - Name-addressable strategy registry: `listStrategies()`, `getStrategy(name)`, `registerStrategy(name, def)` (exported from `tradelab`).
+
+- **Research and overfitting toolkit** (`research` namespace, re-exported from `tradelab`)
+  - `research.monteCarlo(returns, options)` — equity curve Monte Carlo simulation.
+  - `research.deflatedSharpe(sharpe, options)` — deflated Sharpe ratio (DSR) adjustment.
+  - `research.sweepHaircut(results, options)` — apply DSR haircut across a parameter sweep.
+  - `research.probabilityOfBacktestOverfitting(folds, options)` — CSCV/PBO overfitting probability.
+  - `research.combinatorialPurgedSplits(candles, options)` — combinatorial purged cross-validation (CPCV) split generator.
+
+- **Parallel parameter optimization**
+  - `optimize(options)` — worker-thread pool that runs a parameter sweep in parallel; accepts `candles`, `signalModulePath`, `parameterSets`, `concurrency`, and `scoreBy`; returns `{ results, leaderboard, best }`.
+  - `grid(spec)` — helper that expands a `{ param: [v1, v2] }` spec into an array of parameter-set objects.
+
+- **Carry and funding cost model**
+  - `costs.carry` — annualized borrow/margin cost (`longAnnualBps`, `shortAnnualBps`); deducted proportionally over hold time.
+  - `costs.funding` — perpetual futures funding (`rateBps`, `intervalMs`, `anchorMs`); positive rates charge longs and credit shorts.
+  - Closed positions include `exit.financing` (total financing cost already deducted from `exit.pnl`).
+
+- **Live dashboard**
+  - `createDashboardServer(options)` exported from `tradelab/live` — zero-dependency SSE server using Node `node:http`.
+  - `--dashboard` and `--dashboardPort` CLI flags for `tradelab paper` and `tradelab live`.
+
+- **Dependencies**: `@modelcontextprotocol/sdk` and `zod` added as runtime dependencies.
+
+### Fixed
+
+- Metrics JSON no longer emits `Infinity` or `NaN`; all ratio metrics are clamped to `BIG_NUMBER` (1e9) or zero.
+- Non-annualized Sharpe was not directly comparable across different timeframes; `sharpeAnnualized` provides a consistent cross-timeframe measure.
+
+## [1.0.1]
+
+Prior release. See git history for details.

package/README.md

@@ -17,6 +17,8 @@
 
 Use it for backtests, portfolio and walk-forward validation, and live or paper execution through broker adapters while keeping the same `signal()` contract.
 
+AI-agent users: see [docs/mcp.md](docs/mcp.md) to run the research loop via MCP.
+
 ```bash
 npm install tradelab
 ```
@@ -29,6 +31,7 @@ npm install tradelab
 - [Quick start](#quick-start)
 - [Loading historical data](#loading-historical-data)
 - [Core concepts](#core-concepts)
+- [AI agents / MCP](#ai-agents--mcp)
 - [Portfolio mode](#portfolio-mode)
 - [Walk-forward optimization](#walk-forward-optimization)
 - [Tick backtests](#tick-backtests)
@@ -43,16 +46,21 @@ npm install tradelab
 
 ## What it includes
 
-| Area               | What you get                                                                             |
-| ------------------ | ---------------------------------------------------------------------------------------- |
-| **Engine**         | Candle and tick backtests with position sizing, exits, replay capture, and cost models   |
-| **Portfolio**      | Multi-system shared-capital simulation with live capital locking and daily loss halts    |
-| **Walk-forward**   | Rolling and anchored train/test validation with parameter search and stability summaries |
-| **Live execution** | Live and paper engines with broker adapters, state persistence, and orchestration        |
-| **Data**           | Yahoo Finance downloads, CSV import, and local cache helpers                             |
-| **Costs**          | Slippage, spread, and commission modeling                                                |
-| **Exports**        | HTML reports, metrics JSON, and trade CSV                                                |
-| **Dev experience** | TypeScript definitions, ESM/CJS support, CLI for quick runs                              |
+| Area                       | What you get                                                                                       |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Engine**                 | Candle and tick backtests with position sizing, exits, replay capture, and cost models             |
+| **Async / AI signals**     | Promise-returning signals, `LlmSignal` caching/budgets, and live async signal support              |
+| **Indicators (`ta`)**      | RSI, MACD, stochastic, Bollinger, Donchian, Keltner, Supertrend, VWAP, EMA, ATR, swing/FVG helpers |
+| **Optimization**           | `optimize()` worker-pool parameter sweep and `grid()` spec helper                                  |
+| **Portfolio**              | Multi-system shared-capital simulation with live capital locking and daily loss halts              |
+| **Walk-forward**           | Rolling and anchored train/test validation with parameter search and stability summaries           |
+| **Research / overfitting** | Monte Carlo, deflated Sharpe, sweep haircut, PBO (CSCV), and CPCV combinatorial purging            |
+| **AI / MCP server**        | `tradelab-mcp` stdio server — run the research loop from Claude Desktop, Cursor, or any MCP agent  |
+| **Live execution**         | Live and paper engines with broker adapters, state persistence, orchestration, and SSE dashboard   |
+| **Data**                   | Yahoo Finance downloads, CSV import, and local cache helpers                                       |
+| **Costs**                  | Slippage, spread, commission, annualized carry/borrow, and perpetual futures funding               |
+| **Exports**                | HTML reports, metrics JSON, and trade CSV                                                          |
+| **Dev experience**         | TypeScript definitions, ESM/CJS support, CLI for quick runs                                        |
 
 ---
 
@@ -98,6 +106,14 @@ After the run, check `result.metrics` for the headline numbers and `result.posit
 
 ---
 
+## AI agents / MCP
+
+`tradelab-mcp` lets MCP-capable agents run the research loop through tools: list strategies, fetch candles, run backtests, and walk-forward validate parameter grids.
+
+See [docs/mcp.md](docs/mcp.md) for setup and the Claude Desktop config.
+
+---
+
 ## Loading historical data
 
 Most users can start with `getHistoricalCandles()`. It abstracts over Yahoo Finance and CSV, handles caching, and normalizes the output so it feeds straight into `backtest()`.
@@ -254,12 +270,35 @@ import { backtestTicks } from "tradelab";
 const result = backtestTicks({
   ticks,
   queueFillProbability: 0.35,
+  seed: "research-run-1",
   signal,
 });
 ```
 
 Market entries fill on the next tick, limit orders can fill at the touch with configurable queue probability, and stop exits use the existing cost model with stop-specific slippage if you provide it in `costs.slippageByKind.stop`.
 
+Use `seed` to make probabilistic limit fills reproducible across repeated runs with the same data and options.
+
+## Async and LLM signals
+
+Use `backtestAsync()` when your signal returns a promise. `LlmSignal` wraps async model or agent calls with a per-bar budget, one-decision-per-bar cache, no-lookahead candle view, and a decision log.
+
+```js
+import { backtestAsync, LlmSignal } from "tradelab";
+
+const llm = new LlmSignal({
+  budgetMs: 2000,
+  async resolve({ candles, bar }) {
+    const closes = candles.map((c) => c.close);
+    return closes.at(-1) > closes.at(-5) ? { side: "long", stop: bar.close * 0.98, rr: 2 } : null;
+  },
+});
+
+const result = await backtestAsync({ candles, signal: llm.signal, signalBudgetMs: 3000 });
+```
+
+`LiveEngine` awaits async signals too, so the same `llm.signal` can move from research into paper or live execution.
+
 ---
 
 ## Live trading
@@ -314,6 +353,15 @@ const result = backtest({
     commissionPerUnit: 0,
     commissionPerOrder: 1,
     minCommission: 1,
+    carry: {
+      longAnnualBps: 500,
+      shortAnnualBps: 800,
+    },
+    funding: {
+      rateBps: 10,
+      intervalMs: 8 * 60 * 60 * 1000,
+      anchorMs: 0,
+    },
   },
 });
 ```
@@ -322,6 +370,9 @@ const result = backtest({
 - Spread is modeled as half-spread paid on entry and exit
 - Commission can be percentage-based, per-unit, per-order, or mixed
 - `minCommission` floors the fee per fill
+- `carry` models annualized overnight financing or borrow costs
+- `funding` models per-interval perpetual futures funding; positive rates charge longs and credit shorts
+- Closed trades include `exit.financing`, already deducted from `exit.pnl`
 
 > Leaving costs at zero is the most common cause of inflated backtests. Set them from the start.
 
@@ -396,6 +447,7 @@ You can also point `--strategy` at a local module that exports `default(args)`,
 ```bash
 node examples/emaCross.js
 node examples/yahooEmaCross.js SPY 1d 1y
+node examples/llmSignal.js
 ```
 
 The examples are a good place to start if you want something runnable before wiring the package into your own strategy code.
@@ -408,18 +460,27 @@ The examples are a good place to start if you want something runnable before wir
 
 ```js
 import { backtest, getHistoricalCandles, ema } from "tradelab";
+import { backtestAsync, LlmSignal, optimize, grid } from "tradelab";
+import { research } from "tradelab"; // monteCarlo, deflatedSharpe, probabilityOfBacktestOverfitting, ...
 import { fetchHistorical } from "tradelab/data";
-import { LiveEngine, PaperEngine } from "tradelab/live";
+import { LiveEngine, PaperEngine, createDashboardServer } from "tradelab/live";
+import { rsi, macd, bollinger, vwap, supertrend } from "tradelab/ta";
+import { createServer, startStdioServer } from "tradelab/mcp";
 ```
 
 ### CommonJS
 
 ```js
 const { backtest, getHistoricalCandles, ema } = require("tradelab");
+const { backtestAsync, LlmSignal, optimize, grid } = require("tradelab");
+const { research } = require("tradelab");
 const { fetchHistorical } = require("tradelab/data");
-const { LiveEngine, PaperEngine } = require("tradelab/live");
+const { LiveEngine, PaperEngine, createDashboardServer } = require("tradelab/live");
+const { rsi, macd, bollinger, vwap, supertrend } = require("tradelab/ta");
 ```
 
+> `tradelab/mcp` is ESM-only (the MCP SDK is ESM-only). Use the `tradelab-mcp` binary or import it from an ESM context.
+
 ---
 
 ## Documentation
@@ -429,6 +490,8 @@ const { LiveEngine, PaperEngine } = require("tradelab/live");
 | [Backtest engine](docs/backtest-engine.md)             | Signal contract, all options, result shape, portfolio mode, walk-forward       |
 | [Data, reporting, and CLI](docs/data-reporting-cli.md) | Data loading, cache behavior, exports, CLI reference                           |
 | [Live trading](docs/live-trading.md)                   | Live engine, broker adapters, paper mode, orchestration, and state persistence |
+| [MCP server](docs/mcp.md)                              | Run the research loop from any MCP-capable agent                               |
+| [Research & overfitting](docs/research.md)             | Monte Carlo, deflated Sharpe, PBO, CPCV, sweep haircut                         |
 | [Strategy examples](docs/examples.md)                  | Mean reversion, breakout, sentiment, LLM, and portfolio strategy patterns      |
 | [API reference](docs/api-reference.md)                 | Compact index of every public export                                           |
 

package/bin/tradelab-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startStdioServer } from "../src/mcp/server.js";
+
+startStdioServer().catch((error) => {
+  console.error("tradelab-mcp failed to start:", error);
+  process.exit(1);
+});

package/bin/tradelab.js

@@ -116,6 +116,22 @@ function createBrokerAdapter(args, overrides = {}) {
   throw new Error(`Unsupported broker "${brokerName}"`);
 }
 
+async function maybeStartDashboard(args, source) {
+  if (!toBoolean(args.dashboard, false)) return null;
+  const { createDashboardServer } = await import("../src/live/dashboard/server.js");
+  const dashboard = createDashboardServer({
+    source,
+    port: toNumber(args.dashboardPort, 4317),
+  });
+  const url = await dashboard.start();
+  console.log(`dashboard: ${url}`);
+  return dashboard;
+}
+
+async function closeDashboard(dashboard) {
+  if (dashboard) await dashboard.close();
+}
+
 function brokerConfigFromArgs(args, overrides = {}) {
   return {
     apiKey: overrides.apiKey ?? args.apiKey,
@@ -514,6 +530,7 @@ async function commandLive(args, overrides = {}) {
       maxDailyLossPct: toNumber(fileConfig.maxDailyLossPct ?? args.maxDailyLossPct, 0),
       equity: toNumber(fileConfig.equity ?? args.equity, 10_000),
     });
+    const dashboard = await maybeStartDashboard(args, orchestrator);
     await broker.connect(brokerConfig);
     await orchestrator.start();
 
@@ -526,6 +543,15 @@ async function commandLive(args, overrides = {}) {
 
     if (!watch) {
       await orchestrator.stop();
+      await closeDashboard(dashboard);
+    } else if (dashboard) {
+      const shutdown = async () => {
+        await orchestrator.stop();
+        await closeDashboard(dashboard);
+        process.exit(0);
+      };
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
     }
     return;
   }
@@ -551,6 +577,7 @@ async function commandLive(args, overrides = {}) {
     storage,
     brokerConfig,
   });
+  const dashboard = await maybeStartDashboard(args, engine);
 
   await engine.start();
 
@@ -563,11 +590,13 @@ async function commandLive(args, overrides = {}) {
 
   if (!watch) {
     await engine.stop();
+    await closeDashboard(dashboard);
     return;
   }
 
   const shutdown = async () => {
     await engine.stop();
+    await closeDashboard(dashboard);
     process.exit(0);
   };
   process.once("SIGINT", shutdown);

package/dist/cjs/data.cjs

@@ -119,22 +119,93 @@ function calculatePositionSize({
   return quantity >= minQty ? quantity : 0;
 }
 
+// src/metrics/finite.js
+var BIG_NUMBER = 1e9;
+function clampFinite(value, fallback = 0) {
+  if (value === Infinity) return BIG_NUMBER;
+  if (value === -Infinity) return -BIG_NUMBER;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return fallback;
+}
+
+// src/metrics/annualize.js
+var TRADING_DAYS = 252;
+var RTH_HOURS = 6.5;
+var MS_PER_YEAR = 365 * 24 * 60 * 60 * 1e3;
+var INTERVAL_PERIODS = {
+  "1m": TRADING_DAYS * RTH_HOURS * 60,
+  "2m": TRADING_DAYS * RTH_HOURS * 30,
+  "5m": TRADING_DAYS * RTH_HOURS * 12,
+  "15m": TRADING_DAYS * RTH_HOURS * 4,
+  "30m": TRADING_DAYS * RTH_HOURS * 2,
+  "1h": TRADING_DAYS * RTH_HOURS,
+  "60m": TRADING_DAYS * RTH_HOURS,
+  "1d": TRADING_DAYS,
+  "1wk": 52,
+  "1mo": 12
+};
+function periodsPerYear(interval, estBarMs) {
+  if (interval && INTERVAL_PERIODS[interval]) return INTERVAL_PERIODS[interval];
+  if (Number.isFinite(estBarMs) && estBarMs > 0) {
+    return Math.round(MS_PER_YEAR / estBarMs);
+  }
+  return TRADING_DAYS;
+}
+
+// src/metrics/benchmark.js
+function mean(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function benchmarkStats(strategyReturns, benchmarkReturns) {
+  const nullStats = {
+    alpha: null,
+    beta: null,
+    correlation: null,
+    informationRatio: null,
+    trackingError: null
+  };
+  if (!Array.isArray(strategyReturns) || !Array.isArray(benchmarkReturns) || strategyReturns.length === 0 || strategyReturns.length !== benchmarkReturns.length) {
+    return nullStats;
+  }
+  const meanStrat = mean(strategyReturns);
+  const meanBench = mean(benchmarkReturns);
+  let covar = 0;
+  let varBench = 0;
+  let varStrat = 0;
+  for (let i = 0; i < strategyReturns.length; i += 1) {
+    const ds = strategyReturns[i] - meanStrat;
+    const db = benchmarkReturns[i] - meanBench;
+    covar += ds * db;
+    varBench += db * db;
+    varStrat += ds * ds;
+  }
+  const beta = varBench === 0 ? 0 : covar / varBench;
+  const alpha = meanStrat - beta * meanBench;
+  const denom = Math.sqrt(varStrat * varBench);
+  const correlation = denom === 0 ? 0 : covar / denom;
+  const active = strategyReturns.map((r, i) => r - benchmarkReturns[i]);
+  const meanActive = mean(active);
+  const trackingError = Math.sqrt(mean(active.map((a) => (a - meanActive) ** 2)));
+  const informationRatio = trackingError === 0 ? 0 : meanActive / trackingError;
+  return { alpha, beta, correlation, informationRatio, trackingError };
+}
+
 // src/metrics/buildMetrics.js
 function sum(values) {
   return values.reduce((total, value) => total + value, 0);
 }
-function mean(values) {
+function mean2(values) {
   return values.length ? sum(values) / values.length : 0;
 }
 function stddev(values) {
   if (values.length <= 1) return 0;
-  const avg = mean(values);
-  return Math.sqrt(mean(values.map((value) => (value - avg) ** 2)));
+  const avg = mean2(values);
+  return Math.sqrt(mean2(values.map((value) => (value - avg) ** 2)));
 }
 function sortino(values) {
   const losses = values.filter((value) => value < 0);
   const downsideDeviation = stddev(losses.length ? losses : [0]);
-  const avg = mean(values);
+  const avg = mean2(values);
   return downsideDeviation === 0 ? avg > 0 ? Infinity : 0 : avg / downsideDeviation;
 }
 function dayKeyUTC(timeMs) {
@@ -220,14 +291,22 @@ function percentile(values, percentileRank) {
   const index = Math.floor((sorted.length - 1) * percentileRank);
   return sorted[index];
 }
-var PROFIT_FACTOR_CAP = 1e6;
 function finiteProfitFactor(grossProfit, grossLoss) {
   if (grossLoss === 0) {
-    return grossProfit > 0 ? PROFIT_FACTOR_CAP : 0;
+    return grossProfit > 0 ? BIG_NUMBER : 0;
   }
   return grossProfit / grossLoss;
 }
-function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqSeries }) {
+function buildMetrics({
+  closed,
+  equityStart,
+  equityFinal,
+  candles,
+  estBarMs,
+  eqSeries,
+  interval,
+  benchmarkReturns
+}) {
   const legs = [...closed].sort((left, right) => left.exit.time - right.exit.time);
   const completedTrades = [];
   const tradeRs = [];
@@ -297,11 +376,11 @@ function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqS
       if (pnl > 0) shortTradeWins += 1;
     }
   }
-  const avgR = mean(tradeRs);
+  const avgR = mean2(tradeRs);
   const { maxWin, maxLoss } = streaks(labels);
-  const expectancy = mean(tradePnls);
+  const expectancy = mean2(tradePnls);
   const tradeReturnStd = stddev(tradeReturns);
-  const sharpePerTrade = tradeReturnStd === 0 ? tradeReturns.length ? Infinity : 0 : mean(tradeReturns) / tradeReturnStd;
+  const sharpePerTrade = tradeReturnStd === 0 ? tradeReturns.length ? Infinity : 0 : mean2(tradeReturns) / tradeReturnStd;
   const sortinoPerTrade = sortino(tradeReturns);
   const profitFactorPositions = finiteProfitFactor(grossProfitPositions, grossLossPositions);
   const profitFactorLegs = finiteProfitFactor(grossProfitLegs, grossLossLegs);
@@ -309,11 +388,11 @@ function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqS
   const calmar = maxDrawdown === 0 ? returnPct > 0 ? Infinity : 0 : returnPct / maxDrawdown;
   const totalBars = Math.max(1, candles.length);
   const exposurePct = openBars / totalBars;
-  const avgHoldMin = mean(holdDurationsMinutes);
+  const avgHoldMin = mean2(holdDurationsMinutes);
   const equitySeries = eqSeries && eqSeries.length ? eqSeries : buildEquitySeriesFromLegs({ legs, equityStart });
   const dailyReturnsSeries = dailyReturns(equitySeries);
   const dailyStd = stddev(dailyReturnsSeries);
-  const sharpeDaily = dailyStd === 0 ? dailyReturnsSeries.length ? Infinity : 0 : mean(dailyReturnsSeries) / dailyStd;
+  const sharpeDaily = dailyStd === 0 ? dailyReturnsSeries.length ? Infinity : 0 : mean2(dailyReturnsSeries) / dailyStd;
   const sortinoDaily = sortino(dailyReturnsSeries);
   const dailyWinRate = dailyReturnsSeries.length ? dailyReturnsSeries.filter((value) => value > 0).length / dailyReturnsSeries.length : 0;
   const rDistribution = {
@@ -335,28 +414,36 @@ function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqS
       trades: longTradesCount,
       winRate: longTradesCount ? longTradeWins / longTradesCount : 0,
       avgPnL: longTradesCount ? longPnLSum / longTradesCount : 0,
-      avgR: mean(longRs)
+      avgR: mean2(longRs)
     },
     short: {
       trades: shortTradesCount,
       winRate: shortTradesCount ? shortTradeWins / shortTradesCount : 0,
       avgPnL: shortTradesCount ? shortPnLSum / shortTradesCount : 0,
-      avgR: mean(shortRs)
+      avgR: mean2(shortRs)
     }
   };
+  const periods = periodsPerYear(interval, estBarMs);
+  const sqrtPeriods = Math.sqrt(periods);
+  const sharpeAnnualized = clampFinite(clampFinite(sharpeDaily) * sqrtPeriods);
+  const sortinoAnnualized = clampFinite(clampFinite(sortinoDaily) * sqrtPeriods);
+  const benchmark = benchmarkStats(dailyReturnsSeries, benchmarkReturns ?? []);
   return {
     trades: completedTrades.length,
     winRate: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
-    profitFactor: profitFactorPositions,
+    profitFactor: clampFinite(profitFactorPositions),
     expectancy,
     totalR,
     avgR,
-    sharpe: sharpeDaily,
-    sharpePerTrade,
-    sortinoPerTrade,
+    sharpe: clampFinite(sharpeDaily),
+    sharpeAnnualized,
+    sortinoAnnualized,
+    sharpePerTrade: clampFinite(sharpePerTrade),
+    sortinoPerTrade: clampFinite(sortinoPerTrade),
+    annualizationPeriods: periods,
     maxDrawdown,
     maxDrawdownPct: maxDrawdown,
-    calmar,
+    calmar: clampFinite(calmar),
     maxConsecWins: maxWin,
     maxConsecLosses: maxLoss,
     avgHold: avgHoldMin,
@@ -366,12 +453,13 @@ function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqS
     returnPct,
     finalEquity: equityFinal,
     startEquity: equityStart,
-    profitFactor_pos: profitFactorPositions,
-    profitFactor_leg: profitFactorLegs,
+    profitFactor_pos: clampFinite(profitFactorPositions),
+    profitFactor_leg: clampFinite(profitFactorLegs),
     winRate_pos: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
     winRate_leg: legs.length ? winningLegCount / legs.length : 0,
-    sharpeDaily,
-    sortinoDaily,
+    sharpeDaily: clampFinite(sharpeDaily),
+    sortinoDaily: clampFinite(sortinoDaily),
+    benchmark,
     sideBreakdown,
     long: sideBreakdown.long,
     short: sideBreakdown.short,
@@ -380,7 +468,7 @@ function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqS
     daily: {
       count: dailyReturnsSeries.length,
       winRate: dailyWinRate,
-      avgReturn: mean(dailyReturnsSeries)
+      avgReturn: mean2(dailyReturnsSeries)
     }
   };
 }
@@ -800,6 +888,30 @@ function dayKeyET(timeMs) {
   const pseudoEtTime = anchor.getTime() + hoursET * 60 * 60 * 1e3 + minutesETDay * 60 * 1e3;
   return dayKeyUTC2(pseudoEtTime);
 }
+var MS_PER_YEAR2 = 365 * 24 * 60 * 60 * 1e3;
+function fundingEvents(fromMs, toMs, intervalMs, anchorMs = 0) {
+  if (!(intervalMs > 0) || toMs <= fromMs) return 0;
+  const firstK = Math.floor((fromMs - anchorMs) / intervalMs) + 1;
+  const lastK = Math.floor((toMs - anchorMs) / intervalMs);
+  return Math.max(0, lastK - firstK + 1);
+}
+function financingCost({ side, notional, fromMs, toMs, costs }) {
+  const model = costs || {};
+  const absNotional = Math.abs(notional);
+  let cost = 0;
+  if (model.carry) {
+    const annualBps = side === "long" ? model.carry.longAnnualBps ?? 0 : model.carry.shortAnnualBps ?? 0;
+    const years = Math.max(0, toMs - fromMs) / MS_PER_YEAR2;
+    cost += absNotional * (annualBps / 1e4) * years;
+  }
+  const funding = model.funding;
+  if (funding && funding.intervalMs > 0 && Number.isFinite(funding.rateBps)) {
+    const count = fundingEvents(fromMs, toMs, funding.intervalMs, funding.anchorMs ?? 0);
+    const perEvent = absNotional * (funding.rateBps / 1e4);
+    cost += (side === "long" ? 1 : -1) * perEvent * count;
+  }
+  return cost;
+}
 
 // src/engine/backtest.js
 function asNumber(value) {
@@ -931,6 +1043,7 @@ function mergeOptions(options) {
     maxSlipROnFill: options.maxSlipROnFill ?? 0.4,
     collectEqSeries: options.collectEqSeries ?? true,
     collectReplay: options.collectReplay ?? true,
+    benchmarkReturns: Array.isArray(options.benchmarkReturns) ? options.benchmarkReturns : null,
     strict: options.strict ?? false
   };
 }
@@ -1053,7 +1166,14 @@ function backtest(rawOptions) {
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const pnl = grossPnl - entryFeePortion - exitFeeTotal;
+    const financing = financingCost({
+      side: openPos.side,
+      notional: entryFill * qty,
+      fromMs: openPos.openTime,
+      toMs: time,
+      costs
+    });
+    const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
     currentEquity += pnl;
     dayPnl += pnl;
     if (wantEqSeries) {
@@ -1081,6 +1201,7 @@ function backtest(rawOptions) {
         time,
         reason,
         pnl,
+        financing,
         exitATR: openPos._lastATR ?? void 0
       },
       mfeR: openPos._mfeR ?? 0,
@@ -1483,7 +1604,9 @@ function backtest(rawOptions) {
     equityFinal: currentEquity,
     candles,
     estBarMs: estimatedBarMs,
-    eqSeries
+    eqSeries,
+    interval: options.interval,
+    benchmarkReturns: options.benchmarkReturns
   });
   const positions = closed.filter((trade) => trade.exit.reason !== "SCALE");
   const lastPrice = asNumber(candles[candles.length - 1]?.close);