Wallbot

Instances and modes

Wallbot runs as two separate instances on one PC or Linux VPS, Research and Trading. Each one can be in Paper, Testnet or Live mode. This page explains how they differ, how you switch modes and which API key goes where.

Two instances, one folder

Both instances run from the same C:\wallbot folder and the same code. They do not share data: each has its own database, its own dashboard password, its own settings and its own log. Think of them as two separate bots that happen to live in one folder.

ResearchTrading
Dashboardhttp://127.0.0.1:8787http://127.0.0.1:8788
Start withstart_wallbot.batstart_wallbot_live.bat
Data folderdata\data_live\
Log filelogs\wallbot.loglogs\wallbot_live.log
Records market dataYes, when record_market_data is onNever, whatever the setting says
Wall-flow log and studiesYesNo
Usual modePaperPaper, then Testnet, then Live

On a Linux VPS

Both instances can also run on a Linux VPS, which keeps the Trading instance up when your PC is off. There wallbot.sh starts each one in its own tmux session, under the same launcher (see Getting started). Only the names differ:

On the VPSResearchTrading
Dashboardhttp://127.0.0.1:8787 through an SSH tunnelhttp://127.0.0.1:8788 through an SSH tunnel
Start with./wallbot.sh start research./wallbot.sh start live
Stop with./wallbot.sh stop research./wallbot.sh stop live
tmux sessionwallbot-researchwallbot-live
Data folderdata (for example /wallbot/data)data_live (for example /wallbot/data_live)
Log filelogs/wallbot.loglogs/wallbot_live.log

Never run the same instance on the PC and on the VPS at the same time: they would trade the same account from two databases. How to view the dashboards and how to update the code on a VPS is in Daily operation.

The header shows which instance you are looking at, for example "Research · 8787" or "Trading · 8788". You can change the name with instance_name; empty means automatic. The browser tab title also shows the name and the mode.

Research (8787)

Research is the learning and data-collection bot. It trades in paper mode on real market data and, with recording on, saves the order book and trades of the watched coins to backtest_data\live\. Every day it runs becomes another day you can backtest. It also writes the wall-flow log used by the studies.

Trading (8788)

Trading is the bot that may one day place real orders. The launcher sets its port, data folder and log through environment variables, so it never touches Research's database. It never records market data, because recording costs disk and memory and has nothing to do with placing safe orders.

On its very first start it applies small, careful defaults (recorded in the settings history as "system"):

Trading always shows the "Live learning" panel, even in paper mode, so you can run the safety checklist before you go live.

Separate logins per port

Browsers share cookies between ports on 127.0.0.1. If both instances used one cookie, signing in to one would sign you out of the other. So each instance has its own session cookie, wb_session_8787 and wb_session_8788. You can keep both dashboards open in the same browser. Each one still asks for its own password.

Paper, Testnet and Live

The mode is set per instance under Settings → Account & keys → Mode. One set of trading settings drives every mode: there are no separate copies of margin, max trades or other risk values for each mode. The only mode-specific settings are the Live safety caps (see Safety rules).

ModeOrders go toMarket data fromKey used
PaperNowhere: fills are simulatedThe real exchangeNone needed. A saved Live key is used read-only for brackets and fees
TestnetBinance futures test environment (demo-fapi)Binance mainnet (the real walls)The Testnet slot
LiveThe real exchange, real moneyThe real exchangeThe Live slot

Testnet still reads walls from the real Binance book, because the test book is thin and meaningless. Only orders go to the test environment, and every request to any other host is refused locally. MEXC has no futures test environment, so its testnet shows as "not available".

In testnet and live, a paper "shadow" runs inside the same instance on the same data. It never places orders. It lets you compare real fills and results with what paper would have done.

The mode pill at the top reads "Paper trading", "Testnet trading" or "Live trading". Notification titles start with [Wallbot PAPER], [Wallbot TESTNET] or [Wallbot LIVE].

How you switch

Only you switch modes. Every switch is written to the settings history and sent as a notification ("Mode switched to LIVE"). The bot refuses to switch while it has active trades: close or cancel them first.

To switch to Testnet or Live, all of these must be true:

  1. a key is saved in that mode's slot for the execution exchange;
  2. that key is enabled;
  3. "Test connection" on that key passed within the last hour.

Live adds two more steps:

  1. you type GO LIVE in the confirmation box;
  2. the API key safety checklist runs at that moment and every blocking item must be green.

The GO LIVE checklist

The checklist uses read-only calls with the key saved in the Live slot right now, against Binance mainnet. You can also run it any time with "Run safety check" on the Live learning page.

ItemMust showWhy
Withdrawals disabled on the keydisabledA stolen key can then never move money out
Futures trading enabled on the keyenabledThe bot cannot trade without it
Key restricted to trusted IPsIP-restrictedA key copied to another machine is useless
Multi-Assets mode offoffBinance does not allow isolated margin in Multi-Assets mode
Position mode detectedHedge Mode or One-way ModeOrders are built differently in each
Isolated margin readable (positionRisk)position rows readableThe bot must be able to check its positions
Checked against Binance mainnetyesThe check must be about the real account
A separate key from the Research instance'sdifferent keyWarning only (not blocking), compared by fingerprint

Warning. Live mode places real orders with real money, using your current risk settings. Run paper and testnet first, and only fund the account with an amount you can afford to lose.

Credential slots: which key goes where

Settings → Account & keys → API keys has two slots per exchange: "Live key" and "Testnet key" (MEXC has the Live slot only). Each slot has its own "Enabled" switch, "Save", "Test connection" and "Remove". Keys are encrypted on disk and shown only masked. The slot used by the running mode is marked "IN USE".

InstanceLive slotTestnet slot
Research (8787)Optional: a read-only key. Paper mode uses it only to read leverage brackets and fee ratesNot needed
Trading (8788)A separate, new key: futures trading on, withdrawals off, restricted to your IPA key from demo.binance.com for testnet runs

In paper mode a saved Live key is used strictly read-only: the client refuses every signed request that is not a GET. Without any key, paper mode assumes one leverage bracket and default fees, and the dashboard says so.

Each instance stores a one-way fingerprint of its saved keys, never the key itself. If Trading's Live key is the same as Research's, Trading warns on its dashboard and in the checklist. Use two different keys so that a problem with one bot never affects the other.

Tip. Back up data\ and data_live\. Each holds a secret.key file. Without it, the saved keys cannot be decrypted and must be entered again.

IP whitelist and the key-rejected alert

Restrict every trading key to your PC's or server's public IP. If your IP changes (a new router, a VPN, a different network), Binance rejects the key with error -2015 ("invalid API key, IP or permissions").

In testnet and live

The key guard

With key_unstable_guard on (the default), testnet and live go further. A single -2015, or 3 -1021 clock rejections within a minute (key_unstable_1021_burst), engage the guard:

In paper mode

If the read-only key is rejected, paper trading continues on the brackets, fee rates and max leverages cached while the key worked. With nothing cached it uses assumed values. A "BINANCE KEY REJECTED (IP ...)" notification goes out at most once an hour. The key is retried every key_retry_s (600 s), and "BINANCE KEY OK AGAIN" is sent when it works again.

To fix either case, add the reported IP to the key's allow-list on Binance. Do not remove the IP restriction.