How CloddsBot's Volatility Regime Affects Trade Size: A Technical Deep Dive

CloddsBot dynamically scales trade sizes using four volatility regimes—low (1.2×), normal (1.0×), high (0.5×), and extreme (0.25× or halt)—with multipliers defined in src/risk/volatility.ts that the risk engine applies to every position calculation.

CloddsBot automatically adjusts capital allocation based on real-time market volatility classifications. By implementing a rolling standard-deviation and ATR detector, the open-source trading bot categorizes market conditions into distinct volatility regimes that directly determine position sizing multipliers. Understanding how CloddsBot's volatility regime affects trade size is essential for operators configuring risk parameters and developers extending the platform's capabilities.

The Four Volatility Regimes and Size Multipliers

The volatility detector classifies market states into four distinct regimes, each mapped to a specific size multiplier in the DEFAULT_CONFIG object at src/risk/volatility.ts (lines 5-9 and 28-31).

Low Volatility (1.2× Multiplier)

When markets are calm, CloddsBot adopts an aggressive stance. The low regime triggers a 1.2× size multiplier, allowing the bot to deploy positions 20% larger than calculated. This configuration encourages larger exposure during stable conditions when price movements are predictable.

Normal Volatility (1.0× Multiplier)

The normal regime represents baseline market conditions and applies a 1.0× multiplier, leaving trade sizes unchanged. This serves as the default state where the bot executes trades at their originally calculated dimensions without regime-based adjustments.

High Volatility (0.5× Multiplier)

During elevated volatility periods classified as high, the bot tightens risk exposure by applying a 0.5× multiplier, effectively halving the trade size. According to the implementation in src/risk/engine.ts (lines 74-76), when the risk engine queries the detector and receives the high volatility classification, it scales the request size to limit potential drawdowns.

Extreme Volatility (0.25× Multiplier or Trading Halt)

The extreme regime represents crisis-level market conditions. Here, the multiplier drops to 0.25× (quarter size), or if haltOnExtreme is enabled, trading ceases entirely. The detector's snapshot includes a shouldHalt flag defined at src/risk/volatility.ts (lines 47-48), which the risk engine evaluates before approving any trades.

How the Risk Engine Applies Regime Multipliers

The volatility regime directly influences position sizing through two primary pathways in src/risk/engine.ts, depending on whether Kelly criterion calculations are available.

Kelly-Based Sizing Adjustment

When a Kelly calculator is present, the bot first computes the Kelly-optimal position size, then multiplies it by the current regime's size multiplier. As implemented at lines 50-53, the adjusted size is calculated using:

const kellySize = kellyResult.positionSize * volSnapshot.sizeMultiplier;
const adjustedSize = Math.min(request.size, kellySize);

This ensures that even mathematically optimal position sizes respect current market volatility constraints.

Direct Regime Scaling

In scenarios without Kelly calculation, the risk engine applies the multiplier directly to the requested trade size (lines 74-76). If the resulting adjusted size falls below the original request, the system generates a warning message indicating the reduction reason and current regime classification (lines 81-85).

Implementing Volatility Detection in Code

To utilize the volatility detection system in the alsk1992/CloddsBot repository, developers interact with the createVolatilityDetector factory function.

Obtaining the Current Regime and Multiplier

import { createVolatilityDetector } from './risk/volatility';

// Initialize detector (uses default thresholds)
const detector = createVolatilityDetector();

// Feed recent P&L percentages
pnlHistory.forEach(pnl => detector.addObservation(pnl));

// Snapshot contains regime and multiplier
const { regime, sizeMultiplier } = detector.detect();
console.log(`Regime: ${regime}, size multiplier: ${sizeMultiplier}x`);

Handling Extreme Regime Conditions

When implementing custom risk checks, access the shouldHalt property to determine if trading should cease:

const volSnapshot = volDetector.detect();

if (volSnapshot.shouldHalt) {
  // Reject trade outright
  return { approved: false, reason: 'Extreme volatility — trading halted' };
}

// Otherwise apply the multiplier
const adjustedSize = requestedSize * volSnapshot.sizeMultiplier;

Key Configuration Files

The volatility regime system spans several critical files in the codebase:

• src/risk/volatility.ts – Implements the VolatilityDetector class, regime classification logic, and default multipliers (lines 5-9, 28-31).
• src/risk/engine.ts – Consumes detector snapshots to adjust trade sizes via Kelly-based or direct scaling (lines 50-53, 74-76, 81-85).
• src/skills/bundled/risk/index.ts – Exposes volatility snapshots to the UI dashboard for operator monitoring.
• src/risk/dashboard.ts – Renders the current regime and active multiplier on the risk management interface.

Summary

• CloddsBot classifies markets into four volatility regimes—low, normal, high, and extreme—using a rolling standard-deviation/ATR detector in src/risk/volatility.ts.
• Each regime applies a specific size multiplier: 1.2× for low volatility, 1.0× for normal, 0.5× for high, and 0.25× (or halt) for extreme conditions.
• The risk engine applies these multipliers to Kelly-calculated sizes or directly to requested trade sizes in src/risk/engine.ts.
• When haltOnExtreme is enabled, the extreme regime triggers a complete trading cessation via the shouldHalt flag.
• All adjustments generate warnings when trade sizes are reduced, providing visibility into regime-based risk management decisions.

Frequently Asked Questions

What are the four volatility regimes in CloddsBot?

CloddsBot defines four volatility regimes in src/risk/volatility.ts: low (calm markets), normal (baseline), high (elevated volatility), and extreme (crisis levels). Each regime maps to a specific size multiplier—1.2×, 1.0×, 0.5×, and 0.25× respectively—that scales trade positions accordingly.

How does the volatility regime affect position sizing?

The regime affects sizing through multipliers applied in src/risk/engine.ts. When the detector identifies a high volatility regime, the engine multiplies the calculated position size by 0.5×, effectively reducing exposure by half. Conversely, low volatility triggers a 1.2× multiplier to increase position size during stable market conditions.

Can CloddsBot halt trading during extreme volatility?

Yes. When the detector classifies conditions as extreme and haltOnExtreme is enabled in the configuration, the shouldHalt flag (lines 47-48 in src/risk/volatility.ts) triggers a complete trading halt. The risk engine checks this flag before approving any trades, rejecting requests with an "Extreme volatility — trading halted" message when active.

Where is the volatility detection logic implemented?

The core detection logic resides in src/risk/volatility.ts, which exports the createVolatilityDetector factory and VolatilityDetector class. This module calculates rolling standard deviations, classifies regimes, and provides size multipliers consumed by the risk engine in src/risk/engine.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}