Quickstart Guide

This guide walks you through running your first Hummingbot trading bot using the Simple PMM (Pure Market Making) strategy on a paper trading exchange.

This quickstart uses paper trading (simulated trading) so you can learn without risking real funds. You’ll create a bot that places buy and sell orders around the mid-price of a trading pair.

Prerequisites

Hummingbot installed via Docker or source
Hummingbot CLI running

Step 1: Start Hummingbot

If Hummingbot isn’t already running:

docker attach hummingbot

You should see the Hummingbot CLI prompt:

>>>

Step 2: Create a Script Strategy

We’ll use the Simple PMM script strategy, which places symmetric buy and sell orders around the mid-price.

Navigate to Scripts

In the Hummingbot CLI:

>>> create --script-config

This opens the script configuration wizard.

Select Simple PMM

When prompted for a script file, enter:

simple_pmm.py

The simple_pmm.py script is included with Hummingbot in the scripts/ directory. You can view all available scripts with the ls scripts/ command from your shell.

Configure Parameters

The wizard will ask for configuration parameters. Use these recommended values for paper trading:

Parameter	Value	Description
exchange	`binance_paper_trade`	Paper trading exchange (no real funds)
trading_pair	`ETH-USDT`	Trading pair to use
order_amount	`0.01`	Amount of ETH per order
bid_spread	`0.001`	0.1% below mid-price for buy orders
ask_spread	`0.001`	0.1% above mid-price for sell orders
order_refresh_time	`15`	Refresh orders every 15 seconds
price_type	`mid`	Use mid-price as reference

Example configuration session:

Enter exchange (default: binance_paper_trade): binance_paper_trade
Enter trading_pair (default: ETH-USDT): ETH-USDT
Enter order_amount (default: 0.01): 0.01
Enter bid_spread (default: 0.001): 0.001
Enter ask_spread (default: 0.001): 0.001
Enter order_refresh_time (default: 15): 15
Enter price_type (default: mid): mid

Save Configuration

When prompted for a configuration name:

Enter a name for your configuration: my_first_bot

The configuration will be saved to conf/scripts/my_first_bot.yml.

Step 3: Start the Strategy

Now launch your bot:

>>> start --script my_first_bot

You should see output like:

Starting strategy...
Strategy: simple_pmm
Exchange: binance_paper_trade
Trading pair: ETH-USDT

Creating orders...
BUY 0.01 ETH-USDT binance_paper_trade at 2450.55
SELL 0.01 ETH-USDT binance_paper_trade at 2455.50

The bot will continuously:

Cancel existing orders
Calculate new bid/ask prices based on current mid-price
Place new orders
Wait for order_refresh_time seconds
Repeat

Step 4: Monitor Your Bot

While the strategy is running, you can use these commands to monitor performance:

status - View current orders and balances

>>> status

Shows:

Active buy/sell orders
Current balances
Market prices
Spread information

history - View completed trades

>>> history

Lists all filled orders with:

Trade side (buy/sell)
Amount
Price
Timestamp

pnl - Check profit and loss

>>> pnl

Shows:

Realized PnL from closed trades
Unrealized PnL from open positions
Total PnL

config - View current configuration

>>> config

Displays all strategy parameters

Step 5: Modify and Restart

To adjust your strategy parameters:

Stop the Strategy

>>> stop

This will cancel all open orders and stop the bot.

Edit Configuration

>>> config

Then modify any parameter, for example:

>>> config bid_spread
Enter bid_spread (current: 0.001): 0.002

Restart

>>> start

The bot will use the new configuration.

Understanding the Simple PMM Code

The Simple PMM strategy demonstrates core Hummingbot concepts. Here’s the key logic from scripts/simple_pmm.py:

def create_proposal(self) -> List[OrderCandidate]:
    # Get reference price (mid-price or last trade)
    ref_price = self.connectors[self.config.exchange].get_price_by_type(
        self.config.trading_pair, self.price_source
    )
    
    # Calculate bid and ask prices
    buy_price = ref_price * Decimal(1 - self.config.bid_spread)
    sell_price = ref_price * Decimal(1 + self.config.ask_spread)
    
    # Create order candidates
    buy_order = OrderCandidate(
        trading_pair=self.config.trading_pair,
        is_maker=True,
        order_type=OrderType.LIMIT,
        order_side=TradeType.BUY,
        amount=Decimal(self.config.order_amount),
        price=buy_price
    )
    
    sell_order = OrderCandidate(
        trading_pair=self.config.trading_pair,
        is_maker=True,
        order_type=OrderType.LIMIT,
        order_side=TradeType.SELL,
        amount=Decimal(self.config.order_amount),
        price=sell_price
    )
    
    return [buy_order, sell_order]

The Simple PMM strategy is defined in hummingbot/scripts/simple_pmm.py:31-95. It extends StrategyV2Base and implements the core methods: on_tick(), create_proposal(), and did_fill_order().

Moving to Real Trading

Once you’re comfortable with paper trading, you can move to real exchanges:

Before trading with real funds:

Thoroughly test your strategy in paper trading
Start with small amounts
Understand the risks of automated trading
Never invest more than you can afford to lose

Connect to Real Exchange

Add API keys for a real exchange:

>>> connect binance

Follow the prompts to enter your API key and secret. See Exchange Setup for details.

Create New Configuration

>>> create --script-config

Use the same simple_pmm.py script but configure:

Real exchange (e.g., binance)
Appropriate order amounts for your balance
Suitable spreads for the market

Start with Caution

>>> start --script my_real_bot

Monitor closely, especially during the first few hours.

Next Steps

Explore Strategies

Learn about other built-in strategies like XEMM, VWAP, and DCA

Architecture Deep Dive

Understand Controllers, Executors, and the V2 framework

Create Custom Strategy

Build your own strategy from scratch

Configure Exchanges

Set up API keys for different exchanges

Common Issues

Orders not filling

Too wide spreads: Your bid/ask spreads might be too large. Try reducing them.
Low volume pair: Choose a more liquid trading pair.
Check order book: Use >>> orderbook to see current market depth.

Insufficient balance errors

Increase balance: In paper trading, you can add more test funds.
Reduce order_amount: Make orders smaller to fit your available balance.
Check budget: The adjust_proposal_to_budget() method may be rejecting orders.

Strategy keeps canceling orders

order_refresh_time too short: Increase to 30-60 seconds to reduce API calls.
Price volatility: In volatile markets, orders may need frequent updates.

Script not found

Ensure the script exists:

ls scripts/simple_pmm.py

If missing, pull the latest code:

git pull origin master

Join the Hummingbot Discord to get help from the community, share your strategies, and learn from other traders.

Get Started

Core Concepts

Built-in Strategies

Exchange Connectors

Strategy Development

Gateway

Configuration

CLI Commands

Prerequisites

Step 1: Start Hummingbot

Step 2: Create a Script Strategy

Step 3: Start the Strategy

Step 4: Monitor Your Bot

Step 5: Modify and Restart

Understanding the Simple PMM Code

Moving to Real Trading

Next Steps

Explore Strategies

Architecture Deep Dive

Create Custom Strategy

Configure Exchanges

Common Issues

Build docs developers (and LLMs) love

Get Started

Core Concepts

Built-in Strategies

Exchange Connectors

Strategy Development

Gateway

Configuration

CLI Commands

​Prerequisites

​Step 1: Start Hummingbot

​Step 2: Create a Script Strategy

​Step 3: Start the Strategy

​Step 4: Monitor Your Bot

​Step 5: Modify and Restart

​Understanding the Simple PMM Code

​Moving to Real Trading

​Next Steps

Explore Strategies

Architecture Deep Dive

Create Custom Strategy

Configure Exchanges

​Common Issues

Build docs developers (and LLMs) love

Prerequisites

Step 1: Start Hummingbot

Step 2: Create a Script Strategy

Step 3: Start the Strategy

Step 4: Monitor Your Bot

Step 5: Modify and Restart

Understanding the Simple PMM Code

Moving to Real Trading

Next Steps

Common Issues