Interface PartialLossContract

Contract for partial loss level events.

Emitted by partialLossSubject when a signal reaches a loss level milestone (-10%, -20%, -30%, etc). Used for tracking partial stop-loss execution and monitoring strategy drawdown.

Events are emitted only once per level per signal (Set-based deduplication in ClientPartial). Multiple levels can be emitted in a single tick if price drops significantly.

Consumers:

  • PartialMarkdownService: Accumulates events for report generation
  • User callbacks via listenPartialLoss() / listenPartialLossOnce()

Example

import { listenPartialLoss } from "backtest-kit";

// Listen to all partial loss events
listenPartialLoss((event) => {
  console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} reached -${event.level}% loss`);
  console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
  console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);

  // Alert on significant loss
  if (event.level >= 30 && !event.backtest) {
    console.warn("HIGH LOSS ALERT:", event.data.id);
  }
});

// Wait for first 20% loss level
listenPartialLossOnce(
  (event) => event.level === 20,
  (event) => console.log("20% loss reached:", event.data.id)
);
interface PartialLossContract {
    backtest: boolean;
    currentPrice: number;
    data: IPublicSignalRow;
    exchangeName: string;
    frameName: string;
    level: PartialLevel;
    strategyName: string;
    symbol: string;
    timestamp: number;
}

Properties

backtest currentPrice data exchangeName frameName level strategyName symbol timestamp

Properties

backtest

backtest: boolean

Execution mode flag.

  • true: Event from backtest execution (historical candle data)
  • false: Event from live trading (real-time tick)

currentPrice

currentPrice: number

Current market price at which this loss level was reached. Used to calculate actual loss percentage.

data

data: IPublicSignalRow

Complete signal row data with original prices. Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and totalExecuted.

exchangeName

exchangeName: string

Exchange name where this signal is being executed. Identifies which exchange this loss event belongs to.

frameName

frameName: string

Frame name where this signal is being executed. Identifies which frame this loss event belongs to (empty string for live mode).

level

level: PartialLevel

Loss level milestone reached (10, 20, 30, 40, 50, 60, 70, 80, 90, or 100). Represents percentage loss relative to entry price (absolute value).

Note: Stored as positive number, but represents negative loss. level=20 means -20% loss from entry price.

Example

// If entry was $50000 and level is 20:
// currentPrice <= $40000 (-20% loss)
// Level is stored as 20, not -20

strategyName

strategyName: string

Strategy name that generated this signal. Identifies which strategy execution this loss event belongs to.

symbol

symbol: string

Trading pair symbol (e.g., "BTCUSDT"). Identifies which market this loss event belongs to.

timestamp

timestamp: number

Event timestamp in milliseconds since Unix epoch.

Timing semantics:

  • Live mode: when.getTime() at the moment loss level was detected
  • Backtest mode: candle.timestamp of the candle that triggered the level

Example

const eventDate = new Date(event.timestamp);
console.log(`Loss reached at: ${eventDate.toISOString()}`);

// Calculate time in loss
const entryTime = event.data.pendingAt;
const timeInLoss = event.timestamp - entryTime;
console.log(`In loss for ${timeInLoss / 1000 / 60} minutes`);

Settings

Member Visibility

On This Page

Properties