Risk Management

This guide explains the risk management system in backtest-kit, which provides portfolio-level validation and position tracking to prevent excessive risk exposure.

What is Risk Management?

Risk management in backtest-kit is a validation system that checks signals before they are created, analyzing the state of the entire portfolio. Unlike signal validation (which checks individual parameters), risk management considers all active positions across all strategies.

Key Features

✅ Portfolio-level position limits
✅ Multi-strategy position coordination
✅ Custom validation rules with notes
✅ Symbol filtering
✅ Trading time windows
✅ Active position inspection
✅ Crash-safe position tracking
✅ Events for rejected signals

Risk Management Architecture

Mermaid Diagram

Execution Flow

Strategy calls getSignal() to generate a new signal
ClientRisk.checkSignal() evaluates the signal against risk rules
Each validation function receives IRiskValidationPayload with portfolio state
If any validation throws an error, the signal is rejected (not created)
Rejection generates an event in riskSubject with the reason
If all validations pass, the signal is created and position tracking is updated

Registering a Risk Profile

Risk profiles are registered via the addRisk() function:

import { addRisk } from "backtest-kit";

addRisk({
  riskName: "conservative",          // Unique identifier
  note: "Conservative profile",      // Optional documentation
  validations: [                      // Array of validation rules
    // Validation rules here
  ],
  callbacks: {                        // Optional callbacks
    onRejected: (symbol, params) => {
      console.warn(`Signal rejected: ${symbol}`);
    },
    onAllowed: (symbol, params) => {
      console.log(`Signal allowed: ${symbol}`);
    },
  },
});

Risk Schema Structure

Field	Type	Description
`riskName`	`string`	Unique profile identifier
`note`	`string?`	Optional documentation
`validations`	`Array`	Array of validation rules
`callbacks`	`object?`	Optional event callbacks

Risk Validation Payload

Each validation function receives an IRiskValidationPayload object with full portfolio context:

Field	Type	Description
`symbol`	`string`	Trading pair (e.g., "BTCUSDT")
`pendingSignal`	`ISignalDto`	Signal to validate
`strategyName`	`string`	Strategy requesting the signal
`exchangeName`	`string`	Exchange name
`currentPrice`	`number`	Current VWAP price
`timestamp`	`number`	Current timestamp (ms)
`activePositionCount`	`number`	Total active positions across all strategies
`activePositions`	`Array`	Detailed list of active positions

Active Position Structure

interface IRiskActivePosition {
  signal: ISignalRow;        // Full signal data
  strategyName: string;      // Owner strategy
  exchangeName: string;      // Exchange name
  openTimestamp: number;     // When position opened (ms)
}

Validation Rule Examples

Example 1: Concurrent Position Limit

addRisk({
  riskName: "max-3-positions",
  note: "Maximum 3 concurrent positions",
  validations: [
    ({ activePositionCount }) => {
      if (activePositionCount >= 3) {
        throw new Error("Maximum 3 concurrent positions reached");
      }
    }
  ]
});

When to use: To limit the total number of open positions and manage capital exposure.

Example 2: Symbol Filtering

addRisk({
  riskName: "no-meme-coins",
  note: "Block meme coins from trading",
  validations: [
    ({ symbol }) => {
      const memeCoins = ["DOGEUSDT", "SHIBUSDT", "PEPEUSDT"];
      if (memeCoins.includes(symbol)) {
        throw new Error(`Meme coin ${symbol} not allowed`);
      }
    }
  ]
});

When to use: To exclude specific instruments from trading.

Example 3: Trading Time Windows

addRisk({
  riskName: "trading-hours",
  note: "Trade only during business hours (9:00 - 17:00 UTC)",
  validations: [
    ({ timestamp }) => {
      const date = new Date(timestamp);
      const hour = date.getUTCHours();

      if (hour < 9 || hour >= 17) {
        throw new Error("Trading allowed only 9:00 - 17:00 UTC");
      }

      // Check day of week (no weekend trading)
      const day = date.getUTCDay();
      if (day === 0 || day === 6) {
        throw new Error("Weekend trading not allowed");
      }
    }
  ]
});

When to use: To restrict trading to specific time periods.

Example 4: Multi-Strategy Coordination

addRisk({
  riskName: "multi-strategy-coordinator",
  note: "Limit per-strategy exposure and check for active positions",
  validations: [
    ({ activePositions, strategyName, symbol }) => {
      // Count positions for specific strategy
      const strategyPositions = activePositions.filter(
        (pos) => pos.strategyName === strategyName
      );

      if (strategyPositions.length >= 2) {
        throw new Error(`Strategy ${strategyName} already has 2 positions`);
      }

      // Check for existing position on this symbol
      const symbolPositions = activePositions.filter(
        (pos) => pos.signal.symbol === symbol
      );

      if (symbolPositions.length > 0) {
        const existingStrategy = symbolPositions[0].strategyName;
        throw new Error(`Position on ${symbol} already open by ${existingStrategy}`);
      }
    }
  ]
});

When to use: To manage multiple strategies and prevent duplicate positions.

Example 5: TP/SL Distance Validation

addRisk({
  riskName: "tp-sl-distance",
  note: "Minimum TP distance and risk/reward ratio",
  validations: [
    {
      validate: ({ pendingSignal, currentPrice }) => {
        const { priceOpen = currentPrice, priceTakeProfit, position } = pendingSignal;
        const tpDistance = position === "long"
          ? ((priceTakeProfit - priceOpen) / priceOpen) * 100
          : ((priceOpen - priceTakeProfit) / priceOpen) * 100;

        if (tpDistance < 1) {
          throw new Error(`TP distance ${tpDistance.toFixed(2)}% < 1%`);
        }
      },
      note: "TP distance must be at least 1%"
    },
    {
      validate: ({ pendingSignal, currentPrice }) => {
        const { priceOpen = currentPrice, priceTakeProfit, priceStopLoss, position } = pendingSignal;

        const reward = position === "long"
          ? priceTakeProfit - priceOpen
          : priceOpen - priceTakeProfit;

        const risk = position === "long"
          ? priceOpen - priceStopLoss
          : priceStopLoss - priceOpen;

        if (risk <= 0) {
          throw new Error("Invalid SL: risk must be positive");
        }

        const rrRatio = reward / risk;
        if (rrRatio < 2) {
          throw new Error(`R/R ratio ${rrRatio.toFixed(2)} < 2:1`);
        }
      },
      note: "Risk/reward ratio must be at least 1:2"
    }
  ]
});

When to use: To ensure adequate profit potential relative to risk.

Example 6: Maximum Risk Per Trade

addRisk({
  riskName: "max-risk-per-trade",
  note: "Maximum 2% risk per trade",
  validations: [
    ({ pendingSignal, currentPrice }) => {
      const { priceOpen = currentPrice, priceStopLoss, position } = pendingSignal;

      const slDistance = position === "long"
        ? ((priceOpen - priceStopLoss) / priceOpen) * 100
        : ((priceStopLoss - priceOpen) / priceOpen) * 100;

      if (slDistance > 2) {
        throw new Error(`SL distance ${slDistance.toFixed(2)}% > 2% max risk`);
      }
    }
  ]
});

When to use: To limit the maximum loss on a single trade.

Linking Risk Profile to Strategy

After registering a risk profile, link it to a strategy:

import { addStrategy, addRisk } from "backtest-kit";

// Register risk profile
addRisk({
  riskName: "conservative",
  validations: [
    ({ activePositionCount }) => {
      if (activePositionCount >= 3) {
        throw new Error("Maximum 3 positions");
      }
    }
  ]
});

// Link to strategy
addStrategy({
  strategyName: "macd-crossover",
  interval: "15m",
  riskName: "conservative",  // ← Link to risk profile
  getSignal: async (symbol) => {
    // Strategy logic
  },
});

Monitoring Risk Events

Rejection Event Listener

import { listenRisk } from "backtest-kit";

listenRisk((event) => {
  console.log("=== Signal Rejected ===");
  console.log(`Symbol: ${event.symbol}`);
  console.log(`Strategy: ${event.strategyName}`);
  console.log(`Reason: ${event.comment}`);
  console.log(`Active Positions: ${event.activePositionCount}`);
  console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);

  // Send notification
  sendAlert(`Signal rejected: ${event.comment}`);
});

Risk Event Structure

interface RiskContract {
  symbol: string;              // Trading pair
  strategyName: string;        // Strategy name
  exchangeName: string;        // Exchange name
  activePositionCount: number; // Active position count
  comment: string;             // Rejection reason
  timestamp: number;           // Timestamp (ms)
  pendingSignal: ISignalDto;   // Rejected signal
}

Using Callbacks

addRisk({
  riskName: "monitored-risk",
  validations: [
    ({ activePositionCount }) => {
      if (activePositionCount >= 5) {
        throw new Error("Maximum 5 positions reached");
      }
    }
  ],
  callbacks: {
    onRejected: (symbol, params) => {
      console.warn(`⚠️ Signal rejected for ${symbol}`);
      console.warn(`   Reason: ${params.comment}`);
      console.warn(`   Active positions: ${params.activePositionCount}`);

      // Log to database
      logRiskRejection({
        symbol,
        strategy: params.strategyName,
        reason: params.comment,
        timestamp: params.timestamp,
      });
    },
    onAllowed: (symbol, params) => {
      console.log(`✓ Signal allowed for ${symbol}`);
      console.log(`   Strategy: ${params.strategyName}`);
      console.log(`   Active positions after: ${params.activePositionCount + 1}`);
    },
  },
});

Risk Check Flow Diagram