Risk - Complete API Reference

Full risk management engine: circuit breakers, loss limits, Value-at-Risk, volatility regime detection, stress testing, and kill switches.

---

Chat Commands

View Risk Status

/risk                               Current risk status
/risk status                        Detailed status with portfolio metrics
/risk limits                        View all limits
/risk dashboard                     Real-time risk metrics (VaR, regime, HHI, etc.)

Risk Analytics

/risk var                           Value-at-Risk and CVaR numbers
/risk regime                        Current volatility regime and size multiplier
/risk stress [scenario]             Run stress test (flash_crash, black_swan, etc.)

Available stress scenarios: flash_crash, liquidity_crunch, platform_down, correlation_spike, black_swan

Configure Limits

/risk set max-loss 1000             Max daily loss ($)
/risk set max-loss-pct 10           Max daily loss (%)
/risk set max-drawdown 20           Max drawdown (%)
/risk set max-position 25           Max single position (%)
/risk set max-trades 50             Max trades per day
/risk set consecutive-losses 5      Stop after N losses

Circuit Breaker

/risk trip "manual stop"            Manually trip breaker
/risk reset                         Reset after cooldown
/risk kill                          Emergency stop all trading
/risk check 500                     Check if a $500 trade is allowed

---

TypeScript API Reference

Unified Risk Engine

The risk engine is the single entry point for all pre-trade validation. It orchestrates 10 checks in order:

1. Kill switch (SafetyManager)
2. Circuit breaker (execution-level)
3. Max order size
4. Exposure limits
5. Daily loss limit
6. Max drawdown
7. Position concentration
8. VaR limit
9. Volatility regime
10. Kelly sizing recommendation

import { createRiskEngine } from 'clodds/risk';

const engine = createRiskEngine(
  {
    varLimit: 500,           // Reject trades if portfolio VaR > $500
    varConfidence: 0.95,
    varWindowSize: 100,
    volatilityConfig: {
      lookbackWindow: 30,
      haltOnExtreme: true,   // Stop trading in extreme volatility
    },
  },
  {
    riskContext,              // From trading/risk.ts
    safetyManager,           // From trading/safety.ts
    circuitBreaker,          // From execution/circuit-breaker.ts
    kellyCalculator,         // From trading/kelly.ts
    getPositions: () => positions,
    getPositionValues: () => positions.map(p => p.value),
  }
);

Validate a Trade

const decision = engine.validateTrade({
  userId: 'user-123',
  platform: 'polymarket',
  marketId: 'market-456',
  outcome: 'YES',
  side: 'buy',
  size: 500,
  price: 0.65,
  estimatedEdge: 0.05,    // 5% edge
  confidence: 0.8,
  category: 'politics',
});

if (decision.approved) {
  // Use adjustedSize — may be smaller than requested (Kelly + regime)
  await executeTrade(decision.adjustedSize);
  console.log(`Regime: ${decision.regime}`);
  console.log(`Warnings: ${decision.warnings}`);
} else {
  console.log(`Blocked: ${decision.reason}`);
  // Check which step failed:
  for (const check of decision.checks) {
    console.log(`  ${check.name}: ${check.passed ? 'PASS' : 'FAIL'} — ${check.message}`);
  }
}

Record Trade P&L (feeds VaR + volatility)

engine.recordPnL({
  pnlUsd: -45.20,
  pnlPct: -0.09,
  positionId: 'polymarket:market-456:YES',
  timestamp: new Date(),
});

Portfolio Risk Snapshot

const risk = engine.getPortfolioRisk();
console.log(`Total value: $${risk.totalValue}`);
console.log(`VaR (95%): $${risk.var95}`);
console.log(`VaR (99%): $${risk.var99}`);
console.log(`CVaR (95%): $${risk.cvar95}`);
console.log(`Regime: ${risk.regime}`);
console.log(`Drawdown: ${risk.drawdownPct}%`);

Value-at-Risk

import { createVaRCalculator, calculateVaR, calculateCVaR } from 'clodds/risk';

// Full calculator with rolling window
const calc = createVaRCalculator({ windowSize: 100, confidenceLevel: 0.95 });
calc.addObservation({ pnlUsd: -50, pnlPct: -0.05, timestamp: new Date() });
const result = calc.calculateAt(0.99);
console.log(`VaR (99%): $${result.historicalVaR}`);
console.log(`CVaR (99%): $${result.cvar}`);

// Quick one-liners
const var95 = calculateVaR(pnlArray, 0.95);
const cvar95 = calculateCVaR(pnlArray, 0.95);

Volatility Regime Detection

import { createVolatilityDetector, detectRegime } from 'clodds/risk';

const detector = createVolatilityDetector({
  lookbackWindow: 30,
  haltOnExtreme: false,
  regimeMultipliers: { low: 1.2, normal: 1.0, high: 0.5, extreme: 0.25 },
});

detector.addObservation(0.03);  // 3% P&L
const snapshot = detector.detect();
console.log(`Regime: ${snapshot.regime}`);          // 'low' | 'normal' | 'high' | 'extreme'
console.log(`Size multiplier: ${snapshot.sizeMultiplier}x`);
console.log(`Should halt: ${snapshot.shouldHalt}`);

// One-shot from array
const regime = detectRegime(recentPnLPcts);

Stress Testing

import { runStressTest, runAllScenarios, getAvailableScenarios } from 'clodds/risk';

const result = runStressTest(positions, 'flash_crash');
console.log(`Estimated loss: $${result.estimatedLoss} (${result.estimatedLossPct}%)`);
console.log(`Severity: ${result.severity}`);
console.log(`Recommendations: ${result.recommendations.join(', ')}`);

// Run all scenarios at once
const all = runAllScenarios(positions);  // sorted by severity

// Override scenario parameters
const custom = runStressTest(positions, 'flash_crash', {
  scenarios: { flash_crash: { lossPct: 30, description: 'Severe crash' } },
});

Risk Dashboard

import { getRiskDashboard } from 'clodds/risk';

const dashboard = engine.getDashboard();
console.log(`VaR (95%): $${dashboard.portfolioVaR95}`);
console.log(`Regime: ${dashboard.regime} (${dashboard.regimeSizeMultiplier}x)`);
console.log(`Daily P&L: $${dashboard.dailyPnL} / $${dashboard.dailyLossLimit}`);
console.log(`Drawdown: ${dashboard.currentDrawdown}% / ${dashboard.maxDrawdown}%`);
console.log(`Concentration HHI: ${dashboard.concentrationHHI}`);
console.log(`Kill switch: ${dashboard.killSwitchActive}`);
console.log(`Warnings: ${dashboard.warnings}`);

Circuit Breaker (Standalone)

import { createCircuitBreaker, MODERATE_CONFIG } from 'clodds/risk';

// Feature-engineering circuit breaker (market-condition-aware)
const breaker = createCircuitBreaker(MODERATE_CONFIG);
breaker.startMonitoring();

if (!breaker.canTrade('polymarket', marketId)) {
  return; // Trading halted
}

breaker.recordTrade({ success: true, pnl: 2.5 });

Kill Switch

// Emergency stop via SafetyManager — no auto-resume
safetyManager.killSwitch('Market anomaly detected');

// Resume manually after review
safetyManager.resumeTrading();

---

Risk Engine Checks

#	Check	Module	Blocks Trade?
1	Kill switch	SafetyManager	Yes
2	Circuit breaker	CircuitBreaker	Yes
3	Max order size	trading/risk	Yes
4	Exposure limits	trading/risk	Yes
5	Daily loss limit	SafetyManager	Yes
6	Max drawdown	SafetyManager	Yes
7	Concentration	SafetyManager	Yes
8	VaR limit	VaRCalculator	Yes (if configured)
9	Volatility regime	VolatilityDetector	Yes (if extreme + halt)
10	Kelly sizing	DynamicKelly	No (adjusts size)

Circuit Breaker Triggers

Trigger	Default	Description
Daily loss (USD)	$1,000	Absolute loss limit
Daily loss (%)	10%	Percentage of capital
Drawdown	20%	Peak-to-trough
Consecutive losses	5	Losses in a row
Error rate	50%	Failed order rate
Max trades	50	Trades per day

Volatility Regimes

Regime	Size Multiplier	Description
low	1.2x	Calm markets, slightly larger positions
normal	1.0x	Baseline conditions
high	0.5x	Elevated volatility, half size
extreme	0.25x	Crisis — quarter size or halt trading

Stress Test Scenarios

Scenario	Loss	Description
flash_crash	20%	All positions lose value instantly
liquidity_crunch	10%	Slippage doubles, partial fills
platform_down	15%	Primary platform offline
correlation_spike	25%	All positions move together
black_swan	40%	3-sigma tail event

Status Levels

Status	Description
armed	Normal, trading allowed
warning	Approaching limits (80%)
tripped	Limit exceeded, trading stopped
killed	Emergency stop, manual reset required

---

Recovery Process

1. Auto-reset: Next day at midnight (daily counters)
2. Cooldown: Circuit breaker auto-resets after cooldown period
3. Manual reset: /risk reset to re-arm
4. Kill recovery: /risk reset after manual review (no auto-resume)

---

Best Practices

1. Start conservative — Lower limits while learning
2. Don't override — Respect the circuit breaker
3. Review trips — Understand why limits were hit
4. Monitor VaR — Use /risk var and /risk dashboard regularly
5. Run stress tests — Use /risk stress before large position changes
6. Watch regime — Use /risk regime to understand current volatility
7. Adjust limits — Based on strategy performance and regime