skillbase/hummingbot-strategy-design

## Hummingbot Controller Selection

Hummingbot v2 uses controllers (strategy templates) and executors (execution units). Choose the right controller for the market condition:

### Market Making Controllers

**`pmm_simple`** — Pure Market Making with fixed parameters.

Best for: stable markets, starting point for any MM pair. Fixed bid/ask spread, order amount, refresh interval. Simple but effective.

**`pmm_dynamic`** — PMM with volatility-adjusted spreads.

Best for: pairs with changing volatility. Automatically widens spread when volatility increases, tightens when calm. Based on Avellaneda-Stoikov principles internally.

**`dman_maker_v2`** — Advanced market maker with NATR-based spread.

Best for: more sophisticated MM on volatile pairs. Uses Normalized Average True Range for dynamic spread calculation. Better adverse selection protection than pmm_simple.

### Generic Controllers (relevant for MM)

**`grid_strike`** — Grid trading within a price range.

Best for: range-bound markets with clear support/resistance. Places orders at fixed intervals. Profits from mean reversion.

**`arbitrage_controller`** — Cross-exchange arbitrage.

Best for: same pair on two exchanges with persistent price divergence.

**`hedge_asset`** — Hedge positions across exchanges.

Best for: reducing inventory risk from other MM strategies.

### Executor Types for Direct Trading

When you need direct execution without a controller:

- **`order_executor`** — single order (MARKET, LIMIT, LIMIT_MAKER, LIMIT_CHASER). Use LIMIT_CHASER for best execution on large orders.

- **`position_executor`** — directional trade with built-in SL/TP. Use when you have a directional thesis alongside MM.

- **`grid_executor`** — standalone grid without a controller bot.

- **`dca_executor`** — dollar-cost average into a position.

- **`lp_executor`** — CLMM LP on Meteora/Raydium. On-chain market making.

## Strategy Design Process

### Step 1: Assess the opportunity

Before designing a strategy, determine if MM is viable on this pair:

**Pull data via MCP:**

```

get_market_data(data_type="order_book", connector_name="binance", trading_pair="ETH-USDT", query_type="snapshot")

get_market_data(data_type="candles", connector_name="binance", trading_pair="ETH-USDT", interval="1h", days=7)

get_market_data(data_type="prices", connector_name="binance", trading_pairs=["ETH-USDT"])

```

**Evaluate:**

| Metric | How to get it | MM viable if |

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

| Quoted spread | order_book snapshot: best_ask - best_bid | > 2x maker fee |

| Effective spread | quoted_spread - 2 * fee | > 0 (positive = profitable) |

| Daily volume | candles sum or exchange stats | > $50K |

| Book depth at 0.5% | order_book snapshot | > 10x your order size |

| Volatility (24h) | candles: stdev of returns | < 5% daily (higher = wider spread needed) |

| Funding rate (perps) | `get_market_data(data_type="funding_rate")` | Useful signal, not a filter |

**For cross-exchange (XEMM):**

```

get_market_data(data_type="prices", connector_name="binance", trading_pairs=["ETH-USDT"])

get_market_data(data_type="prices", connector_name="kucoin", trading_pairs=["ETH-USDT"])

```

Compare: persistent divergence > combined fees on both exchanges = XEMM opportunity.

**For DEX pools:**

```

explore_geckoterminal(action="top_pools", network="solana")

explore_dex_pools(action="get_pool_info", network="solana", pool_address="...")

```

### Step 2: Choose controller and calculate parameters

**Spread calculation (Avellaneda-Stoikov simplified):**

```

minimum_spread = 2 * fee_rate + adverse_selection_cost + target_profit

Where:

  fee_rate = exchange maker fee (e.g., 0.001 for 0.1%)

  adverse_selection_cost ≈ hourly_volatility * sqrt(refresh_interval_hours)

  target_profit = your desired profit per round trip (e.g., 0.001 for 10bps)

```

For `pmm_simple`, set `bid_spread` and `ask_spread` to `minimum_spread / 2` each.

For `pmm_dynamic` and `dman_maker_v2`, the controller calculates spread from volatility — you set the risk aversion and base parameters.

**Order amount:**

```

max_order_size = book_depth_at_your_spread * 0.05   # don't exceed 5% of visible depth

position_limit = max_portfolio_risk / max_adverse_move  # e.g., $1000 risk / 0.20 move = $5000 max position

order_amount = min(max_order_size, position_limit / order_levels)

```

**Inventory management params:**

- `inventory_target_base_pct = 50` (neutral — equal base and quote)

- Enable inventory skew in all strategies — it widens spread on the overweight side

### Step 3: Create config via MCP

```

# 1. Get the schema

manage_controllers(action="describe", controller_name="pmm_simple")

# 2. Create config

manage_controllers(

  action="upsert",

  target="config",

  config_name="eth_usdt_pmm_v1",

  config_data={

    "controller_name": "pmm_simple",

    "connector_name": "binance",

    "trading_pair": "ETH-USDT",

    "bid_spread": 0.002,

    "ask_spread": 0.002,

    "order_amount": 0.1,

    "order_levels": 3,

    "order_refresh_time": 15,

    "inventory_skew_enabled": true,

    "inventory_target_base_pct": 50

  }

)

```

Always describe the controller first to get the exact schema — field names and valid ranges differ between controllers.

### Step 4: Document rationale

Every config should have a rationale that maps each parameter to the market condition that determined it:

```

## Config: eth_usdt_pmm_v1

Pair: ETH-USDT on Binance

Controller: pmm_simple

Date: YYYY-MM-DD

### Parameters

| Param | Value | Rationale |

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

| bid_spread | 0.2% | fee=0.1% + adverse_selection=0.05% + profit=0.05% |

| ask_spread | 0.2% | symmetric |

| order_amount | 0.1 ETH | ~$300, <5% of book depth at spread |

| order_levels | 3 | captures depth without excessive inventory |

| inventory_skew | enabled | prevent one-sided accumulation |

### Kill conditions

- Volatility > 8% daily: pause (spread can't compensate)

- Spread compresses below 0.15%: reduce order_amount or pause

- Inventory > 70% one side for > 2h: review

- Total P&L < -$200: stop and investigate

### Review schedule

- Daily: check fill rate, inventory balance, P&L

- Weekly: recalculate spread from updated volatility data

```

## Market Making Theory

### Avellaneda-Stoikov Framework

The model that modern MM strategies (including pmm_dynamic) build on:

**Reservation price** — where you WANT the mid-price given your inventory:

```

r = s - q * γ * σ² * (T - t)

```

- `s` = market mid-price

- `q` = inventory (positive = long, negative = short)

- `γ` = risk aversion (higher = faster inventory reversion)

- `σ` = volatility

- `T - t` = remaining time horizon

When you're long (q > 0), reservation price drops below mid → you want to sell. This is what inventory skew does mechanically.

**Optimal spread:**

```

δ = γ * σ² * (T - t) + (2/γ) * ln(1 + γ/k)

```

- `k` = order arrival intensity (how often orders hit your level)

- Higher volatility → wider spread (more adverse selection risk)

- Higher arrival rate → tighter spread (more fills compensate per-trade risk)

### Inventory Risk

The #1 risk in market making. You profit from spread but risk from price moves on accumulated inventory.

**Decompose P&L always:**

- **Spread P&L** = round_trips * effective_spread * order_size (should be positive)

- **Inventory P&L** = position * (current_price - avg_entry) (can be large and negative)

- **Fees** = total maker + taker fees paid

If |inventory P&L| consistently > spread P&L, the strategy is net speculating. Review immediately.

### When NOT to Market Make

- **Strong trend**: MM accumulates inventory against the trend. If 1h candles show 5+ consecutive same-direction closes, pause.

- **Volatility spike**: a 3x increase in hourly volatility means your spread is too tight. The adverse selection cost exceeds your spread.

- **Thin liquidity event**: if depth drops below 5x your order size, your orders become a significant part of the book — you ARE the market, not making it.

- **Pre-announcement**: known events (FOMC, token unlock, protocol upgrade) cause jumps that bypass any spread.