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.
| Setting | Default | What it does |
|---|---|---|
safety_total_loss_usdt | 5 USDT | When 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_usdt | 2 USDT | The same per UTC day; trading can start again the next day. |
safety_balance_cap_usdt | 0 (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.
- Before every entry on Binance, the bot reads the coin's margin type, switches it to ISOLATED if needed and reads it back. If that fails, the wall is skipped and the reason logged.
- After every fill it reads the position back. If it is not isolated or cannot be confirmed, the bot closes it at market, pauses entries and logs a critical event.
- Multi-Assets mode does not allow isolated margin, so the bot refuses to start in it and says so.
- Auto-add margin is never switched on. The dashboard warns if you turned it on in the exchange app.
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:
- Never changed under its own orders. With
leverage_hold_while_restingon (default), Wallbot never changes a coin's leverage while it has its own resting entry or open position there. - Read before every entry. With
verify_leverage_before_entryon (default), Wallbot reads the coin's real leverage on Binance before every entry, re-place and re-plan. If it differs from the plan, it sets the planned leverage again, but never under its own resting order or open position. If Binance refuses or allows less, the entry is not placed and the next evaluation plans at the leverage Binance allows, with margin, liquidation and every check recomputed. - Changes made outside Wallbot are reported. A leverage different from the one Wallbot last set sends "LEVERAGE CHANGED coin: Ax -> Bx", at most once per coin per hour.
- Maximum leverage refreshed. Binance's per-coin maximum leverage (your account's leverage brackets) is re-read every
leverage_bracket_refresh_min(60 minutes), and at once after a leverage mismatch or a leverage-related rejection. A changed maximum on a watched or traded coin sends "MAX LEVERAGE coin: Ax -> Bx". - Reserved margin compared with the plan. In testnet and live, while Wallbot has orders or positions, every
margin_check_interval_s(60 s) it compares the margin Binance reserves per coin with the planned margin. More thanmargin_reserve_alert_pct(20%) above plan sends a high-priority "MARGIN coin: x reserved vs y planned" alert, at most once per coin per hour. Nothing is cancelled or closed.
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.
- Quantity-based close stops, never
closePosition. Each stop is a STOP_MARKET order for the position's quantity:reduceOnlyin One-way Mode, orpositionSidewith the opposite side in Hedge Mode. Binance allows only oneclosePositionstop per direction (error-4130), which would make a safe stop move impossible. - Moves never leave a gap. To move a stop, the bot places the new one, waits until Binance confirms it is live, and only then cancels the old one. If the new stop is not confirmed, the old one stays.
- Resizing. When the position size changes (a partial take-profit fill, for example), the stop is replaced at the same price with the new quantity, in the same order.
- Trigger price.
stop_triggerchooses last price or mark price.
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:
- the stop is placed;
- Binance's own liquidation price is read;
- if the stop is not safely before it, isolated margin is added once, at most
max_added_margin_pct(50%) of the original margin; - 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 exchange | What the bot does |
|---|---|
A wb order that no trade tracks (a lost order), older than 15 s | Cancels 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 tracks | Adopts 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 confirm | Retried 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:
- Entry fills are recognised by the bot's own list of order ids, not by the client-id prefix (
fill_route_by_registry). The old prefix test mistook about 1 in 16 entry orders, those with ids startingwbc, for close orders and dropped their fills. - When cancelling an entry finds it already filled, the bot applies the fill at once and places the stop (
adopt_fill_on_cancel). - On every user-data reconnect or key renewal, each pending entry's order status is read from Binance: a filled one is applied at once, a cancelled one is closed (
reconnect_order_status_check).
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:
- new entries pause until signed requests have been clean for
key_stable_minutes(10 minutes); - every resting entry is cancelled at the first request that gets through; stops are never cancelled;
- while it is engaged and a position is open, that position's stop on Binance is checked every 15 s, with high-priority alerts until it is confirmed.
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.
- It skips any coin where the account has a position, open orders or conditional orders it did not create.
- A position mixed with manual trading (the size does not match the bot's fill) is reported with "MIXED POSITION" but not touched.
- Margin used by positions or orders it did not open is reported on the dashboard as a warning.
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
- No withdrawal permission. Never enable withdrawals on a key you give the bot. GO LIVE is refused if withdrawals are enabled.
- Futures trading only. Enable futures; nothing else is needed.
- IP restricted. Bind the key to your PC's or server's IP. GO LIVE is refused without an IP restriction. If your IP changes, add the new one; never remove the restriction.
- One key per instance. Create a separate, new key for the Trading instance. Keep the read-only key on Research only. The bot warns if both use the same key.
- Multi-Assets mode off. Isolated margin needs Single-Asset mode.
- Keys stay encrypted. They are stored encrypted, shown only masked, and never written to logs or the settings history.
The full checklist is in Instances and modes.