# Replay and strategy (/vela-pro/api/replay-and-strategy)



This page documents bar replay options and custom bar controls alongside the strategy tester APIs, including the strategy tracker, backtest report builder, and performance metric types.

Import symbols on this page from `@luxalgo/vela-pro`. Related guides: [Bar replay](/vela-pro/charts/replay), [Strategy tester](/vela-pro/indicators/backtesting/strategy-tester), [Backtest results](/vela-pro/indicators/backtesting/results).

Feature enablers for this area ([`enableReplay`](/vela-pro/api/enablers#enablereplay), [`enableStrategyTester`](/vela-pro/api/enablers#enablestrategytester)) are documented on [Enablers and options](/vela-pro/api/enablers).

## Functions [#functions]

### `buildStrategyReport` [#buildstrategyreport]

```typescript
function buildStrategyReport(input: { title: string; state: StrategyState; trades: readonly StrategyTrade[] }): StrategyReport
```

See also: [`StrategyReport`](/vela-pro/api/replay-and-strategy#strategyreport). From `@luxalgo/vela/plugin`: `StrategyState`, `StrategyTrade`.

### `replayResolutionControl` [#replayresolutioncontrol]

A replay-bar control ([`ReplayBarControl`](/vela-pro/api/replay-and-strategy#replaybarcontrol)) choosing the replay resolution: Auto by default (candles appear whole, at the chart's timeframe) and a finer pick replays each candle through that timeframe's bars, one update per speed step (at 1x, a 15m candle from 1m updates takes 15 s).

```typescript
function replayResolutionControl(opts?: ReplayResolutionControlOptions): ReplayBarControl
```

See also: [`ReplayBarControl`](/vela-pro/api/replay-and-strategy#replaybarcontrol), [`ReplayResolutionControlOptions`](/vela-pro/api/replay-and-strategy#replayresolutioncontroloptions).

### `timeframeMs` [#timeframems]

One chart bar's duration in ms for a timeframe string (`'60'`, `'1D'`, `'W'`, `'M'`, `'30S'`); null when unknown.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function timeframeMs(tf: string): number | null
```

## Classes [#classes]

### `StrategyTesterPanel` [#strategytesterpanel]

The strategy tester: a summary strip (net profit, trades, win rate, drawdown, profit factor over the equity curve) that maximizes into the full report (Performance, Trades Analysis and Trades Log). It draws its own header in both.

```typescript
class StrategyTesterPanel {
    constructor(
        ctx: WidgetContext,
        tracker: StrategyTracker,
        header: BottomPanelHeader,
        openDock?: () => void,
    );
    readonly el: HTMLElement;
    readonly isMobile: boolean;
    setVisible(on: boolean): void;
    destroy(): void;
}
```

| Member         | Type                                                                                               | Description                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `constructor`  | `(ctx: WidgetContext, tracker: StrategyTracker, header: BottomPanelHeader, openDock?: () => void)` | `openDock`: Open the dock on this panel (the mobile Backtest button). Default: `openDock = () => {}`. |
| `el`           | `HTMLElement`                                                                                      |                                                                                                       |
| `isMobile`     | `boolean`                                                                                          | The shell runs its mobile layout: the report opens from a button, never as a strip.                   |
| `setVisible()` | `(on: boolean) => void`                                                                            |                                                                                                       |
| `destroy()`    | `() => void`                                                                                       |                                                                                                       |

See also: [`BottomPanelHeader`](/vela-pro/api/layout#bottompanelheader), [`StrategyTracker`](/vela-pro/api/replay-and-strategy#strategytracker). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `StrategyTracker` [#strategytracker]

```typescript
class StrategyTracker {
    constructor(ctx: WidgetContext);
    onFirstRun: ((s: TrackedStrategy) => void) | null;
    readonly selected: TrackedStrategy | null;
    list(): TrackedStrategy[];
    select(id: string): void;
    onChange(cb: () => void): () => void;
    destroy(): void;
}
```

| Member        | Type                                     | Description                                                    |
| ------------- | ---------------------------------------- | -------------------------------------------------------------- |
| `constructor` | `(ctx: WidgetContext)`                   |                                                                |
| `onFirstRun`  | `((s: TrackedStrategy) => void) \| null` | Called the first time a strategy shows up on the active chart. |
| `selected`    | `TrackedStrategy \| null`                |                                                                |
| `list()`      | `() => TrackedStrategy[]`                |                                                                |
| `select()`    | `(id: string) => void`                   |                                                                |
| `onChange()`  | `(cb: () => void) => () => void`         |                                                                |
| `destroy()`   | `() => void`                             |                                                                |

See also: [`TrackedStrategy`](/vela-pro/api/replay-and-strategy#trackedstrategy). From `@luxalgo/vela/plugin`: `WidgetContext`.

## Interfaces and types [#interfaces-and-types]

### `EquityPoint` [#equitypoint]

```typescript
interface EquityPoint {
    time: number;
    equity: number;
    drawdown: number;
    trade?: number;
    side?: 'long' | 'short';
}
```

| Member     | Type                | Description                                                                              |
| ---------- | ------------------- | ---------------------------------------------------------------------------------------- |
| `time`     | `number`            |                                                                                          |
| `equity`   | `number`            | Closed-trade net profit so far.                                                          |
| `drawdown` | `number`            | Distance below the running peak (≤ 0).                                                   |
| `trade?`   | `number`            | The closed trade this point follows (`ReportTrade.index`); absent on the starting point. |
| `side?`    | `'long' \| 'short'` |                                                                                          |

### `ReplayBarControl` [#replaybarcontrol]

A dropdown the host adds to the replay control bar, right after the speed selector: e.g. the timeframe whose bars replay each candle (`chart.replay.setTicks`; [`replayResolutionControl`](/vela-pro/api/replay-and-strategy#replayresolutioncontrol) is the ready-made one).

```typescript
interface ReplayBarControl {
    id: string;
    title?: string;
    options: readonly ReplayBarOption[] | ((ctx: { chart: WidgetContext['chart'] }) => readonly ReplayBarOption[]);
    value?: string;
    tooltip?: string;
    onChange(value: string, ctx: { chart: WidgetContext['chart'] }): void;
}
```

| Member       | Type                                                                                                     | Description                                                                                                                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | `string`                                                                                                 |                                                                                                                                                                               |
| `title?`     | `string`                                                                                                 | Heading shown at the top of the open list (the bar itself shows the selection).                                                                                               |
| `options`    | `readonly ReplayBarOption[] \| ((ctx: { chart: WidgetContext['chart'] }) => readonly ReplayBarOption[])` | The entries, or a function of the chart, re-read whenever a replay starts (the chart's market may have changed since).                                                        |
| `value?`     | `string`                                                                                                 | The default selection (default: the first option): also where the bar falls back when a re-read no longer lists the user's pick.                                              |
| `tooltip?`   | `string`                                                                                                 | Hover text on the dropdown.                                                                                                                                                   |
| `onChange()` | `(value: string, ctx: { chart: WidgetContext['chart'] }) => void`                                        | Runs on every pick, and again with the current value whenever the bar binds a chart (a shell may replace its instance), so the control's effect always lands on the live one. |

See also: [`ReplayBarOption`](/vela-pro/api/replay-and-strategy#replaybaroption). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `ReplayBarOption` [#replaybaroption]

One entry of a [`ReplayBarControl`](/vela-pro/api/replay-and-strategy#replaybarcontrol).

```typescript
interface ReplayBarOption {
    value: string;
    label: string;
    selected?: string;
}
```

| Member      | Type     | Description                                                      |
| ----------- | -------- | ---------------------------------------------------------------- |
| `value`     | `string` |                                                                  |
| `label`     | `string` | The entry in the open list.                                      |
| `selected?` | `string` | What the bar shows once this entry is picked (default: `label`). |

### `ReplayPickShade` [#replaypickshade]

How the start pick veils the chart right of the pick line.

```typescript
interface ReplayPickShade {
    color?: string;
    opacity?: number;
}
```

| Member     | Type     | Description                    |
| ---------- | -------- | ------------------------------ |
| `color?`   | `string` | Default: the chart background. |
| `opacity?` | `number` | 0..1: default 0.6.             |

### `ReplayResolutionControlOptions` [#replayresolutioncontroloptions]

Options for [`replayResolutionControl`](/vela-pro/api/replay-and-strategy#replayresolutioncontrol).

```typescript
interface ReplayResolutionControlOptions {
    timeframes?: readonly string[];
    title?: string;
    tooltip?: string;
}
```

| Member        | Type                | Description                                                                     |
| ------------- | ------------------- | ------------------------------------------------------------------------------- |
| `timeframes?` | `readonly string[]` | Candidate finer timeframes; each is offered when it evenly divides the chart's. |
| `title?`      | `string`            | The list heading (default `'Replay Resolution'`).                               |
| `tooltip?`    | `string`            | The dropdown's hover text.                                                      |

### `ReportTrade` [#reporttrade]

```typescript
interface ReportTrade {
    index: number;
    id: string;
    side: 'long' | 'short';
    qty: number;
    entryId: string;
    entryTime: number;
    entryPrice: number;
    exitId: string | null;
    exitTime: number | null;
    exitPrice: number | null;
    open: boolean;
    pnl: number | null;
    pnlPct: number | null;
    cumulative: number | null;
    runup: number | null;
    drawdown: number | null;
    commission: number | null;
}
```

### `SideMetrics` [#sidemetrics]

```typescript
interface SideMetrics {
    netProfit: number;
    netProfitPct: number | null;
    grossProfit: number;
    grossLoss: number;
    profitFactor: number | null;
    commission: number;
    trades: number;
    wins: number;
    losses: number;
    even: number;
    winRate: number | null;
    avgTrade: number | null;
    avgTradePct: number | null;
    avgWin: number | null;
    avgLoss: number | null;
    winLossRatio: number | null;
    largestWin: number | null;
    largestLoss: number | null;
    largestWinPct: number | null;
    largestLossPct: number | null;
    avgDurationMs: number | null;
    avgWinDurationMs: number | null;
    avgLossDurationMs: number | null;
    maxConsecutiveWins: number;
    maxConsecutiveLosses: number;
    avgPerDay: number | null;
    avgPerWeek: number | null;
    cagr: number | null;
    longestMs: number | null;
    shortestMs: number | null;
    tradesPerDay: number | null;
    tradesPerWeek: number | null;
}
```

| Member                 | Type             | Description                                                     |
| ---------------------- | ---------------- | --------------------------------------------------------------- |
| `netProfit`            | `number`         |                                                                 |
| `netProfitPct`         | `number \| null` |                                                                 |
| `grossProfit`          | `number`         |                                                                 |
| `grossLoss`            | `number`         |                                                                 |
| `profitFactor`         | `number \| null` |                                                                 |
| `commission`           | `number`         |                                                                 |
| `trades`               | `number`         |                                                                 |
| `wins`                 | `number`         |                                                                 |
| `losses`               | `number`         |                                                                 |
| `even`                 | `number`         |                                                                 |
| `winRate`              | `number \| null` |                                                                 |
| `avgTrade`             | `number \| null` |                                                                 |
| `avgTradePct`          | `number \| null` |                                                                 |
| `avgWin`               | `number \| null` |                                                                 |
| `avgLoss`              | `number \| null` |                                                                 |
| `winLossRatio`         | `number \| null` |                                                                 |
| `largestWin`           | `number \| null` |                                                                 |
| `largestLoss`          | `number \| null` |                                                                 |
| `largestWinPct`        | `number \| null` |                                                                 |
| `largestLossPct`       | `number \| null` |                                                                 |
| `avgDurationMs`        | `number \| null` |                                                                 |
| `avgWinDurationMs`     | `number \| null` |                                                                 |
| `avgLossDurationMs`    | `number \| null` |                                                                 |
| `maxConsecutiveWins`   | `number`         |                                                                 |
| `maxConsecutiveLosses` | `number`         |                                                                 |
| `avgPerDay`            | `number \| null` | Net profit per calendar day / week the closed trades span.      |
| `avgPerWeek`           | `number \| null` |                                                                 |
| `cagr`                 | `number \| null` | Compound annual growth of this side's net profit over its span. |
| `longestMs`            | `number \| null` |                                                                 |
| `shortestMs`           | `number \| null` |                                                                 |
| `tradesPerDay`         | `number \| null` |                                                                 |
| `tradesPerWeek`        | `number \| null` |                                                                 |

### `StrategyReport` [#strategyreport]

```typescript
interface StrategyReport {
    title: string;
    initialCapital: number;
    position: { qty: number; avgPrice: number; openPnl: number };
    finalEquity: number;
    netPnl: number;
    engine?: {
        sharpe?: number;
        sortino?: number;
        buyHoldPnl?: number;
        buyHoldPct?: number;
        outperformance?: number;
    };
    maxDrawdown: number;
    maxDrawdownPct: number | null;
    maxRunup: number;
    all: SideMetrics;
    long: SideMetrics;
    short: SideMetrics;
    sharpe: number | null;
    sortino: number | null;
    cagr: number | null;
    equity: EquityPoint[];
    trades: ReportTrade[];
    distribution: Array<{ from: number; to: number; count: number; tone: 'profit' | 'loss' }>;
    daily: Array<{ day: number; pnl: number; trades: number; wins: number }>;
    weekday: number[];
    weekdayTrades: number[];
    calmar: number | null;
    firstTime: number | null;
    lastTime: number | null;
}
```

| Member           | Type                                                                                                        | Description                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `title`          | `string`                                                                                                    |                                                                                      |
| `initialCapital` | `number`                                                                                                    |                                                                                      |
| `position`       | `{ qty: number; avgPrice: number; openPnl: number }`                                                        | The open position at the last bar.                                                   |
| `finalEquity`    | `number`                                                                                                    |                                                                                      |
| `netPnl`         | `number`                                                                                                    | The engine's own net profit (commissions included even when the ledger lacks them).  |
| `engine?`        | `{ sharpe?: number; sortino?: number; buyHoldPnl?: number; buyHoldPct?: number; outperformance?: number; }` | Figures only the engine can give (they need every bar): absent when it reports none. |
| `maxDrawdown`    | `number`                                                                                                    |                                                                                      |
| `maxDrawdownPct` | `number \| null`                                                                                            |                                                                                      |
| `maxRunup`       | `number`                                                                                                    |                                                                                      |
| `all`            | `SideMetrics`                                                                                               |                                                                                      |
| `long`           | `SideMetrics`                                                                                               |                                                                                      |
| `short`          | `SideMetrics`                                                                                               |                                                                                      |
| `sharpe`         | `number \| null`                                                                                            | Calendar-month returns of the closed-trade equity, annualized.                       |
| `sortino`        | `number \| null`                                                                                            |                                                                                      |
| `cagr`           | `number \| null`                                                                                            | Compound annual growth over the first entry → last exit span.                        |
| `equity`         | `EquityPoint[]`                                                                                             |                                                                                      |
| `trades`         | `ReportTrade[]`                                                                                             |                                                                                      |
| `distribution`   | `Array<{ from: number; to: number; count: number; tone: 'profit' \| 'loss' }>`                              | Closed trades by P\&L %, in buckets.                                                 |
| `daily`          | `Array<{ day: number; pnl: number; trades: number; wins: number }>`                                         | Net P\&L, closed trades and winners by the UTC day trades closed on.                 |
| `weekday`        | `number[]`                                                                                                  | Net P\&L by weekday of the exit, Monday first.                                       |
| `weekdayTrades`  | `number[]`                                                                                                  | Closed trades by weekday of the exit, Monday first.                                  |
| `calmar`         | `number \| null`                                                                                            | Return over the largest drawdown (annual growth % / max drawdown %).                 |
| `firstTime`      | `number \| null`                                                                                            |                                                                                      |
| `lastTime`       | `number \| null`                                                                                            |                                                                                      |

See also: [`EquityPoint`](/vela-pro/api/replay-and-strategy#equitypoint), [`ReportTrade`](/vela-pro/api/replay-and-strategy#reporttrade), [`SideMetrics`](/vela-pro/api/replay-and-strategy#sidemetrics).

### `TrackedStrategy` [#trackedstrategy]

```typescript
interface TrackedStrategy {
    id: string;
    title: string;
    report: StrategyReport | null;
}
```

See also: [`StrategyReport`](/vela-pro/api/replay-and-strategy#strategyreport).

## Constants [#constants]

### `REPLAY_ACTION_ID` [#replay_action_id]

The topbar action's id.

```typescript
const REPLAY_ACTION_ID: 'vela-pro.replay';
```

### `STRATEGY_PANEL_ID` [#strategy_panel_id]

```typescript
const STRATEGY_PANEL_ID: 'vela-pro.strategy';
```
