Wallbot

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.

ToolCommandPurposeNetwork
Backtestpython backtest.py download | run | selftestReplay real order books through the same enginedownload: Tardis.dev; run: Binance public 4h candles when sr_filter is on
Wall studypython backtest.py wallstudyHow walls behave when touched: held, broke, pulled, penetration, flowBinance public candles, and exchangeInfo if --tick is omitted
Flow studypython backtest.py flowstudyHold rates by flow measurement; proposes and validates a flow_filternone
Coin studypython backtest.py coinstudyHold rates by coin trait; proposes scanner thresholdsnone
Live reportpython backtest.py livereportThe live learning log (items a to m) as a report and CSVnone
Liquidation calculatorpython liq_calc.pyWhat the bot computes for one position, to compare with Binance's calculatorBinance public exchangeInfo; with --use-saved-key read-only signed calls
Testnet checkpython scripts\testnet_check.pyPASS/FAIL of every order path on Binance's futures testnetBinance 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:

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]
OptionMeaning
--symbolRequired. Binance symbol, e.g. BTCUSDT
--datesRequired. One or more days. Days other than the 1st of a month are skipped without a key
--api-keyTardis.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).

OptionDefaultMeaning
--symbolrequiredThe real symbol (also for recorded files with ASCII-safe names)
--book, --tradesall files foundExplicit data files (several allowed)
--tick, --steprequiredPrice tick and quantity step
--min-notional5.0Exchange minimum order value in USDT (BTCUSDT: 50)
--max-leverage125The coin's exchange maximum; an assumption without the bracket table
--mmr0.004Maintenance margin rate of the first bracket
--maker-fee, --taker-fee0.0002, 0.0005Fees as fractions (0.02%, 0.05%)
--balance100.0Starting balance in USDT. Use 1000 or more on BTC, or positions round down to nothing
--setnoneSetting overrides, e.g. --set entry_model=loss_budget leverage=20 (validated like the dashboard)
--book-step-ms1000Book sampling interval (live sees 100 ms updates)
--cancel-latency-ms300Time a cancel takes to land; fills meanwhile count
--slippage-bps5.0Slippage on stops and market exits
--max-gap-s60.0A data gap longer than this closes everything and starts a new segment
--outbacktest_resultsOutput folder
--contract-size1.0Execution exchange: base units per contract (MEXC BTC_USDT: 0.0001)
--primary-exchange, --primary-tick, --primary-contract-sizebinance, tick, 1.0Two-exchange runs: the exchange in --book/--trades
--alt-exchange, --alt-book, --alt-trades, --alt-tick, --alt-contract-sizenoneA second book source, e.g. mexc
--execthe primaryExecution 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

LineMeaning
Wallbot backtest: SYMBOL, N days of data in S segment(s), E eventsHow much data was replayed. More than one segment means gaps split the data
Settings, AssumptionsThe effective settings and the simulation assumptions (book step, cancel latency, slippage, fees). Keep them with your results
Balance, ReturnStart and end balance, total return and return per day
Trades ... win rateClosed trades and the share with a positive result
Avg win / lossAverage result of winning and losing trades in USDT
Profit factorSum of wins divided by the sum of losses
Max drawdownLargest fall from a balance peak, in %
Leverage usedMinimum, 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 strategyPrinted 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:

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]
OptionDefaultMeaning
--symbolrequiredThe coin
--ticklooked upPrice tick; read from Binance exchangeInfo when omitted
--liveoffUse the bot's recordings (see --live-dir) instead of downloaded files
--live-dirbacktest_data\liveFolder of recorded files
--book, --tradesall files foundExplicit files
--bounce-pct0.5Held once price moves this far (%) away from the wall
--break-pct0.5Broken once price goes this far (%) past the far edge
--timeout-h4.0A touch unresolved after this long counts as unresolved
--outbacktest_results/wallstudyOutput folder
--groupallcore 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 fieldMeaning
confirmed, touched, gone_before_touchWalls confirmed; touched by a trade while still there; gone before any touch
all, on_level, off_levelThe same counts for all touched walls, those at a 4h level, and those not at one
held, broke, unresolved, pulledOutcomes of the touches
hold_rate_pctheld / (held + broke), in %
held_penetration_ticks, held_penetration_pctFor held walls: how far price went past the far edge (median, p75, p90). Useful for judging the stop distance
held_no_penetration_pctShare of held walls that price never went past
flow_bucketsHold 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
coinCoin 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]
OptionDefaultMeaning
--dirsbacktest_results/wallstudy_flow_liveFolders with *_wallstudy_summary.json / _walls.json
--discovery-frac0.7Share of the dates used for discovery
--split-datenoneEarlier dates are discovery (overrides the share)
--record-coins15Coins recorded, for the "weeks until 30 walls" estimate
--outbacktest_results/flowstudyOutput folder (flowstudy.json)
--groupallOnly walls on days the coin was core or movers
python backtest.py flowstudy --split-date 2026-09-25

Reading the flow study

ColumnMeaning
bucket / setThe range of the measurement, or which walls (discovery, validation, validation baseline)
walls, heldWalls in the bucket, and how many held
hold rateheld / walls
95% CIWilson 95% interval of the hold rate. Wide intervals mean too little data
fav 30m median / p75The largest favourable move within 30 minutes, median and 75th percentile, in %
noteunder 30: too few walls to trust

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).

ColumnMeaning
touched, hold rate, 95% CITouched walls (held or broke), hold rate and its Wilson interval
spread bpsMedian 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/band15-minute ATR as % of price, and divided by the middle of the wall distance band
max lev, 1st bracketHighest leverage, and the notional cap of the first bracket
corr BTCCorrelation of 15m returns with BTC
confirmed/day, pulled, touch rateConfirmed walls per day, share pulled, share touched
fav after holdMedian favourable move after a hold, in %
noteunder 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]
OptionDefaultMeaning
--datadata_liveThe instance's data folder; its wallbot.db is opened read-only
--outbacktest_results/livereportOutput folder
--alloffInclude 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]
OptionDefaultMeaning
--symbol, --side, --entry, --leverage, --marginrequiredThe position: side long or short, entry price, leverage, initial margin in USDT
--stopnoneA stop price to check and size margin for
--wall-farnoneThe wall's far edge: also prints the Wall % stop and whether it is safe
--mmr, --cum0.004, 0Assumed bracket without a key (right only for small positions in the first bracket)
--maker, --taker0.0002, 0.0005Assumed fees without a key
--slippage-bpsyour settingStop slippage; defaults to paper_slippage_bps
--use-saved-keyoffUse 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
LineHow to read it
First lineThe 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 usedWhere the maintenance rate came from, and which bracket applied (recomputed if the notional at liquidation falls in another bracket)
Isolated wallet assumedMargin minus the whole opening fee: the safer assumption
LiquidationThe bot's figure, with and without the learned offset. The old estimate is shown for comparison only
Required roomThe buffer between the stop's fill and liquidation: the larger of 8% of margin and 10 ticks, plus the offset
Closest stopThe closest stop to liquidation the bot would accept at this leverage
wall_pct stopWith --wall-far: the Wall % stop and whether it passes. NOT SAFE means the planner would try a lower leverage
FeesRound-trip fees as % of margin, against max_fee_pct_of_margin
Isolated wallet for stopThe 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]
OptionDefaultMeaning
--symbolBTCUSDTThe coin to test on (a tiny position)
--leverage20Leverage set on the coin for the test
  1. Create a key on demo.binance.com and put some demo USDT in the futures wallet.
  2. Save it in the Testnet slot (Settings → Account & keys → API keys → Binance).
  3. Stop the bot that uses this database, so the two do not share the key.
  4. Run the script. It uses the database in data\ by default. For the Trading instance's key, point it at data_live first, 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.

StepWhat PASS means
1 post-only entry placed and cancelledA maker order far below the market was accepted and its cancel confirmed
2 tiny position opened and its stop appearsA small market position, and its quantity-based stop is visible among the open algo orders
3 stop movedThe new stop is placed and confirmed, and the old one is gone
4 liquidation read and comparedBinance's liquidation price vs the bot's formula, with the error in ticks and %
5 margin added and liquidation re-readIsolated margin was added and liquidation moved farther away
6 closed at market, position flatThe position closed and nothing is left
7 actual PnL recordedP&L from the fills matches Binance's income history within 0.01 USDT
8 unknown status resolved without a duplicateA 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.