Skip to main content
Paper trading mode allows you to test trading strategies with simulated funds on real market data. This is perfect for testing new strategies, learning Hummingbot, or experimenting with parameters without financial risk.

​
Overview

Paper trading mode creates a simulated trading environment that:
  • Uses real-time market data from exchanges
  • Executes simulated orders that don’t hit actual exchange APIs
  • Maintains a virtual balance you can configure
  • Mimics real trading behavior including order fills and market dynamics
Paper trading is sometimes called “simulation mode” or “backtesting” - though Hummingbot’s paper trading runs in real-time, not on historical data.

​
Configuration

​
Enable Paper Trading

Paper trading settings are configured in conf/conf_client.yml:
Paper Trade Config
paper_trade:
  paper_trade_exchanges:
    - binance
    - kucoin
    - kraken
    - gate_io
  paper_trade_account_balance:
    BTC: 1
    USDT: 100000
    USDC: 100000
    ETH: 20
    WETH: 20
    SOL: 100
    DOGE: 1000000
    HBOT: 10000000
​
paper_trade_exchanges
array
List of exchanges available for paper trading. These don’t require API keys.
​
paper_trade_account_balance
object
Virtual starting balances for different assets. Set these based on your testing needs.

​
Supported Paper Trade Exchanges

By default, these exchanges are available for paper trading:

Binance

Spot trading simulation

KuCoin

Spot trading simulation

Kraken

Spot trading simulation

Gate.io

Spot trading simulation
You can add any exchange to paper_trade_exchanges as long as it supports public market data without authentication.

​
Setting Virtual Balances

You can customize your virtual balances to match your testing scenario: 
paper_trade_account_balance:
  BTC: 0.1
  USDT: 10000
  ETH: 2
The balances are stored as JSON and must use valid syntax. Use the format: {"SYMBOL": amount, "SYMBOL2": amount}

​
Using Paper Trading

​
Starting a Paper Trade Strategy

When creating a strategy, select a paper trade exchange: 
>>> create

What is your market making strategy?
>>> pure_market_making

Enter your maker spot connector:
>>> binance_paper_trade

Enter the trading pair:
>>> BTC-USDT
Notice the _paper_trade suffix on the exchange name.
1

Create Strategy

Use the create command and select your strategy
2

Select Paper Trade Exchange

Choose an exchange with _paper_trade suffix (e.g., binance_paper_trade)
3

Configure Parameters

Set your strategy parameters as normal
4

Start Trading

Run start to begin paper trading

​
Connecting to Paper Trade Exchanges

Paper trade exchanges don’t require API keys: 
>>> connect binance_paper_trade

You are using the paper trade mode for binance.
No API credentials required.

​
How Paper Trading Works

​
Order Simulation

Paper trading simulates order execution based on real market conditions:
When you place an order in paper trading:
  1. The order is stored in Hummingbot’s internal database
  2. Real market data is fetched from the exchange
  3. No actual API call is made to the exchange
Orders are filled when:
  • Market price crosses your limit order price
  • Sufficient volume exists at that price level
  • Order book depth indicates the order would fill
Fill simulation mimics real trading conditions including partial fills.
When an order fills:
  • Virtual balances are updated accordingly
  • Trading fees are deducted (using exchange’s default fee structure)
  • P&L is calculated based on execution prices

​
Market Data

Paper trading uses real-time market data:
  • Live order book snapshots
  • Current market prices
  • Actual trading volumes
  • Real spread and liquidity conditions
Because paper trading uses real market data, you need an internet connection and the exchange’s public API must be accessible.

​
Implementation Details

​
Paper Trade Connector

From the source code (hummingbot/client/settings.py): 
class AllConnectorSettings:
    @classmethod
    def initialize_paper_trade_settings(cls, paper_trade_exchanges: List[str]):
        """Initialize paper trade connectors based on real exchange settings"""
        cls.paper_trade_connectors_names = paper_trade_exchanges
        
        for exchange in paper_trade_exchanges:
            base_connector = cls.all_connector_settings.get(exchange)
            if base_connector:
                # Create paper trade version
                paper_trade_settings = ConnectorSetting(
                    name=f"{exchange}_paper_trade",
                    type=base_connector.type,
                    centralised=base_connector.centralised,
                    example_pair=base_connector.example_pair,
                    use_ethereum_wallet=base_connector.use_ethereum_wallet,
                    trade_fee_schema=base_connector.trade_fee_schema,
                    config_keys=base_connector.config_keys,
                    parent_name=base_connector.name,
                    # ... other settings
                )
                cls.all_connector_settings[f"{exchange}_paper_trade"] = paper_trade_settings

​
Configuration Validation

From client_config_map.py: 
class PaperTradeConfigMap(BaseClientModel):
    paper_trade_exchanges: List = Field(
        default=[
            BinanceConfigMap.model_config["title"],
            KuCoinConfigMap.model_config["title"],
            KrakenConfigMap.model_config["title"],
            GateIOConfigMap.model_config["title"],
        ],
    )
    
    paper_trade_account_balance: Dict[str, float] = Field(
        default={
            "BTC": 1,
            "USDT": 100000,
            "USDC": 100000,
            "ETH": 20,
            "WETH": 20,
            "SOL": 100,
            "DOGE": 1000000,
            "HBOT": 10000000,
        },
        json_schema_extra={"prompt": lambda cm: (
            "Enter paper trade balance settings (Input must be valid json — "
            "e.g. {\"ETH\": 10, \"USDC\": 50000})"
        )},
    )

​
Advantages of Paper Trading

Risk-Free Testing

Test strategies without risking real capital

Real Market Data

Practice with live market conditions and prices

No API Keys Needed

Start testing immediately without exchange accounts

Unlimited Funds

Configure any virtual balance amount for testing

Strategy Validation

Verify strategy logic before live deployment

Parameter Tuning

Experiment with different settings risk-free

​
Limitations

Paper Trading Limitations:
  1. Order fills are simulated - May not perfectly reflect real execution
  2. No slippage modeling - Large orders may fill unrealistically well
  3. No queue position - Assumes instant fills when price is touched
  4. Simplified fee structure - Uses default exchange fees
  5. No API rate limits - Real trading has rate limit constraints
  6. No real money emotions - Psychology differs when trading real funds

​
Best Practices

1

Always Paper Trade First

Test every new strategy in paper trading mode before going live
2

Use Realistic Balances

Set virtual balances similar to what you’d actually trade with
3

Monitor Performance

Track paper trading results over multiple market conditions
4

Test Edge Cases

Try extreme market conditions, high volatility, low liquidity
5

Document Results

Keep notes on what works and what doesn’t
6

Transition Gradually

Start live trading with small amounts before scaling up

​
Switching Between Paper and Live Trading

​
From Paper to Live Trading

1

Stop Paper Trading

Use the stop command to halt your paper trading strategy
2

Connect Real Exchange

Use connect binance (without _paper_trade suffix) and enter API credentials
3

Create Live Strategy

Create a new strategy using the real exchange connector
4

Start with Small Amounts

Begin with reduced position sizes for safety

​
From Live to Paper Trading

Simply create a new strategy using the _paper_trade exchange variant.

​
Monitoring Paper Trading Performance

Use Hummingbot’s standard commands to monitor paper trading: 
>>> status
>>> history
>>> pnl
>>> balance
All commands work identically in paper trading mode.

​
Configuring Paper Trade Balances Programmatically

You can update paper trade balances via the config file: 
from hummingbot.client.config.config_helpers import (
    load_client_config_map_from_file,
    save_to_yml,
)
from hummingbot.client.settings import CLIENT_CONFIG_PATH

# Load config
client_config = load_client_config_map_from_file()

# Update paper trade balances
client_config.paper_trade.paper_trade_account_balance = {
    "BTC": 2.0,
    "USDT": 200000,
    "ETH": 40,
}

# Save config
save_to_yml(CLIENT_CONFIG_PATH, client_config)

​
Troubleshooting

Ensure the exchange is listed in paper_trade_exchanges in conf/conf_client.yml
Check that:
  • Market data is being received (check logs)
  • Your order prices are within the market spread
  • Sufficient time has passed for price movement
Verify:
  • Orders are actually filling (check history)
  • No configuration errors in conf_client.yml
  • Restart Hummingbot to reload config

Global Settings

Configure paper trading in global settings

Config Files

Understanding configuration file structure

Strategies

Explore strategies to test in paper trading

Getting Started

Complete beginner’s guide

Build docs developers (and LLMs) love

Get started for freeTalk to us