Wallbot

Safety rules

The rules Wallbot follows to limit losses and keep every position protected. They cover loss caps, isolated margin, leverage checks, stops on the exchange, liquidation checks, reconciliation, the key guard, safe shutdown, what the bot never touches, and how to set up API keys.

Warning. These rules reduce risk. They do not remove it. High-leverage futures can lose a trade's whole margin quickly, and gaps, slippage, exchange outages or bugs can make a loss larger than planned. Trade only with money you can afford to lose.

Loss caps

Daily loss limit (every mode)

daily_loss_limit_pct (10%) pauses new entries once today's realized loss reaches that share of the day's starting balance. The day is the UTC day. Pending entries are cancelled; open positions keep their stops. The pause lifts by itself at the next UTC day, when you press "Resume entries", or when you reset today's loss count (below). It is not kept across a restart.

Example

Illustrative numbers. The day starts with 200 USDT. At 10%, the limit is 200 × 10% = 20 USDT. After closed trades total −20 USDT or worse, the bot opens nothing new until 00:00 UTC.

Live safety caps (live, and testnet if you choose)

Settings → Risk & safety holds the only mode-specific settings. They always apply in live mode, and in testnet when safety_in_testnet is on. You can adjust them within limits, but you can never switch them off.

SettingDefaultWhat it does
safety_total_loss_usdt5 USDTWhen the realized loss since the count started reaches this, no new trades are opened, a "TRADING STOPPED: loss cap reached" notification is sent, and the bot waits for you.
safety_daily_loss_usdt2 USDTThe same per UTC day; trading can start again the next day.
safety_balance_cap_usdt0 (no cap)Sizing uses the smaller of the available balance and this cap, so money you deposit for manual trading does not make the bot's trades bigger.

After you have reviewed what caused a stop, "Count losses from now" on the Live learning page restarts the count (type RESET).

Realized P&L in these caps includes each trade's funding fees (include_funding_in_pnl). In live and testnet, every close is checked against Binance's fills, commissions and funding (validate_close_with_binance). When Binance's values differ, they become the record: the daily totals and the loss caps use them at once, and a "TRADE CORRECTED" notification names the difference.

Reset today's loss count

"Reset today's loss count" on the Live learning page (daily_loss_reset_button, on) starts today's count again from zero, both for the live safety daily cap and for the daily loss limit. If the daily loss limit had paused entries, that pause lifts. The cap values, the total count and any manual pause stay as they are. In live mode you type I ACCEPT. Each reset is recorded in Settings → History and sent as a "Daily loss count reset (by owner)" notification (email_on_loss_reset).

Example

Illustrative numbers. Available balance 80 USDT, balance cap 30 USDT, margin per entry 10%. Sizing uses min(80, 30) = 30 USDT, so each entry uses 30 × 10% = 3 USDT of margin.

In live mode, any change that loosens risk, such as raising margin, leverage, max trades or a loss cap, asks you to type I ACCEPT. Tightening saves at once. Every change is in Settings → History.

Isolated margin on every trade

Every bot trade uses isolated margin, so one trade can never draw on other positions or the rest of the balance. The most a trade can lose is its own margin plus fees, except when a gap makes the exit worse than the liquidation price.

Isolated margin caps each trade's loss, but every open trade's margin still comes out of your available balance. With several trades open, their margins add up.

Leverage checked against Binance

Binance sets leverage per coin, and changing it re-margins any resting order or open position on that coin. Wallbot therefore guards the leverage it plans with:

Warning. The most likely cause of a leverage change outside Wallbot is the Binance app's default-leverage setting on the futures screen, which can overwrite the per-coin leverage Wallbot sets. Turn that setting off, and do not change leverage in the Binance app on coins Wallbot trades while it runs. Trade other coins manually instead.

Stops always on the exchange

The stop is placed on the exchange the moment an entry fills. If the exchange refuses it, the bot closes the position at market. A stop that lives on the exchange still works if the bot, the PC or the internet connection stops.

Liquidation checks

Wallbot computes the liquidation price with Binance's published formula for isolated USDⓈ-M positions, in the planner, the paper broker and the backtester alike:

long:  LP = (Qty × EP − WB − cum) / (Qty × (1 − MMR))
short: LP = (Qty × EP + WB + cum) / (Qty × (1 + MMR))
EP = entry price, WB = the position's isolated wallet,
MMR and cum = maintenance rate and amount from the leverage bracket

Every stop must fill before liquidation, even after slippage, by at least liq_buffer_pct_of_margin (8% of margin) plus a learned safety offset. Leverage steps down until that holds.

The slippage used here is paper_slippage_bps (5 bps) until a coin has observed_slippage_min_samples (5) live stop fills. From then on, with observed_slippage on (default), it is the observed_slippage_pct (90th) percentile of that coin's real stop-fill slippage, never less than paper_slippage_bps. It changes the leverage and the liquidation buffer, not where the entry or the stop is placed. The value used is logged with each trade.

How it was checked. Automated tests reproduce both worked examples in Binance's article. The testnet check script (scripts\testnet_check.py) opens a tiny position, reads Binance's own liquidation price, compares it with the formula, adds margin and re-reads it. It passed in both One-way and Hedge Mode on the Binance testnet.

After a live fill, in this order:

  1. the stop is placed;
  2. Binance's own liquidation price is read;
  3. if the stop is not safely before it, isolated margin is added once, at most max_added_margin_pct (50%) of the original margin;
  4. if it is still unsafe, the stop moves inward; if that would put it in front of the wall, the position is closed at market and entries pause.

Every live fill teaches the safety offset. Increases apply automatically; decreases are only proposed on the dashboard and wait for your "Approve".

Reconciliation

In testnet and live, the bot compares the exchange with its own records every 60 s (reconcile_interval_s), soon after any exchange error, and after every restart or reconnect. Every bot order carries a client id starting with wb.

Found on the exchangeWhat the bot does
A wb order that no trade tracks (a lost order), older than 15 sCancels it on the priority lane and logs it. "LOST ORDER" alert if the cancel is not confirmed.
A real position whose trade is still "pending" (a missed fill)Takes it over with its stop after missed_fill_after_s (10 s), without a restart (reconcile_missed_fills).
A position from a Wallbot order that no trade tracksAdopts it with its planned stop if that stop is still valid (right side of price, before liquidation, behind the wall); otherwise closes it at market. Notified either way.
A bot position with no confirmed stop"UNPROTECTED POSITION" alert (at most every 10 minutes) and a dashboard warning (unprotected_alert).
An entry cancel the exchange did not confirmRetried after 1, 2, 5 and 10 s, then every 30 s, until confirmed cancelled, filled or absent. Alert after 60 s.

Uncertain order replies (a timeout, HTTP 503 or -1007) are resolved by asking Binance about that client id. The bot resends only after Binance confirms the order does not exist, so orders are never duplicated.

Fills are never missed between these passes either:

Unstable key or connection

With key_unstable_guard on (default), in testnet and live, any -2015 (key rejected, for example because your public IP changed) or key_unstable_1021_burst (3) clock rejections (-1021) within a minute engage the key guard:

You get one notification when it engages ("ENTRIES PAUSED: API KEY UNSTABLE") and one when it clears ("ENTRIES RESUMED: API KEY STABLE"), with the IPs Binance reported. See Key rejected.

Safe shutdown

On every shutdown in testnet and live (safe_shutdown), and on "Prepare to stop", the bot pauses entries, waits for order actions in progress (up to safe_stop_timeout_s, 30 s), cancels and confirms every resting entry, and leaves open positions with their exchange stops. Stops are never cancelled on the way out. If it cannot finish safely, it sends "NOT SAFE TO STOP" and records the reason; it never exits silently. See Prepare to stop.

"Prepare to stop" and "Pause entries" are kept across a restart (persist_manual_pause): the bot starts paused and only "Resume entries" lifts it. A plain shutdown runs the same safe-stop steps but does not keep a pause, so the next start is not paused unless you pressed one of those buttons first.

After an unplanned server restart, when the @reboot crontab entry starts the Trading instance, new entries start paused (reboot_start_paused, on) and a high-priority "VPS rebooted" notification goes out (email_on_reboot). Only "Resume entries" lifts that pause.

What the bot never touches

Orders and positions without the wb prefix are yours. The bot never cancels, moves or closes them.

Tip. Manual trading on the same coins blocks the bot on those coins. A separate account or sub-account for the bot, where possible, keeps both clean.

API key rules

The full checklist is in Instances and modes.