skillbase/hummingbot-risk-management

## Risk Controls in Hummingbot

Hummingbot has built-in risk controls. Use them — they are the automated last line of defense.

### Deploy-time limits (via `manage_bots`)

```

manage_bots(

  action="deploy",

  bot_name="...",

  controllers_config=["..."],

  max_global_drawdown_quote=500,          # stop ALL controllers if total loss > $500

  max_controller_drawdown_quote=200       # stop individual controller if its loss > $200

)

```

**How to size these limits:**

- `max_global_drawdown_quote` = maximum acceptable loss for this bot instance. Typically 5-10% of capital deployed to this bot.

- `max_controller_drawdown_quote` = per-strategy limit. Typically 2-5% of capital allocated to that strategy.

These are hard stops — when hit, Hummingbot automatically stops the affected controllers. This is non-negotiable: every bot deploys with both limits set.

### Strategy-level inventory controls

In controller configs (via `manage_controllers`):

- `inventory_skew_enabled` — widens spread on overweight side. Always enable.

- `inventory_target_base_pct` — target balance (50% = neutral)

- Order levels and amounts — implicitly limit max position

## P&L Attribution

Market making P&L must be decomposed to understand if the strategy actually works:

### Spread P&L (the intended profit)

```

spread_pnl = number_of_round_trips × effective_spread × avg_order_size

```

This should be consistently positive. If not, spreads are too tight or adverse selection is too high.

**How to calculate from MCP data:**

```

search_history(data_type="orders", status="filled", start_time=..., end_time=...)

```

Match buy fills with sell fills chronologically. Sum: (sell_price - buy_price) for matched pairs.

### Inventory P&L (the risk)

```

inventory_pnl = current_position × (current_price - avg_entry_price)

```

**How to calculate:**

```

get_portfolio_overview(include_balances=True)  → current position

get_market_data(data_type="prices", ...)       → current price

search_history(data_type="orders", ...)        → reconstruct avg entry from fills

```

### Fee drag

```

total_fees = sum of all trading fees from order history

```

Include in every P&L analysis. High-frequency MM strategies can accumulate significant fee costs.

### The critical check

```

If |inventory_pnl| > spread_pnl consistently (over 3+ days):

  → The strategy is speculating, not market making

  → Action: stop, review parameters, reduce position size

```

## Exposure Monitoring

### Portfolio snapshot

```

get_portfolio_overview(

  include_balances=True,

  include_perp_positions=True,

  include_active_orders=True,

  as_distribution=True          # see concentration %

)

```

### What to check

**Per-pair concentration:**

Any single pair > 30% of total deployed capital → over-concentrated. Reduce or diversify.

**Per-exchange concentration:**

Any single exchange > 40% of total capital → counterparty risk too high.

| Exchange tier | Max allocation |

|---|---|

| Top 5 by volume, regulated | Up to 40% |

| Top 20, established | Up to 25% |

| Smaller / less transparent | Up to 10% |

| DEX (non-custodial) | Based on smart contract audit status |

**Inventory balance per pair:**

```

get_portfolio_overview(include_balances=True)

```

Check base/quote ratio for each active pair. >70% one side for >1 hour = alert.

**Correlation risk:**

If running MM on ETH-USDT, SOL-USDT, and AVAX-USDT — these are all correlated with BTC. A 20% BTC drop affects ALL positions simultaneously. Treat correlated positions as one block for risk sizing.

## Stress Testing (before approving new strategy)

Calculate the impact of adverse scenarios using current portfolio data:

### Scenario 1: Flash crash (-30% in 1 hour)

```

max_loss = sum(position_size × 0.30) for all positions

```

Compare to total portfolio. If max_loss > 10% of total → reduce position sizes.

### Scenario 2: Exchange downtime (4 hours)

Orders sit on the book, market moves. Worst case: all orders on one side fill, market moves 10% against you.

```

exposure = sum(all_active_order_amounts)

max_loss = exposure × 0.10

```

### Scenario 3: Correlation shock

All crypto positions move together. Calculate total directional exposure:

```

net_exposure = sum(long_positions) - sum(short_positions)

max_loss_at_20pct = net_exposure × 0.20

```

### Scenario 4: Fee structure change

If maker fee doubles (exchange changes tiers), recalculate effective spread for all active strategies. Any that become negative effective spread → must stop.

## Risk Report Template

Produce periodically using MCP data:

```

## Risk Report: [Date]

### Data Sources

- Portfolio: get_portfolio_overview() at [timestamp]

- Recent orders: search_history(data_type="orders", last 24h)

### Portfolio Overview

| Metric | Value |

|--------|-------|

| Total deployed | $X |

| Net P&L (24h) | +/-$X |

|   Spread P&L | +$X |

|   Inventory P&L | +/-$X |

|   Fees | -$X |

| Drawdown from peak | X% |

### Exposure

| Exchange | Pair | Position | Exposure $ | % of total |

|----------|------|----------|------------|------------|

### Alerts

| Condition | Status | Action needed |

|-----------|--------|---------------|

### Stress Test

| Scenario | Max loss | % of portfolio |

|----------|----------|---------------|

### Recommendations

- [Specific actions]

```

## Incident Analysis

After any loss event or circuit breaker trigger:

1. **Timeline**: `manage_bots(action="logs", ...)` + `search_history(data_type="orders", start_time=..., end_time=...)`

2. **Decompose**: was the loss from inventory (market move) or from spread (adverse selection)?

3. **Root cause**: strategy flaw, parameter issue, market regime change, or operational failure?

4. **Action**: parameter adjustment, strategy redesign, or resume with no changes?

Do not restart until the analysis is complete and documented.