Tools
Command-line tools that come with Wallbot: the backtester, the wall, flow and coin studies, the live learning report, the liquidation calculator and the testnet check. For each one: what it is for, the exact command, an example and how to read what it prints.
Overview
Run every command from the Wallbot folder (C:\wallbot) with the bot's own Python, for example .venv\Scripts\python.exe backtest.py run .... The examples below write python for short.
| Tool | Command | Purpose | Network |
|---|---|---|---|
| Backtest | python backtest.py download | run | selftest | Replay real order books through the same engine | download: Tardis.dev; run: Binance public 4h candles when sr_filter is on |
| Wall study | python backtest.py wallstudy | How walls behave when touched: held, broke, pulled, penetration, flow | Binance public candles, and exchangeInfo if --tick is omitted |
| Flow study | python backtest.py flowstudy | Hold rates by flow measurement; proposes and validates a flow_filter | none |
| Coin study | python backtest.py coinstudy | Hold rates by coin trait; proposes scanner thresholds | none |
| Live report | python backtest.py livereport | The live learning log (items a to m) as a report and CSV | none |
| Liquidation calculator | python liq_calc.py | What the bot computes for one position, to compare with Binance's calculator | Binance public exchangeInfo; with --use-saved-key read-only signed calls |
| Testnet check | python scripts\testnet_check.py | PASS/FAIL of every order path on Binance's futures testnet | Binance testnet only |
Note. These tools never contact the running dashboards, and the bot never starts them: you run them by hand. The studies and the report open the bot's database read-only. One BTC day replays in about 17 minutes.
One heavy job at a time
Every backtest.py command (download, run, selftest, the studies and the live report) follows three rules, so it never slows the bots down:
- One at a time. A lock file enforces it. A second command started while one runs refuses at once with "Not started: another backtest/study/replay is running (lock ...); one at a time."
- Lowest priority. On Linux it lowers itself to nice 19 and ionice idle. Add
--normal-priorityto keep normal priority. - Memory guard. The job aborts if it uses more than 1500 MB (
--max-rss-mb) or the server has less than 2000 MB available (--min-free-mb); 0 turns either check off. It does not even start when memory is already short. An aborted job prints "ABORTED by the memory guard: ..." and exits with code 3. Nothing else is affected. The guard reads Linux memory figures; on Windows it stays idle.
These options go before the command name:
python backtest.py --max-rss-mb 2500 --normal-priority wallstudy --symbol BTCUSDT --live
Backtest
The backtester replays full-depth order-book updates and trades through the same engine the live bot uses, with simulated fills. Data comes from Tardis.dev (the 1st day of every month is free) or from the bot's own recordings in backtest_data\live\.
download
python backtest.py download --symbol SYMBOL --dates YYYY-MM-DD [YYYY-MM-DD ...] [--api-key KEY]
| Option | Meaning |
|---|---|
--symbol | Required. Binance symbol, e.g. BTCUSDT |
--dates | Required. One or more days. Days other than the 1st of a month are skipped without a key |
--api-key | Tardis.dev key (or the TARDIS_API_KEY environment variable) |
Files land in backtest_data\ as SYMBOL_incremental_book_L2_DATE.csv.gz and SYMBOL_trades_DATE.csv.gz. Files already present are kept ("have ...").
python backtest.py download --symbol BTCUSDT --dates 2026-08-01 2026-09-01
run
python backtest.py run --symbol SYMBOL --tick TICK --step STEP [options]
Without --book / --trades, every downloaded file for the symbol in backtest_data\ is replayed. The tick, step and minimum notional must match the coin's current rules (Binance /fapi/v1/exchangeInfo).
| Option | Default | Meaning |
|---|---|---|
--symbol | required | The real symbol (also for recorded files with ASCII-safe names) |
--book, --trades | all files found | Explicit data files (several allowed) |
--tick, --step | required | Price tick and quantity step |
--min-notional | 5.0 | Exchange minimum order value in USDT (BTCUSDT: 50) |
--max-leverage | 125 | The coin's exchange maximum; an assumption without the bracket table |
--mmr | 0.004 | Maintenance margin rate of the first bracket |
--maker-fee, --taker-fee | 0.0002, 0.0005 | Fees as fractions (0.02%, 0.05%) |
--balance | 100.0 | Starting balance in USDT. Use 1000 or more on BTC, or positions round down to nothing |
--set | none | Setting overrides, e.g. --set entry_model=loss_budget leverage=20 (validated like the dashboard) |
--book-step-ms | 1000 | Book sampling interval (live sees 100 ms updates) |
--cancel-latency-ms | 300 | Time a cancel takes to land; fills meanwhile count |
--slippage-bps | 5.0 | Slippage on stops and market exits |
--max-gap-s | 60.0 | A data gap longer than this closes everything and starts a new segment |
--out | backtest_results | Output folder |
--contract-size | 1.0 | Execution exchange: base units per contract (MEXC BTC_USDT: 0.0001) |
--primary-exchange, --primary-tick, --primary-contract-size | binance, tick, 1.0 | Two-exchange runs: the exchange in --book/--trades |
--alt-exchange, --alt-book, --alt-trades, --alt-tick, --alt-contract-size | none | A second book source, e.g. mexc |
--exec | the primary | Execution exchange: the primary or the alt exchange |
python backtest.py run --symbol BTCUSDT --tick 0.1 --step 0.001 --min-notional 50 --balance 1000 --max-leverage 125
python backtest.py run --symbol BTCUSDT --tick 0.1 --step 0.001 --min-notional 50 --balance 1000 --book backtest_data/live/BTCUSDT_incremental_book_L2_2026-09-27.csv.gz --trades backtest_data/live/BTCUSDT_trades_2026-09-27.csv.gz
With sr_filter on (default), the run first fetches the needed 4h candles from Binance's public endpoint and caches them in backtest_data\. Only candles that had fully closed at each moment are used.
Reading the backtest report
| Line | Meaning |
|---|---|
Wallbot backtest: SYMBOL, N days of data in S segment(s), E events | How much data was replayed. More than one segment means gaps split the data |
Settings, Assumptions | The effective settings and the simulation assumptions (book step, cancel latency, slippage, fees). Keep them with your results |
Balance, Return | Start and end balance, total return and return per day |
Trades ... win rate | Closed trades and the share with a positive result |
Avg win / loss | Average result of winning and losing trades in USDT |
Profit factor | Sum of wins divided by the sum of losses |
Max drawdown | Largest fall from a balance peak, in % |
Leverage used | Minimum, median and maximum leverage of the closed trades |
Exits: | One row per exit reason (for example take profit, trailing stop, stop (wall broke), wall pulled after fill, liquidation): count, average result as % of margin, total USDT |
Entries cancelled before fill: | Why pending entries were cancelled (for example wall pulled, wall faded) and how often |
Note: N trades is too few to judge the strategy | Printed under 30 trades. Replay more days |
Price gap ... | Two-exchange runs only: median and 5 to 95% gap between the exchanges in bps |
Two files are saved in the output folder:
SYMBOL_trades.csv: one row per trade with the same columns as the bot's trade records (side, status, entry, stop, fill price, leverage, margin, pnl, fees, close reason, stack size, re-anchors, take-profit price, ...).SYMBOL_summary.json: everything in the report plus counters:stacks(entries by stack size, average span),reanchors,holds,replans,take_profit(armed, filled, retargeted, reward/risk skips),stop_tightenings,absorbed_after_fill,correlation_guard_skips,flow_filter_skips, andgrid_rejects/close_position_rejects(orders the simulated exchange refused as Binance would; these should be 0).
Warning. A backtest is not a forecast. Fills happen only when a trade prints through the limit price, the book is sampled once a second, and it cannot know your queue position or how a spoofer reacts to your order. Treat a result as a check of the logic, and confirm in paper mode before risking money.
selftest
python backtest.py selftest [--minutes 240] [--seed 7]
Writes synthetic data (SIMUSDT) and replays it, to prove the pipeline runs end to end. It says nothing about real markets.
Wall study
Replays order books through the same wall tracker, without trading, and follows every confirmed wall that price touches. A touch is held when price then moves --bounce-pct away, broken when it goes --break-pct past the far edge. It also records how deep price went past the far edge before a hold, whether the wall was pulled, and the order-flow measurements at confirmation, first touch and the end.
python backtest.py wallstudy --symbol SYMBOL [options]
| Option | Default | Meaning |
|---|---|---|
--symbol | required | The coin |
--tick | looked up | Price tick; read from Binance exchangeInfo when omitted |
--live | off | Use the bot's recordings (see --live-dir) instead of downloaded files |
--live-dir | backtest_data\live | Folder of recorded files |
--book, --trades | all files found | Explicit files |
--bounce-pct | 0.5 | Held once price moves this far (%) away from the wall |
--break-pct | 0.5 | Broken once price goes this far (%) past the far edge |
--timeout-h | 4.0 | A touch unresolved after this long counts as unresolved |
--out | backtest_results/wallstudy | Output folder |
--group | all | core or movers: only days the coin was in that group (from the Research database's coin_groups table) |
python backtest.py wallstudy --symbol XRPUSDT --live --out backtest_results/wallstudy_flow_live
It prints the summary as JSON and saves SYMBOL_wallstudy_summary.json and SYMBOL_wallstudy_walls.json (one record per wall).
| Summary field | Meaning |
|---|---|
confirmed, touched, gone_before_touch | Walls confirmed; touched by a trade while still there; gone before any touch |
all, on_level, off_level | The same counts for all touched walls, those at a 4h level, and those not at one |
held, broke, unresolved, pulled | Outcomes of the touches |
hold_rate_pct | held / (held + broke), in % |
held_penetration_ticks, held_penetration_pct | For held walls: how far price went past the far edge (median, p75, p90). Useful for judging the stop distance |
held_no_penetration_pct | Share of held walls that price never went past |
flow_buckets | Hold rate by bucket of each flow measurement (time to break, absorption, flow reversal, impact trend, quartiles of imbalance, cushion and bounce room). Buckets under 30 walls have "few": true |
coin | Coin metrics sampled during the replay (spread, depth, 15m candles), used by the coin study |
Tip. The flow and coin studies read backtest_results/wallstudy_flow_live by default. Write wall studies there with --out, or point the studies at your folder with --dirs.
Flow study
Reads wall-study results and asks: does any flow measurement separate walls that hold from walls that break? It splits the walls by date, 70% discovery and 30% validation. It proposes at most 2 filters from discovery walls only, then checks them on the validation walls against fixed PASS/FAIL criteria.
python backtest.py flowstudy [--dirs DIR ...] [--discovery-frac 0.7] [--split-date YYYY-MM-DD] [--record-coins 15] [--out backtest_results/flowstudy] [--group all|core|movers]
| Option | Default | Meaning |
|---|---|---|
--dirs | backtest_results/wallstudy_flow_live | Folders with *_wallstudy_summary.json / _walls.json |
--discovery-frac | 0.7 | Share of the dates used for discovery |
--split-date | none | Earlier dates are discovery (overrides the share) |
--record-coins | 15 | Coins recorded, for the "weeks until 30 walls" estimate |
--out | backtest_results/flowstudy | Output folder (flowstudy.json) |
--group | all | Only walls on days the coin was core or movers |
python backtest.py flowstudy --split-date 2026-09-25
Reading the flow study
- First the walls used (touched, then held or broke), the coins and days, and which dates are discovery and validation. A per-coin table follows:
| coin | touched | discovery | validation | confirmed |. - Bucket tables (discovery, then pooled over all dates) use these columns:
| Column | Meaning |
|---|---|
bucket / set | The range of the measurement, or which walls (discovery, validation, validation baseline) |
walls, held | Walls in the bucket, and how many held |
hold rate | held / walls |
95% CI | Wilson 95% interval of the hold rate. Wide intervals mean too little data |
fav 30m median / p75 | The largest favourable move within 30 minutes, median and 75th percentile, in % |
note | under 30: too few walls to trust |
- "Proposed filters" prints each candidate as
flow_filter = '...'with discovery, validation and baseline rows, the median required move, and the four criteria: 1) at least 50 validation walls pass; 2) hold rate at least 65% and its lower bound above the baseline; 3) median favourable move at least the required move; 4) the filter-on backtest beats filter-off, printed PENDING until you run it. - "Bounce estimate calibration" compares the bot's 5 and 15 minute bounce estimates with what happened (median ratio actual / estimate). The ratio feeds
bounce_calibration_5mandbounce_calibration_15m.
Note. The study measures at the first touch, while flow_filter acts when the entry is placed, before any touch. Criterion 4 (a backtest with and without the filter) is the real test.
Coin study
Same input and the same date split as the flow study, but per coin: which coin traits go with walls that hold. It can propose scanner thresholds (for example a maximum spread) and validates them with the same criteria.
python backtest.py coinstudy [--dirs DIR ...] [--discovery-frac 0.7] [--split-date YYYY-MM-DD] [--out backtest_results/coinstudy] [--group all|core|movers]
It accepts the same options as the flow study (--record-coins is accepted but not used). The maximum leverage and first-bracket cap columns are filled from values the Research instance cached from its read-only key (data\wallbot.db, opened read-only).
| Column | Meaning |
|---|---|
touched, hold rate, 95% CI | Touched walls (held or broke), hold rate and its Wilson interval |
spread bps | Median bid-ask spread |
depth 0.5%, depth 1% | Resting notional within 0.5% and 1% of price |
tick % | Tick as a share of price |
ATR15 %, ATR/band | 15-minute ATR as % of price, and divided by the middle of the wall distance band |
max lev, 1st bracket | Highest leverage, and the notional cap of the first bracket |
corr BTC | Correlation of 15m returns with BTC |
confirmed/day, pulled, touch rate | Confirmed walls per day, share pulled, share touched |
fav after hold | Median favourable move after a hold, in % |
note | under 30: too few touched walls |
A heading "PRELIMINARY" means some coins have fewer than 30 touched walls. Saved as coinstudy.json.
Live learning report
Turns the Trading instance's live learning log into a Markdown report and a CSV. It is the same data the "Live learning" page shows, items a) to m): liquidation estimate vs Binance, post-only rejections, stop slippage, spoof races, take profits, trailing windows without a stop, latency, fees, estimated vs actual P&L, Binance error codes, reconciliation, notifications and setups skipped as too small.
python backtest.py livereport [--data data_live] [--out backtest_results/livereport] [--all]
| Option | Default | Meaning |
|---|---|---|
--data | data_live | The instance's data folder; its wallbot.db is opened read-only |
--out | backtest_results/livereport | Output folder |
--all | off | Include events from before the current test start ("Count losses from now") |
python backtest.py livereport --data data_live
The report starts with the number of closed trades and live P&L vs the paper shadow. Each section ## a) ... to ## m) ... has a table | time (UTC) | trade | coin | event | details |, or "No events yet.". A JSON summary closes it (stop slippage in bps vs the assumption, liquidation error in ticks, error counts, too-small skips per coin, ...). It is printed and saved as live_test_report.md, and the raw log as live_log.csv with columns ts, trade_id, symbol, cat, data.
Liquidation calculator
Prints what Wallbot computes for one isolated position, so you can compare it with Binance's own calculator. It never places orders.
python liq_calc.py --symbol SYMBOL --side long|short --entry PRICE --leverage N --margin USDT [options]
| Option | Default | Meaning |
|---|---|---|
--symbol, --side, --entry, --leverage, --margin | required | The position: side long or short, entry price, leverage, initial margin in USDT |
--stop | none | A stop price to check and size margin for |
--wall-far | none | The wall's far edge: also prints the Wall % stop and whether it is safe |
--mmr, --cum | 0.004, 0 | Assumed bracket without a key (right only for small positions in the first bracket) |
--maker, --taker | 0.0002, 0.0005 | Assumed fees without a key |
--slippage-bps | your setting | Stop slippage; defaults to paper_slippage_bps |
--use-saved-key | off | Use the account's real bracket table and fee rates through the Research instance's saved key, strictly read-only (GET only) |
The buffer, minimum ticks, Wall % distance, fee limit and the learned safety offset are read from the Research instance's database (data\wallbot.db), read-only. The tick and step come from Binance's public exchangeInfo (0.1 and 0.001 if it cannot be reached).
python liq_calc.py --symbol BTCUSDT --side long --entry 70000 --leverage 100 --margin 2 --wall-far 69800
Example output
Illustrative output, computed with the same functions and default settings, no key and no learned offset. Yours depends on your settings, database and the coin's current rules.
BTCUSDT LONG 100x entry 70000, margin 1.4000 USDT, qty 0.002 (notional 140.00)
Brackets: ASSUMED single bracket (mmr 0.40%, cum 0); use --use-saved-key for the real table
Bracket used: max 125x, notional 0-inf, mmr 0.400%, cum 0
Isolated wallet assumed: 1.372000 USDT (margin minus the opening fee 0.028000)
Liquidation (ours, Binance formula): 69592.37 without the offset, 69592.37 with the learned offset 0.0000% (none learned yet) [old estimate 69580.00]
Required room from the stop's fill to liquidation: max(8% of margin, 10 ticks) = 560 ticks, 560 with the offset
Closest stop the bot would place (slippage 5 bps): 69683.3
wall_pct stop (0.50% behind 69800): 69451 -> NOT SAFE at this leverage (the bot would step leverage down)
Fees (maker entry + taker exit at 69451): 0.097451 USDT = 6.96% of margin (limit 15%)
Isolated wallet for stop 69451 + buffer (liquidation at or beyond 69360.27): 1.834333 USDT -> add 0.462333 USDT
| Line | How to read it |
|---|---|
| First line | The position after rounding: 2 USDT x 100 / 70,000 = 0.00286 BTC rounds down to 0.002, so the real margin is 1.40 USDT. Rounding only ever makes positions smaller |
Brackets, Bracket used | Where the maintenance rate came from, and which bracket applied (recomputed if the notional at liquidation falls in another bracket) |
Isolated wallet assumed | Margin minus the whole opening fee: the safer assumption |
Liquidation | The bot's figure, with and without the learned offset. The old estimate is shown for comparison only |
Required room | The buffer between the stop's fill and liquidation: the larger of 8% of margin and 10 ticks, plus the offset |
Closest stop | The closest stop to liquidation the bot would accept at this leverage |
wall_pct stop | With --wall-far: the Wall % stop and whether it passes. NOT SAFE means the planner would try a lower leverage |
Fees | Round-trip fees as % of margin, against max_fee_pct_of_margin |
Isolated wallet for stop | The wallet needed to keep that stop plus the buffer safe, and how much margin that would add |
To compare: open Binance Futures, the calculator icon above the order form, Liquidation Price. Choose Isolated and One-way, enter the same side, leverage, entry price and the qty printed, with the isolated margin as the wallet balance.
Testnet check
A scripted run of every order path against Binance's futures testnet (demo-fapi.binance.com). Its request layer refuses every other host, so it cannot reach mainnet. It only reads the Testnet key slot and cleans up any position or order it created.
python scripts\testnet_check.py [--symbol BTCUSDT] [--leverage 20]
| Option | Default | Meaning |
|---|---|---|
--symbol | BTCUSDT | The coin to test on (a tiny position) |
--leverage | 20 | Leverage set on the coin for the test |
- Create a key on demo.binance.com and put some demo USDT in the futures wallet.
- Save it in the Testnet slot (Settings → Account & keys → API keys → Binance).
- Stop the bot that uses this database, so the two do not share the key.
- Run the script. It uses the database in
data\by default. For the Trading instance's key, point it atdata_livefirst, in PowerShell:$env:WALLBOT_DATA_DIR = "C:\wallbot\data_live".
python scripts\testnet_check.py --symbol ETHUSDT
It prints the account's position mode, then one line per step, [PASS] ... or [FAIL] .... A failed step shows Binance's error code and message.
| Step | What PASS means |
|---|---|
| 1 post-only entry placed and cancelled | A maker order far below the market was accepted and its cancel confirmed |
| 2 tiny position opened and its stop appears | A small market position, and its quantity-based stop is visible among the open algo orders |
| 3 stop moved | The new stop is placed and confirmed, and the old one is gone |
| 4 liquidation read and compared | Binance's liquidation price vs the bot's formula, with the error in ticks and % |
| 5 margin added and liquidation re-read | Isolated margin was added and liquidation moved farther away |
| 6 closed at market, position flat | The position closed and nothing is left |
| 7 actual PnL recorded | P&L from the fills matches Binance's income history within 0.01 USDT |
| 8 unknown status resolved without a duplicate | A deliberately "lost" order reply was resolved by its client id, with exactly one order on the exchange |
| H1 to H5 (Hedge Mode accounts only) | A long and a short on one coin, a stop on each side, a take profit armed and moved, both stops moved, both sides closed |
It ends with N/M steps passed and the failed steps. The exit code is 0 when everything passed, 1 when a step failed, and 2 when no testnet key is saved. Every step must pass before you consider live mode; see API keys.
Related
- Troubleshooting: reading skip reasons and the Live learning page.
- Worked examples: the planner's numbers step by step.
- Dashboard: Live learning.