MMashDiv

Paper trading

Rehearsing a strategy with simulated money against your real order book — what the simulator does and does not touch, how to turn it on for a supervised instance or a downloaded preset, how the starting balances are decided, and the two failure modes that make a paper run look broken.

5 min readUpdated 28 August 2026paper-trade, simulation, dry-run, rehearsal, strategies, instances

Paper trading runs a strategy exactly as it would run live — same spreads, same ladder, same refresh interval, same order book — and settles every fill against imaginary money. It is how you find out that a preset quotes 40 bps too tight without paying for the discovery.

It is Hummingbot's own simulator, not a second engine written here, so what it does is well defined and worth understanding before you trust a result.

What is real and what is not

Live Paper
Order book the strategy reads your exchange your exchange
Prices, spreads, book depth real real
Orders reaching the matching engine yes none
Wallet debited, inOrder held yes no
Fills, balances, inventory real simulated by Hummingbot
Appears in the live bot console yes no — nothing to show

Hummingbot spells paper mode as a connector suffix. bicrypto becomes bicrypto_paper_trade, which it resolves into a PaperTradeExchange wrapped around the real connector's order-book tracker. The bot is genuinely reading your market; it simply never sends an order to it.

That means a paper run is evidence about your liquidity, which a backtest is not. It also means it is not evidence about your matching engine, your fee schedule or your wallet accounting — none of those are exercised.

The simulator fills against the book it can see, and it does not model the market impact of the orders it is pretending to place. A tight strategy will look better on paper than it will trade. Read a paper run for behaviour — does it quote both sides, does it re-quote sensibly, does it hold inventory it should have shed — not for the number at the bottom.

Turning it on for a supervised instance

On Bot Instances, edit the instance and switch on Paper trading (simulated money). It takes effect at the next start; a running bot keeps the mode it was launched with, exactly like every other setting on that form.

The card then carries a Paper badge, and the bot console for that instance carries a paper — no live orders chip. Both exist for one reason: a healthy paper bot and a broken live one look identical from outside. Process up, status RUNNING, memory climbing, and nothing at all on the book.

Two things happen for you at start:

  1. conf/conf_client.yml gains bicrypto under paper_trade_exchanges, and starting balances for this market under paper_trade_account_balance. Only that block is touched — your MQTT, telemetry and colour settings are copied through untouched, and a second paper instance on the same checkout adds its market's balances alongside the first one's rather than replacing them.
  2. conf/connectors/bicrypto.yml is written as usual. Paper mode still needs it: the simulated connector borrows the live one's settings, including the REST base URL its order-book tracker dials. Without that file the book never arrives and the bot waits for ever.

The instance's log opens with a line stating the mode and the exact simulated balances. If a balance could not be worked out, that line says which one and why.

Starting balances

Leave Starting balances blank and both sides of the market are funded from the strategy's own numbers: ten times total_amount_quote in the quote asset, and the equivalent of that in the base asset at the current mid price. Ten times, because a market maker does not spend its notional once — it quotes, fills, re-quotes, and its executors hold inventory while they run. A 1× seed runs out within minutes and reads as a strategy fault.

Set it to rehearse a specific inventory:

{"USDT": 5000, "BTC": 0}

That is "start flat and long nothing" — a useful test, because a two-sided maker with no base cannot quote the sell side until it has bought some, and watching how long that takes on your book is worth knowing.

An explicit figure always wins. A derived one only fills a gap: an asset the file does not mention, or one sitting at zero.

Turning it on for a downloaded preset

Customers running Hummingbot on their own machines get the same thing from Strategy presets. Switch on Paper trade and both Preview and Download serve the simulated copy, under its own filename (..._paper.yml) so it never overwrites the live config sitting beside it in conf/controllers/.

Two steps the download cannot do for them, stated in the file's own header:

  1. connect bicrypto must already have been run in that install.
  2. conf/conf_client.yml must fund the market. Hummingbot's stock paper balances cover BTC, ETH, USDT and a few other majors, so a customer rehearsing on your own listed token starts with zero of the base asset — the sell side never quotes, and it reads as a broken strategy.
paper_trade:
  paper_trade_exchanges:
  - bicrypto
  paper_trade_account_balance:
    USDT: 100000.0
    TKN: 250.0

Limits

Spot only. Hummingbot's simulator is a spot exchange: no positions, no leverage, no position mode. A perpetual profile is refused when you save the instance rather than allowed to fail later — on the simulator it raises inside the executor on its first quote, which reaches you as a stack trace rather than as an answer about the checkbox you ticked.

XEMM simulates both legs. A cross-exchange preset run in paper mode puts the maker and the taker on their paper connectors. Simulating only the maker would mean every imaginary fill triggered a real hedge, in real size, on your own Binance or MEXC account, covering trades that never happened — for as long as the bot ran.

If you specifically want a live maker with a simulated hedge — proving your side quotes correctly before committing capital on the other venue — that is a different thing and it is configured on the preset itself, by setting the taker connector to that venue's paper form. See Strategies and presets.

The market must still be tradable. The book is real, so a pair with nothing on one side has no mid price, and a maker with no mid raises on every tick whether its money is real or not. The same preflight refuses the start.

Nothing is cancelled when it stops. A live instance sweeps the book on exit, because a dead market maker's orders are worse than no market maker. A paper instance skips that sweep entirely: it placed nothing, so everything the sweep could reach belongs to someone else — your own hand-placed orders, or another bot on the same account.

When a paper run looks wrong

Only one side quotes. The simulator has no balance in the other asset. Check the opening line of the instance log, which prints the exact balances it started with, and set them explicitly if the derived figure could not be worked out.

Nothing in the bot console. Correct, and not a fault. That console shows your exchange's orders and fills; a paper bot has none. Read the instance log instead.

"bicrypto is not ready. Please wait…" for ever. The book is not arriving. Almost always a missing or stale conf/connectors/bicrypto.yml — the paper connector inherits the base URL from it. Restart the instance; credentials are re-provisioned at every start.