Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hummingbot/hummingbot/llms.txt

Use this file to discover all available pages before exploring further.

Overview

Perpetual Market Making applies market making strategies to perpetual futures markets, allowing traders to use leverage while providing liquidity. This strategy extends pure market making concepts to derivatives markets with position management and profit-taking features.

How It Works

  1. Place Leveraged Orders: Creates bid and ask orders on perpetual markets
  2. Monitor Positions: Tracks long and short positions separately
  3. Profit Taking: Automatically places opposite orders to reduce positions
  4. Stop Loss: Protects against adverse price movements
  5. Refresh Orders: Updates orders based on market conditions
# Position-aware order placement
if position_mode == "One-way":
    net_position = long_position - short_position
    adjust_orders_for_position(net_position)
else:  # Hedge mode
    manage_long_and_short_separately()

When to Use

Best For

  • Perpetual futures markets with funding rates
  • Leveraged liquidity provision
  • Traders comfortable with derivatives
  • Markets with position-based incentives

Avoid When

  • Unfamiliar with leverage mechanics
  • Exchange has high funding rates
  • Extremely volatile markets
  • Insufficient collateral for liquidation risk

Core Configuration Parameters

Derivative Setup

derivative
string
required
The derivative exchange connectorExamples: binance_perpetual, bybit_perpetual, dydx_perpetual
market
string
required
Perpetual trading pair in BASE-QUOTE formatExample: BTC-USDT (for BTC-USDT perpetual contract)
leverage
int
required
Leverage multiplier for positionsExample: 10 for 10x leverageRange: Varies by exchange (Binance supports up to 75x for most pairs)
Higher leverage increases liquidation risk. Start with 2-5x leverage.
position_mode
string
default:"One-way"
Position management modeOptions:
  • One-way: Net position (long and short offset each other)
  • Hedge: Separate long and short positions
Hedge mode allows simultaneous long and short positions, useful for complex strategies.

Spread Configuration

bid_spread
decimal
required
Distance from mid-price for bid orders. Enter 1 for 1%.Example: 0.1 places bids 0.1% below mid-price
ask_spread
decimal
required
Distance from mid-price for ask orders. Enter 1 for 1%.Example: 0.1 places asks 0.1% above mid-price
minimum_spread
decimal
default:"-100"
Minimum spread before automatically canceling orders. Enter 1 for 1%.Range: -100% to 100%Example: 0.05 cancels orders if spread drops below 0.05%

Order Management

order_amount
decimal
required
Order size in base asset (contracts)Example: 0.01 for 0.01 BTC worth of contractsWith leverage, actual exposure = order_amount * leverage
order_refresh_time
float
required
Frequency in seconds to refresh ordersExample: 30.0 refreshes every 30 seconds
order_refresh_tolerance_pct
decimal
default:"0"
Minimum price change to trigger refresh. Enter 1 for 1%.Range: -10% to 10%

Multi-Level Orders

order_levels
int
default:"1"
Number of orders per sideExample: 3 creates 3 buy and 3 sell orders
order_level_spread
decimal
default:"1.0"
Spread increment between levels. Enter 1 for 1%.Required if order_levels > 1
order_level_amount
decimal
default:"0"
Amount increase/decrease per levelExample: 0.005 increases each level by 0.005 BTC

Profit Taking

long_profit_taking_spread
decimal
default:"0"
Spread from long position entry price to place profit-taking sell orders. Enter 1 for 1%.Example: 2.0 places sell order 2% above long entry priceRange: 0% to 100%
short_profit_taking_spread
decimal
default:"0"
Spread from short position entry price to place profit-taking buy orders. Enter 1 for 1%.Example: 2.0 places buy order 2% below short entry priceRange: 0% to 100%

Stop Loss

stop_loss_spread
decimal
default:"0"
Spread from entry price to place stop loss orders. Enter 1 for 1%.Example: 5.0 places stop loss 5% away from entryRange: 0% to 101%
Stop loss triggers market orders in the opposite direction to close positions.
time_between_stop_loss_orders
float
default:"60"
Seconds before refreshing unfilled stop loss ordersExample: 120 refreshes stop loss every 2 minutes if not executed
stop_loss_slippage_buffer
decimal
default:"0.5"
Additional slippage buffer for stop loss orders. Enter 1 for 1%.Ensures stop loss orders execute even in volatile conditions.

Price Sources

price_source
string
default:"current_market"
Price reference for order placementOptions:
  • current_market: Use current derivative mid-price
  • external_market: Use another exchange’s price
  • custom_api: Use custom API endpoint
price_type
string
default:"mid_price"
Type of price to useOptions:
  • mid_price: Average of best bid and ask
  • last_price: Last traded price
  • last_own_trade_price: Your last trade price
  • best_bid: Top bid price
  • best_ask: Top ask price
price_source_derivative
string
External exchange/derivative for price referenceRequired when price_source=external_market
price_source_market
string
Trading pair on external source

Advanced Features

price_ceiling
decimal
default:"-1"
Price above which only sell orders are placed. Use -1 to disable.
price_floor
decimal
default:"-1"
Price below which only buy orders are placed. Use -1 to disable.
order_optimization_enabled
bool
default:"false"
Enable best bid/ask jumping (order book top positioning)
filled_order_delay
float
default:"60"
Delay in seconds after order fill before placing new orders

Example Configurations

Conservative Market Making

strategy: perpetual_market_making
derivative: binance_perpetual
market: ETH-USDT
leverage: 3
position_mode: One-way
bid_spread: 0.1
ask_spread: 0.1
order_amount: 0.1
order_refresh_time: 30.0
long_profit_taking_spread: 1.0
short_profit_taking_spread: 1.0
stop_loss_spread: 3.0
stop_loss_slippage_buffer: 0.5
Features:
  • Moderate 3x leverage
  • Conservative spreads (0.1%)
  • Profit taking at 1%
  • Stop loss at 3%
  • One-way position mode

Aggressive Multi-Level

strategy: perpetual_market_making
derivative: bybit_perpetual
market: BTC-USDT
leverage: 10
position_mode: Hedge
bid_spread: 0.05
ask_spread: 0.05
order_amount: 0.01
order_levels: 5
order_level_spread: 0.05
order_level_amount: 0.005
order_refresh_time: 15.0
long_profit_taking_spread: 0.5
short_profit_taking_spread: 0.5
stop_loss_spread: 2.0
order_optimization_enabled: true
Optimized for:
  • High 10x leverage
  • Tight spreads (0.05%)
  • 5 order levels
  • Hedge mode for complex positions
  • Quick profit taking (0.5%)
  • Order optimization enabled

Price Source from Spot

strategy: perpetual_market_making
derivative: binance_perpetual
market: SOL-USDT
leverage: 5
position_mode: One-way
bid_spread: 0.2
ask_spread: 0.2
order_amount: 10
order_refresh_time: 20.0
price_source: external_market
price_type: mid_price
price_source_derivative: binance
price_source_market: SOL-USDT
long_profit_taking_spread: 1.5
short_profit_taking_spread: 1.5
stop_loss_spread: 4.0
Uses spot market price to detect funding arbitrage opportunities.

Position Management

One-Way Mode

# Net position calculation
net_position = long_contracts - short_contracts

if net_position > 0:
    # Net long position
    place_profit_taking_sell_orders()
elif net_position < 0:
    # Net short position
    place_profit_taking_buy_orders()
Benefits:
  • Simpler position tracking
  • Natural hedging of long/short
  • Lower margin requirements

Hedge Mode

# Separate position tracking
if long_position > 0:
    place_long_profit_taking_orders()
    place_long_stop_loss()

if short_position > 0:
    place_short_profit_taking_orders()
    place_short_stop_loss()
Benefits:
  • Simultaneous long and short
  • Independent position management
  • Advanced arbitrage strategies

Leverage and Risk

Liquidation Price Calculation

# Approximate liquidation calculation
entry_price = 50000  # USD
leverage = 10
margin_ratio = 0.01  # 1% maintenance margin

# Long position
liquidation_long = entry_price * (1 - 1/leverage + margin_ratio)
# = 50000 * (1 - 0.1 + 0.01) = 45500 USD

# Short position
liquidation_short = entry_price * (1 + 1/leverage - margin_ratio)
# = 50000 * (1 + 0.1 - 0.01) = 54500 USD
Experience LevelRecommended LeverageRisk Level
Beginner2-3xLow
Intermediate3-5xMedium
Advanced5-10xHigh
Expert10-20xVery High
Never use maximum available leverage. Maintain buffer for market volatility.

Funding Rate Considerations

Perpetual contracts charge/pay funding rates every 8 hours. Consider funding rates when market making:
  • Positive Funding: Longs pay shorts (favor short positions)
  • Negative Funding: Shorts pay longs (favor long positions)

Checking Funding Rates

# In Hummingbot
status --funding_rate
Adjust inventory target based on funding:
# High positive funding (longs pay shorts)
long_profit_taking_spread: 0.5   # Take long profits quickly
short_profit_taking_spread: 2.0  # Hold short positions longer

# High negative funding (shorts pay longs)
long_profit_taking_spread: 2.0   # Hold long positions
short_profit_taking_spread: 0.5  # Take short profits quickly

Tips for Success

Begin with 2-3x leverage regardless of exchange limits. Increase gradually as you gain experience:
leverage: 3  # Start here
# After 1 month profitable → 5
# After 3 months profitable → 7-10
Set stop loss at 2-5x your normal spread to prevent catastrophic losses:
bid_spread: 0.1
ask_spread: 0.1
stop_loss_spread: 3.0  # 30x the spread
Keep margin ratio above 20% to avoid liquidation:
# Check margin in Hummingbot
balance --derivative binance_perpetual
If margin < 30%, reduce position size or add collateral.
Calculate break-even including funding:
daily_funding_cost = position_size * funding_rate * 3
min_daily_profit_target = daily_funding_cost * 1.5

Risk Management

Critical Risks:
  • Liquidation Risk: Leverage amplifies losses; positions can be liquidated
  • Funding Risk: Negative funding rates reduce profitability
  • Volatility Risk: Sudden moves can trigger stop losses
  • Exchange Risk: Derivatives exchanges may have outages during volatility

Risk Mitigation Checklist

  • Set stop_loss_spread on all strategies
  • Use leverage ≤ 5x for most markets
  • Maintain margin ratio > 30%
  • Monitor funding rates 3x daily
  • Set price_ceiling and price_floor for range-bound trading
  • Enable order_optimization during high volatility
  • Keep 50% capital in reserve for margin calls

Performance Optimization

Order Placement Strategy

bid_spread: 0.02
ask_spread: 0.02
order_levels: 3
order_optimization_enabled: true
filled_order_delay: 5
Best for: High liquidity markets, competitive market making

Comparison with Spot Market Making

FeaturePerpetual MMSpot MM
LeverageYes (2-100x)No
Funding CostsYes (every 8h)No
Profit TakingBuilt-inManual
Stop LossBuilt-inExternal
Position ModesOne-way/HedgeN/A
Liquidation RiskYesNo
Capital EfficiencyHighLower

Source Code Reference

Configuration: /source/hummingbot/strategy/perpetual_market_making/perpetual_market_making_config_map.py:106 Strategy Implementation: /source/hummingbot/strategy/perpetual_market_making/perpetual_market_making.py Order Tracker: /source/hummingbot/strategy/perpetual_market_making/perpetual_market_making_order_tracker.py