trading-risk-engine 1.0.0

Kill-switch and risk control engine for live trading bots

🛡️ Trading Risk Engine

A Python library with kill-switch and risk controls for live trading bots.

Enforce position sizing, drawdown limits, and leverage controls — before your account pays the price.

---

📑 Quick Navigation

The Problem · Why Backtests Fail · What Is This? · Outcomes · Who Is This For? · Quick Example · Freqtrade Integration · Tests · Roadmap · License

💀 The Problem No One Talks About

Without proper risk controls, even a perfect strategy can wipe out your account.

Most trading bots don't fail because the strategy is bad.
They fail because risk is unmanaged.

• Fixed position sizing that ignores account state
• Unlimited drawdown with no emergency stop
• Correlated exposure across multiple positions
• No kill switch when things go wrong

These are the real reasons accounts go to zero — often after successful backtests.

"I backtested for 6 months, went live, and lost 40% in 2 weeks."
— Every algo trader, at some point

---

❌ Why Backtests Didn't Save You

What You Thought	What Actually Happened
"My backtest was profitable"	Lookahead bias inflated results
"I used 1% risk per trade"	Fixed sizing ignored changing equity
"I had a stop loss"	No global risk context across trades
"The strategy was tested"	No kill switch when live conditions diverged

Strategies don't kill accounts. Uncontrolled risk does.

---

🎯 What Is This?

Trading Risk Engine is a strategy-agnostic risk layer that sits between your signals and execution, enforcing hard risk limits — even when your strategy is wrong.

┌───────────────────────────────┐
│        Your Strategy          │
│  (Freqtrade / Custom Bot)     │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│     Trading Risk Engine       │  ← This Layer
│                               │
│  ✓ Can I afford this trade?   │
│  ✓ Am I overexposed?          │
│  ✓ Should I stop trading?     │
│                               │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│        Execution Layer        │
└───────────────────────────────┘

---

✅ What It Prevents (Outcomes)

Before	After
"I lost 30% before I noticed"	Never lose more than 15% per session (configurable)
"Position sizes were random"	Every trade risks exactly 1% of equity (configurable)
"One bad week wiped months of gains"	Trading stops automatically at drawdown limit
"I was over-leveraged without knowing"	Leverage is capped at 3x before orders are placed (configurable)
"I had 5 correlated positions open"	Exposure limits prevent concentration risk

This is not about making more money. It's about keeping what you have.

---

🔧 How It Works (High Level)

The engine evaluates every trade request against your defined limits:

1. Kill Switch Check — Is trading enabled, or are we in shutdown?
2. Drawdown Check — Are we within account drawdown limits?
3. Session Check — Have we lost too much today?
4. Exposure Check — Do we have room for another position?
5. Size Calculation — What's the correct position size for this stop loss?
6. Leverage Check — Would this position exceed our leverage limit?

Any failure = trade rejected. No exceptions. No overrides.

---

👤 Who Is This For?

✅ This is for:

• Algo traders running live bots
• Developers using Freqtrade, Backtrader, or custom systems
• Traders who understand: profits don't matter if risk is broken
• Anyone who has blown an account and is tired of repeating it

❌ This is NOT for:

• Signal sellers looking for marketing buzzwords
• "Guaranteed profit" seekers
• Beginners who don't understand drawdown
• People who think backtests equal live results

If you're looking for a magic profit button, look elsewhere.

---

📦 What You Get

Core Components

Component	Function
RiskConfig	Define your limits (drawdown, leverage, positions)
RiskState	Track runtime state (equity, peak, exposure)
RiskEngine	Evaluate trades: APPROVE / REJECT / SHUTDOWN

Guards (Risk Controls)

Guard	What It Does
DrawdownGuard	Triggers kill switch at max drawdown
LeverageGuard	Prevents over-leveraged positions
ExposureGuard	Limits concurrent positions

Position Sizing

Sizer	Method
FixedRiskSizer	Classic % risk per trade formula
VolatilitySizer	ATR-based sizing (coming in v1.1)

Adapters

Adapter	Integration
GenericAdapter	Plain Python usage
FreqtradeAdapter	Drop-in Freqtrade integration

---

⚡ Quick Example

from risk_engine import RiskConfig, RiskState, RiskEngine
from risk_engine.interfaces.position import TradeRequest, PositionSide

# Define your risk limits
config = RiskConfig(
    max_account_drawdown=0.15,  # 15% max drawdown → kill switch
    risk_per_trade=0.01,        # 1% risk per trade
    max_leverage=3.0,           # Max 3x leverage
    max_open_positions=3,       # Max 3 concurrent trades
)

# Initialize with current account state
state = RiskState(current_equity=10000, equity_peak=10000)
engine = RiskEngine(config, state)

# Evaluate a trade
decision = engine.evaluate_trade(TradeRequest(
    symbol="BTC/USDT",
    side=PositionSide.LONG,
    entry_price=50000,
    stop_loss=49000,
))

if decision.is_approved:
    print(f"✅ Trade approved: {decision.position_size} units")
else:
    print(f"❌ Trade rejected: {decision.reason}")

# Check kill switch status after losses
print(f"Kill switch active: {not state.trading_enabled}")

---

🔌 Freqtrade Integration

Drop-in integration with Freqtrade strategies:

from risk_engine.adapters.freqtrade import FreqtradeRiskAdapter, FreqtradeConfig

class MyStrategy(IStrategy):
    def __init__(self, config):
        super().__init__(config)
        self.risk_adapter = FreqtradeRiskAdapter(
            FreqtradeConfig(
                max_account_drawdown=0.15,
                risk_per_trade=0.01,
            )
        )
    
    def bot_start(self, **kwargs):
        self.risk_adapter.on_bot_start(self.wallets.get_total_stake_amount())
    
    def custom_stake_amount(self, pair, current_rate, proposed_stake, side, **kwargs):
        return self.risk_adapter.get_stake_amount(
            pair=pair,
            entry_price=current_rate,
            stoploss_price=current_rate * (1 - abs(self.stoploss)),
            proposed_stake=proposed_stake,
            side=side,
        )

Full example: freqtrade_example.py

---

🧪 Tested & Reliable

========================= 61 tests passed =========================

Test Suite	Coverage
Config validation	✅
Drawdown + kill switch	✅
Position sizing	✅
Leverage guards	✅
Full engine integration	✅
Fail-closed behavior	✅

The engine is tested for the scenarios that matter most:

• Losing streaks that hit drawdown limits
• Concurrent position limits
• Manual reset after shutdown
• Error handling (fail-closed)

---

📜 License

Free for personal experimentation and research.
A commercial license is required for live trading, paid services, or client deployments.

📧 Commercial licensing: Get a License

---

🗺️ Roadmap

Version	Features
v1.0 ✅	Kill switch, Fixed sizing, Leverage guard, Freqtrade adapter
v1.1	Session exposure limits, DCA caps, Volatility sizing
Pro	Correlation analysis, Regime detection

---

Remember: This engine protects capital. It doesn't make money.
That's your strategy's job — if it survives long enough to prove itself.