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.
| Research | Trading | |
|---|---|---|
| Dashboard | http://127.0.0.1:8787 | http://127.0.0.1:8788 |
| Start with | start_wallbot.bat | start_wallbot_live.bat |
| Data folder | data\ | data_live\ |
| Log file | logs\wallbot.log | logs\wallbot_live.log |
| Records market data | Yes, when record_market_data is on | Never, whatever the setting says |
| Wall-flow log and studies | Yes | No |
| Usual mode | Paper | Paper, 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 VPS | Research | Trading |
|---|---|---|
| Dashboard | http://127.0.0.1:8787 through an SSH tunnel | http://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 session | wallbot-research | wallbot-live |
| Data folder | data (for example /wallbot/data) | data_live (for example /wallbot/data_live) |
| Log file | logs/wallbot.log | logs/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"):
- margin per entry 10%, at most 1 trade, no second side, no movers group;
- allowlist
XRPUSDT,DOGEUSDT, with the affordability filter on; - a paper balance of 10 USDT;
- Paper mode. It never switches mode by itself.
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).
| Mode | Orders go to | Market data from | Key used |
|---|---|---|---|
| Paper | Nowhere: fills are simulated | The real exchange | None needed. A saved Live key is used read-only for brackets and fees |
| Testnet | Binance futures test environment (demo-fapi) | Binance mainnet (the real walls) | The Testnet slot |
| Live | The real exchange, real money | The real exchange | The 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:
- a key is saved in that mode's slot for the execution exchange;
- that key is enabled;
- "Test connection" on that key passed within the last hour.
Live adds two more steps:
- you type
GO LIVEin the confirmation box; - 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.
| Item | Must show | Why |
|---|---|---|
| Withdrawals disabled on the key | disabled | A stolen key can then never move money out |
| Futures trading enabled on the key | enabled | The bot cannot trade without it |
| Key restricted to trusted IPs | IP-restricted | A key copied to another machine is useless |
| Multi-Assets mode off | off | Binance does not allow isolated margin in Multi-Assets mode |
| Position mode detected | Hedge Mode or One-way Mode | Orders are built differently in each |
| Isolated margin readable (positionRisk) | position rows readable | The bot must be able to check its positions |
| Checked against Binance mainnet | yes | The check must be about the real account |
| A separate key from the Research instance's | different key | Warning 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".
| Instance | Live slot | Testnet slot |
|---|---|---|
| Research (8787) | Optional: a read-only key. Paper mode uses it only to read leverage brackets and fee rates | Not needed |
| Trading (8788) | A separate, new key: futures trading on, withdrawals off, restricted to your IP | A 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
- While rejections happen, the dashboard shows a banner.
- After 3 rejections within a minute (
key_rejected_threshold), you get a critical notification "BINANCE KEY REJECTED (-2015)". It lists the request IPs that Binance reported, so you know exactly which IP to add. - It repeats at most once every 15 minutes (
key_rejected_alert_min). An IP never seen in a rejection before is reported at once, with ": new IP" in the subject. - Live mode never falls back to assumed values: with a rejected key it does not trade.
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:
- New entries pause. You get one notification, "ENTRIES PAUSED: API KEY UNSTABLE", with the IP Binance reported.
- At the first signed request that gets through, every resting entry is cancelled. Stops are never cancelled.
- While the guard is engaged and a position is open, its stop on Binance is checked every 15 seconds, with high-priority alerts until it is confirmed.
- Once signed requests have been clean for 10 minutes (
key_stable_minutes), entries are allowed again and you get "ENTRIES RESUMED: API KEY STABLE".
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.