Installation Guide

Create an account at your chosen provider. Deploy a new server with these specs:

💡 The installer automatically adds a 2 GB swapfile so the weekly ML retrain has headroom on a 2 GB VPS — no manual step needed.

Once your VPS is running, connect to it. Your provider will email you the IP address and root password, or you can use SSH keys (recommended).

ApexQuant's systemd service auto-restarts after reboot. Open positions are persisted in the local database and restored automatically. No manual intervention needed.

Ubuntu can apply security patches automatically without manual apt upgrade. This catches critical patches between your monthly checks.

Note: kernel updates require a reboot to take effect. Unattended-upgrades will install them but won't reboot automatically. Schedule a monthly maintenance window to apply pending kernel updates and reboot.

Subscribe to your VPS provider's security mailing list or status page. Apply critical kernel patches within 48 hours of release for high-severity CVEs.

• Vultr: status.vultr.com
• DigitalOcean: status.digitalocean.com
• Linode: status.linode.com
• AWS Lightsail: health.aws.amazon.com
• Ubuntu security advisories: ubuntu.com/security/notices

Setup takes about 5 minutes:

1. Sign up at dash.cloudflare.com (free, no credit card needed).
2. In your Cloudflare dashboard sidebar, find Turnstile. Click Add widget.
3. Widget name: e.g., "ApexQuant Login"
4. Hostname: Enter your root domain (e.g., yourdomain.com). Turnstile automatically covers all subdomains — so the widget works on app.yourdomain.com, bot.yourdomain.com, or any subdomain you choose later, with no reconfig needed.
5. Widget mode: Select Managed (recommended — Cloudflare auto-decides when to challenge).
6. Click Create. Cloudflare displays your sitekey and secret key.
7. Add both keys to your bot's .env file:

Easiest: run apexquant --config-gui (guided, no file editing). To edit manually instead:

Verification: visit your dashboard login URL. You should see a Turnstile widget below the password field. Without solving the challenge, login is rejected.

There are two backup types:

• Routine backup — trading state + settings only: trade history, open positions, DCA baskets, grid state, settings, equity snapshots, baseline, and profile. Credentials (.env) are excluded. This is the default and the safer choice for regular backups.
• Migration backup — everything above plus your credentials (.env: Binance API key/secret, Telegram token, etc.), passphrase-protected. Use this when moving to a new server and you want a near-complete restore.

Your license key is never in any backup — for security we don't store it in a form we can read, and we can't resend it. Keep your purchase email from {email} or a printout; you'll paste the key during setup.

In the dashboard: Settings → Backup & Restore → Create Backup. Enter a strong passphrase (store it safely — a lost passphrase means the backup is unreadable). Choose scope (Essential recommended). Click Download Backup. Store the .aqbackup file somewhere safe (offline storage recommended).

Restore stages the switch — it no longer refuses when positions are open. The engine boots in Restore Review mode (PAUSED) so you can review the state before resuming.

1. Upload & restore — dashboard Backup tab → upload your .aqbackup file + passphrase.
2. Restore Review mode: trading is PAUSED, no entries or exits fire.
3. Review the reconciliation report — the dashboard shows a banner with a report comparing the restored bookkeeping against live exchange holdings. Resolve any flagged orphans (adopt or sell).
4. Recover trade history (optional) — use the Recover trade history from exchange section in the banner. Click Preview to see which ApexQuant-placed trades occurred after the backup, then Apply to import them and replay PnL. Only trades with an aq_ client order ID are imported — your manual trades are never touched.
5. Resume — click Resume Trading when satisfied.

What gets restored / recovered / not restored:

Restore ≠ software update. To update the bot software on the same VPS, use Mode A (code-only) deploy — pull the new code and restart. No backup/restore involved. Back up your DB before any major update as a precaution.

Visit apexquant.tech/download and complete the challenge to get the latest ApexQuant setup zip.

From your local machine:

SSH into your VPS, then:

The installer will:

• Set up Python 3.12 venv + all dependencies
• Prompt for your license key — or skip for 30-day trial (paper/testnet)
• Ask about domain: YES → nginx + free Let's Encrypt SSL; NO → VPS IP on port 5005
• Configure systemd auto-start (restarts on reboot)
• Start the bot in paper mode — safe, no real orders

After install, the terminal shows your dashboard URL and PIN. Note them.

• Everything you can configure (trading mode, strategy, capital, risk, AI settings, and everything else in the Bot Config tab) — all set in the dashboard, never in .env. This is the only documented way to change these.
• The 13 keys that genuinely only live in .env — Binance API keys (spot and futures), the dashboard password, the admin PIN, the session secret, the FRED API key, the Telegram token and chat ID, the Turnstile site key and secret, and the server timezone. These are secrets or one-time setup values — managed through the setup wizard or apexquant --config-gui, never through the Bot Config tab.

If you edit .env directly (e.g. with nano) for a Binance key, Telegram token, or another of the 13 .env-only values, restart the bot to load the change:

apexquant --config-gui prompts a bot restart after saving — no manual restart needed.

Beyond the 13 keys above, seven more settings genuinely only live in .env — they govern automatic halt protection or low-level server behavior, and are deliberately kept out of the Bot Config tab so they cannot be loosened accidentally from the dashboard. Most installs never need to touch these; they exist for operators who understand the consequences of changing them.

1. Go to Binance API Management.
2. Create a new API key (type: System Generated).
3. Enable: Enable Spot & Margin Trading.
4. Disable: Enable Withdrawals — must be OFF.
5. Set IP restriction: whitelist your VPS IP address.
6. Save your API Key and Secret — the Secret is shown only once.

Only for the Funding Rate Harvest module. Binance has conditions for turning Futures on (an account opened first, a new key, the server's IP, no portfolio margin): see Funding Rate Harvest and the FAQ. Enter the keys via apexquant --config-gui (Binance panel).

See also: Step 4b — Binance Sub-account (recommended for stricter isolation).

The script prompts for API key, secret, and (optionally) a separate futures key. It writes them to .env and restarts the bot.

Sub-account creation is done from the Binance web UI. The exact menu path varies by account type and region. Use the official guide:

Binance: How to create sub-accounts →

Once the sub-account exists, create an API key on the sub-account (not your main account) using the same settings as Step 4:

• Enable: Spot & Margin Trading
• Disable: Withdrawals — must be OFF
• IP whitelist: your VPS IP

Then load the sub-account API key via apexquant --config-gui (Binance panel).

ApexQuant listens for your order fills in real time over a Binance connection called the order-update stream. Binance is moving that connection toward a newer, asymmetric key type called Ed25519 — it's faster and Binance is investing in it as the long-term standard. Your regular API key (Step 4) still works today and will keep working; setting up an Ed25519 key is simply getting ahead of that shift on your own schedule, rather than in a hurry later.

Once set up, ApexQuant uses the Ed25519 key automatically for order-update tracking. Your regular API key keeps handling everything else (placing/canceling orders, checking balances) exactly as before — nothing changes there.

1. Go to the official Binance Asymmetric Keys Generator guide and download the generator tool from Binance's own site (linked from that page).
2. Run the generator, choose Ed25519 as the key type (it's the default).
3. Generate a new key pair. Save both files — you'll need the private key file in Step 3 below. Never share the private key file with anyone, including us.

1. Go to Binance API Management.
2. Create a new API key, choose type Self-Generated Ed25519 Key when prompted, and paste the public key from Step 1.
3. Enable: Enable Spot & Margin Trading (this key only needs to read order updates, but Binance requires the permission to exist on the key for the subscription to authenticate — it is never used to place, cancel, or modify anything).
4. Disable: Enable Withdrawals — must be OFF, same as every ApexQuant key.
5. Set IP restriction: whitelist your VPS IP address, same as Step 4.
6. Copy the API Key string Binance shows you — this is different from your regular (Step 4) API key.

Open the private key file the generator saved in Step 1. It looks like this:

You need to turn every line break into the two characters \n (backslash, then the letter n) so the whole key becomes one line. The easiest way is a single command on your VPS — this reads the key file and prints the correctly-formatted single-line version for you to copy:

This prints one long line starting with -----BEGIN PRIVATE KEY-----\n and ending with \n-----END PRIVATE KEY-----\n. Copy that entire output — that's the value you'll paste into .env.

Now edit .env directly:

Add two lines (paste the single-line key from the command above — do not add extra quotes around it):

Save, then restart the bot to load the new keys:

Check the bot's own logs shortly after restart:

Look for a line mentioning session.logon succeeded and, shortly after, subscribed. If instead you see a line about falling back to the regular key, double-check the API key string and the private key formatting from Step 3 — the bot keeps trading normally either way, so there's no urgency, but you can fix it and restart again whenever convenient.

1. Open Telegram and start a chat with @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. Copy the token BotFather sends you (format: 123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). Keep it secret — anyone with this token can control your bot.
4. (Optional) Verify the token: open https://api.telegram.org/bot123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/getMe in a browser (replace the example token with your real bot token) — you should see your bot's details in the response. Note: the digits before the colon are your bot's own numeric ID — they're part of the token, not your chat ID. getMe needs no chat ID.

1. Start a chat with @userinfobot — it replies with your numeric chat ID (e.g. 123456789).
2. Alternative: send any message to your new bot first, then open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates and look for "chat":{"id":…} — that number is your chat ID.

The script prompts for your bot token and chat ID, writes them to .env, and restarts the bot. You can also enter Telegram Bot Token (TELEGRAM_TOKEN) and Telegram Chat ID (TELEGRAM_CHAT_ID) in dashboard Settings and save instead.

1. Open dashboard → Profile tab → 🔐 Admin PIN section
2. Leave "Current PIN" blank for your first setup
3. Choose a 4–8 digit PIN. Confirm it. Click Update PIN.

A modal will appear before any of these actions:

Enter PIN → action proceeds. The PIN is remembered for a short while — subsequent actions don’t re-prompt.

For /buy, /sell, /restart commands when PIN is enabled:

You: /buy BTC 25
Bot: 🔒 PIN required. Reply with your 4-6 digit PIN as your next message.
     Send /cancel to abort.
You: 1234
Bot: ✓ PIN verified. [shows BUY preview card]

Set Admin PIN (APEXQUANT_PIN) to a new value in .env (or leave it unset to clear the PIN), add RESET_ADMIN_PIN=1, and restart the bot. Then open dashboard → Profile → Admin PIN to set a fresh PIN, and remove RESET_ADMIN_PIN from .env and restart again. No database editing required.

Every time you open a new terminal session, activate the venv before running any Python commands:

Open your browser and visit:

You should see the bot status, regime indicator, and price feeds. If Telegram is configured, send /status to your bot.

You need a domain or subdomain pointing to your VPS IP. Recommended: use app.yourdomain.com.

Let's Encrypt is free SSL. Certbot automates certificate issuance and renewal.

The dashboard's API Health card on the Live tab monitors connectivity and authentication status for every external service ApexQuant depends on. This is your single-glance early-warning system: if something breaks (Binance API key revoked, License Server unreachable, FRED API key expired), you see it here before trades start failing.

• Binance API — connection + permission audit (LIVE mode only). Alerts if withdrawal permission is enabled (security risk).
• License Server — your ApexQuant license validation server. Required.
• Telegram Bot API — only if you've configured Telegram commands.
• FRED Macro Data — only if you've set FRED_API_KEY (used for macro gate).
• AI Provider — your configured AI Commentary provider (Anthropic, OpenAI, Gemini, DeepSeek, MiMo, or custom — per AI Commentary Provider (AI_PROVIDER)), shown when an AI key is set. Pro & Elite — see the AI Commentary section for the full list.
• TradingView — only for the TradingView webhook strategy (coming soon).
• Fear & Greed Index — sentiment data source (no API key required).
• CoinGecko — market data fallback (no API key required).

The card defaults to a compact summary. Click View details ▾ to expand:

• ✓ All systems operational — every required service is healthy. Green.
• ⚠ ServiceName: warning — something is degraded (e.g., license expiring soon). Yellow.
• ✗ ServiceName: error — a required service is down. Red. Investigate immediately.

Services without API keys show as ○ Not configured — gray, neutral. Informational, not an error.

The ↻ Refresh all button forces a fresh parallel check of every service (~3–5 seconds). Per-service ↻ buttons recheck individual services. Data is cached per-service (5–15 minutes) so the card doesn't hammer external APIs on every page load.

In TESTNET mode (TRADING_MODE=TESTNET), the Binance permission audit shows as informational gray ℹ because Binance testnet doesn't implement the permission endpoint. Expected behaviour — switch to LIVE mode to enable the full audit.

ApexQuant supports safe in-place restarts that preserve all open positions, halt state, and trade history. Use this whenever you change configuration that requires a restart.

1. Go to the Settings tab
2. Scroll to the bottom — Restart Now button
3. Confirm in the popup
4. Enter your 2FA code (if 2FA enabled) or PIN (if APEXQUANT_PIN set)
5. Bot restarts in ~10 seconds, page auto-reloads

Type /restart in your bot chat → tap Confirm → enter your APEXQUANT_PIN → restart triggers. Bot sends a status message once back online.

• Open positions (exit_manager re-attaches on startup)
• Halt state, kill-switch state, daily/weekly DD limits
• Trade history (DB unaffected)
• Pending orders on Binance (Binance-side, not affected)

• Websocket connections to Binance (~3–5 seconds)
• License heartbeat to License Server (~10 seconds)
• Telegram polling thread

Every restart is logged with trigger source and authentication method:

[SYSTEM] Restart scheduled via dashboard by web ✓ PIN verified — flag in 1.5s
[SYSTEM] Restart scheduled via telegram by 12345 ✓ PIN verified — flag in 1.5s

Restarts are rate-limited. If you restart again too soon, you'll see a message asking you to wait before the next restart.

ApexQuant supports TOTP-based 2FA for the dashboard, gating sensitive actions like Settings save, restart, and license entry behind a 6-digit code from your authenticator app. Strongly recommended for production deployments.

Log in to the dashboard. Go to the Settings tab. Scroll to the Two-Factor Authentication section near the top.

Click Set up 2FA. The dashboard generates a TOTP secret and displays a QR code. Open your authenticator app and scan it.

If your phone is not handy, click Show secret to manually enter the base32 secret into the app instead.

Your authenticator app shows a 6-digit code that rotates every 30 seconds. Enter the current code into the verification field on the dashboard to confirm setup.

On successful verification, the dashboard generates 10 single-use recovery codes. Copy them now — they are shown only once. Store them in a password manager or print and lock away. If you lose your authenticator app and have no recovery codes, delete ~/.apexquant_2fa on your VPS to reset 2FA.

• Dashboard login — required after session expires
• Settings save — protects against misconfiguration if session is hijacked
• Restart Now button — prevents unauthorized restarts
• License key entry — protects your license from being changed

After several wrong codes the action is locked for a while.

Telegram commands are gated by a separate PIN (Admin PIN, set via APEXQUANT_PIN env var), not by TOTP. Set a 4–6 digit PIN in your .env:

Asked for every time, never remembered: /buy and its buttons, /sell, /forcesell, /dca buy, /dca resume, /dca reset, /dca close, /dca sell, /grid resume, /grid recenter, /grid extend, /grid stop, /grid rebuild, /set (for a money setting; the other settings are free), /mode (a change), /resume, /restart, Stop & Quit, /recalibrate, /setkey, /aibudget RAISE, and license commands. With 2FA on, the bot asks for the 6-digit code instead of the PIN. A code you entered for one of these is used by that one action only: Telegram's five-minute pass is not used for them (/grid pause and /grid drain keep it). /stop and /emergency (halt immediately: positions are kept, nothing is sold) ask for nothing, because the chat is yours.

On the dashboard, every action that moves money or changes what the bot does with it needs the PIN (or the 2FA code), asked each time: the Sell and Buy buttons (position, part of a position, held position, leftover coin), Stop & Liquidate, Reset & Rebuild, Resume, Restart, Stop & Quit, the grid controls, the currency switch, the strategy and trading-mode switches, saving or resetting any money setting, taking over coin, a backup restore, the licence key and the TradingView secret. Emergency Stop is the exception: it asks for your dashboard password typed again, no PIN and no 2FA code. With neither a PIN nor 2FA set up there is no manual sale or buy: ApexQuant says “To sell manually, set an Admin PIN or turn on 2FA first.” (or “To do this, set an Admin PIN or turn on 2FA first.”). The same in paper, testnet and live mode, and while halted. The bot's own exits (stop-loss, trailing stop, take-profit, grid sells, DCA exit) never ask.

Go to Settings → Two-Factor Authentication → Disable 2FA. Enter your current TOTP code to confirm.

Emergency reset (lost authenticator + no recovery codes):

• No new buys; selling still works. A halt blocks new buys only. Your open positions are still watched and still sold at their stop-loss, trailing stop, take-profit or DCA exit. Sell orders already on Binance stay and can still fill, and a grid still puts a sell on coin it holds (for example the part of a buy that filled before the stop took the rest of that buy off). Your own sells work too: the dashboard's Sell, the Sell buttons in Telegram, the typed /sell and /forcesell, each confirmed with your PIN or 2FA code. (If three stop-losses fire within ten seconds, ApexQuant treats it as a cascade and stops its automatic exits until you resume.)
• A grid's waiting buy orders are taken off Binance, once. They were placed before the stop and could fill while ApexQuant is not allowed to buy. If Binance does not confirm the cancel, ApexQuant tries again every minute until it does. When trading resumes, the grid puts a buy back on every empty level below the price by itself. This is true for your own Emergency Stop too.
• It is said once, not over and over. The log says it when it starts, with the reason. While it lasts, one reminder every 15 minutes says how long it has lasted (“Still halted after 1 h 30 min”). When it ends, one line says so and how long it lasted (“The halt is over after 42 min; entries are allowed again”).
• It survives a restart. A stop that was in force when ApexQuant restarted is restored, and its message says its figures are as of the halt. Send /resume or press Resume when you are ready.

When ApexQuant starts, its safety monitor reads your account first. The log line says what it counts: “Now protecting your account — your money counts as 1,000.00 USDT (cash plus the cost of the coin you hold)”, with your daily and weekly limits. No grid is started and no order is sent before the monitor is ready, and a stop that was in force is restored first. In those first moments a grid that has not started shows “The safety monitor is starting, so no new grid is started yet.” and starts by itself a moment later. If a stop is in force it shows “Trading is halted, so no new grid is started. Press Resume when you're ready.”

• Creates a STOP file in the bot folder
• Bot halts at the next tick — no new entries open
• Telegram alert fires confirming the stop
• Open positions remain, and every sell still works (stop-loss, trailing stop, take-profit, DCA exit, grid sells and your own sells); only new buys are blocked until you resume

• You spot unexpected behaviour and want to investigate
• Market making a violent move outside your strategy's design
• Before changing config you don't trust
• Loss of confidence in the running state

Emergency Stop asks for your dashboard password typed again (when you have set one), and nothing else: never your PIN and never a 2FA code, so you can stop the bot in a hurry without finding your phone. It works on every account, with or without a PIN or 2FA. In Telegram, /stop and /emergency ask for nothing, because the chat is yours. To start again, Resume needs your PIN (or your 2FA code), and so does Stop & Quit.

1. Click ▶ Resume Bot on the Live tab (or send /resume in Telegram)
2. Bot resumes from current state — open positions are managed normally again

Choose ONE provider and get an API key. Only one provider is active at a time — configure it in Dashboard → Settings → AI Commentary.

Paste your API key directly into Dashboard → ⚙ Bot Config tab (Elite AI group) — for example, Anthropic API Key (ANTHROPIC_API_KEY), OpenAI API Key (OPENAI_API_KEY), or Gemini API Key (GEMINI_API_KEY), depending on your chosen provider. No SSH or restart needed.

Then turn the feature on and tune it in the same Bot Config tab:

• AI Commentary Enabled (ELITE_AI_ENABLED, default on)
• AI Commentary Cooldown (ELITE_AI_COOLDOWN, default 300 seconds) — minimum time between AI calls per symbol

Set AI Commentary Provider (AI_PROVIDER, Bot Config → Elite AI group) to one of: anthropic (Pro & Elite) | openai | gemini | deepseek | mimo | custom. Then set the matching key (all keys below are in the Bot Config → Elite AI group unless noted):

AI providers operate from different jurisdictions; regardless of provider, only a sanitized market-context prompt is sent — no API keys, balances, trade history, or personal data. See the Privacy Policy for details.

The AI gate and AI sentiment synthesis both activate automatically on restart. You'll see [ELITE-AI] BTCUSDT — APPROVE | adj=+0.00 in the logs when it runs.

Grid trading divides a price range into evenly spaced levels and automatically places buy orders below the current price. Each time a buy fills, a sell order is placed one level higher — capturing the spacing as profit. Each time a sell fills, a new buy is placed one level lower, ready to repeat the cycle. The strategy earns small, frequent profits as long as the price oscillates within the range.

A level's buy may fill in a few pieces rather than all at once — they add up to the level's full amount, so seeing more than one row for the same level in your trade history is normal.

Grid bot is rule-based. It does not consult AI Commentary, ML signals, or regime detection. It simply places and replaces limit orders at fixed price levels. This makes it predictable, but entirely dependent on the market staying range-bound.

It does, however, still obey the safety rails every strategy shares: if the kill-switch halts the bot or Binance goes unreachable, the grid stops placing and filling orders until conditions clear.

Good conditions: Sideways, choppy, or ranging markets where price repeatedly bounces between support and resistance. Coins with high intraday volatility but no clear directional trend. Post-breakout consolidations where a new range is forming.

Avoid in: Strong trending markets (bull or bear). A breakout above the upper bound leaves open buy orders with no fills. A breakdown below the lower bound fills all buy levels, accumulating an inventory that continues to lose value. Your range bounds and Range Break Action (GRID_BREAK_ACTION) limit this downside but do not eliminate it.

ApexQuant supports concurrent grids across multiple symbols. Each symbol gets an independent grid with its own price levels, inventory, and PnL — all running in parallel under the same bot instance.

Tier limits:

• Trial — grid on 1 symbol, TESTNET / PAPER only
• Starter — Grid Bot not included
• Pro — grid on 1 symbol, live (mainnet) trading
• Elite — grids on up to 5 symbols, live trading

How allocation works: Total Allocation (USDT or USDC) (GRID_TOTAL_ALLOCATION_USDT) is split equally across every coin in Grid Coins (GRID_SYMBOLS). Example: Total Allocation = 1000 with Grid Coins = BTC, ETH, SOL allocates $333.33 per grid.

How to configure: set Grid Coins (GRID_SYMBOLS) in the Bot Config tab (Grid Bot group) to a comma-separated list of coins, e.g. BTC, ETH. Restart the bot. Each grid initialises independently — if one symbol fails to start (capital check, range invalid), other symbols continue.

How to control individual grids: the dashboard Live tab shows one card per active grid with per-symbol Pause / Resume / Stop & Liquidate / Reset & Rebuild buttons. Telegram commands accept an optional symbol argument: /grid pause BTC targets one grid, /grid pause with no argument targets all.

If you exceed your tier limit: the bot logs a warning and truncates the list to the tier maximum (e.g. Pro user with BTC, ETH in Grid Coins (GRID_SYMBOLS) will only run BTC). Upgrade to Elite to run grids on up to 5 symbols.

Smart Grid — growing the stall instead of closing it. Normally, when the price leaves your grid's range, the stall has to stop: it either pauses (keeps your apples, waits), closes (hands your apples to the safety net), or holds. Smart Grid gives the stall a fourth choice — it grows. Instead of shutting when price runs off the edge, it builds new baskets at the edge that was breached and keeps trading.

Two ways it grows, depending on which way price broke:

• Price runs UP past your top basket → the stall adds new selling-baskets higher up. Your existing baskets don't move, nothing is cancelled — the stall just gets taller so it can keep selling into the rally. This costs nothing extra: the new baskets up top are empty sell-slots waiting for price, not orders you pay for now.
• Price falls BELOW your bottom basket → the stall adds new buying-baskets lower down, so you keep buying the dip. This spends money (each new buying-basket needs cash), so Smart Grid only uses this grid's own unspent budget — never money you didn't set aside for it. When it can't safely add another buying-basket — the budget's spent, OR each basket would get too small to be worth it, OR the stall has already grown to its size limit — it holds what it has and waits. It never sells your apples at a loss to keep going, and it never freezes. To keep buying lower, recenter the stall or add more trade capital.

Example. Say you set a grid on BTC with a range of $60,000 – $66,000 and $600 budget across 5 levels ($120 per basket).

• BTC rallies to $68,000 (above your $66,000 top). Without Smart Grid the stall would pause — your top sell would fill at $66,000 and then nothing, missing the run to $68,000. With Smart Grid (Extend Upward), the stall adds new selling-baskets above $66,000 — say up to $69,000 — so your apples keep selling into the rally instead of stopping at $66,000. Your bottom ($60,000) doesn't move; the range just stretches up to $60,000 – $69,000.
• BTC drops to $58,000 (below your $60,000 floor). With Smart Grid (Extend Downward), the stall adds new buying-baskets below $60,000 — say down to $57,000 — buying the dip with your grid's own spare budget. If all $600 is already deployed, the stall stops adding baskets, holds everything it bought, and waits for recovery. It never sells those dip-buys at a loss to "escape."

A stall only takes on what it can handle. Every basket the stall adds needs somewhere to sell later and enough money behind it to matter. So the stall grows only while there's room — while each basket stays a worthwhile size and the stall hasn't hit its size limit. Once it's full, it stops adding rather than cramming in baskets it can't properly work — like a full plane not boarding more passengers than it has seats. Nothing is sold, nothing is lost; the stall just tells you it's at capacity and waits, and you can recenter or add capital if you want it bigger.

Smart Grid (Extend) vs Trail Up — what's the difference? Both react to price running up, but they do opposite things to your stall:

• Smart Grid Extend = a bigger stall. The bottom stays pinned; new baskets are added on top. Think of stretching a rubber band: one end stays put, the other stretches. You keep every basket you had, plus new ones. Range $60k–$66k becomes $60k–$69k.
• Trail Up = the same stall, moved. The whole range slides upward — the top rises AND the bottom rises, and the lowest baskets are let go. Think of carrying a ladder upward: same number of rungs, just higher; the bottom rungs leave the ground. Range $60k–$66k becomes, say, $63k–$69k — you've given up the $60k–$63k baskets.

Use Extend to keep accumulating across the whole move (widen and hold everything). Use Trail Up to follow a strong one-way trend and stop holding the now-far-below levels. Smart Grid uses Extend. Trail Up remains available as a separate Range Break Action.

(Neither one "chases profit" — that's Smart TP's job, a separate feature that rides a single sell higher when price is spiking. Extend and Trail just decide where your grid's boundaries sit.)

When Smart Grid is on vs off: Turn Smart Grid on and it takes over what happens on a range break — you'll see Extend Upward (on by default, free) and Extend Downward (off by default, spends budget) options, and the older Range Break Action list is hidden. Turn it off and you're back to the classic choices (close / pause / hold / trail up). Smart Grid is off by default — a deliberate choice you switch on.

Auto-Recenter (optional, for unattended trends). Extend grows the stall while it can. But in a strong one-way move the stall eventually reaches its maximum size and price keeps going — leaving it parked out of range until you recenter it by hand. If you're away (asleep, offline), it just sits idle and misses the move. Turn on Auto-Recenter when the grid can't extend further (GRID_AUTO_RECENTER_ON_IDLE, off by default, Smart Grid only) and the bot does that recenter for you: when price breaks a full grid-width clear of the range AND the stall is already at its maximum size, it automatically recenters around the current price to keep trading. Your held coins, cost basis, profit, and settings are unchanged — only the range moves — it's the same Recenter you can run by hand, never a sale. A brief spike won't trigger it — it waits for a clear move — and it won't repeatedly recenter in a choppy market, with a daily safety cap. By default it only acts on an upside break (the stall has already sold to cash on the way up, so redeploying higher is low-risk); set GRID_AUTO_RECENTER_DIRECTION to both only if you also want it to recenter on a downside break, which deploys remaining cash into a falling price. Off by default — leave it off and the stall holds and waits for you, exactly as before. Auto-Recenter keeps the stall trading through a move; it does not make trending markets safe — grid bots still lose in a sustained adverse trend.

Keep-trading actions (never sell): Pause/Resume, Recenter, Extend Up, Extend Down. Wind-down actions: Drain (sells at profit only), Stop & Liquidate and Reset & Rebuild (sell inventory — these ask for your PIN). Housekeeping: Clear Stats.

All commands accept an optional symbol argument. Omit the symbol to target all active grids.

You set Grid Lower Price (USDT or USDC) (GRID_LOWER_PRICE) = 75000, Grid Upper Price (USDT or USDC) (GRID_UPPER_PRICE) = 80000, Grid Levels (GRID_LEVELS) = 10, Total Allocation (USDT or USDC) (GRID_TOTAL_ALLOCATION_USDT) = 200. The bot places 10 levels spaced $555 apart. Each level gets $20 (200 ÷ 10). Below current price ($77,500), levels at $75,000, $75,555, …, $77,222 get limit buy orders. When any buy fills, a sell is placed one level higher. A complete round-trip (buy at $77,222, sell at $77,778) earns approximately $0.73 gross — minus two maker fees (~$0.04 at 0.1%) = ~$0.69 net per cycle. With frequent oscillations, these accumulate. With a sustained drop below $75,000, all buy levels fill and realised losses begin.

Profit per round-trip ≈ grid spacing % minus fees on both sides. With 10 levels across a 6.7% range, each level is ~0.74% apart. After two maker fees at 0.1% each, net profit is ~0.54% per round-trip. This compounds through frequent fills in a ranging market — but in a trending market, inventory accumulates and losses are real. Grid bot does not beat the market; it harvests volatility within a defined range. If the asset trends strongly in either direction, it will underperform a simple hold or miss the trend entirely.

Grid state (open orders, filled levels, realised PnL) is saved to apexquant.db after every fill. On restart, the bot reconciles persisted state against live Binance orders and resumes from where it left off.

Use these Telegram commands to control a running grid:

• /grid pause — Pauses the grid. Open orders are canceled and the bot holds the current inventory without placing new orders. Use /grid resume to restart the grid from its current state. Useful when you want a temporary break without fully liquidating.
• /grid drain — The graceful exit. Cancels only the resting buy orders, keeps the resting sell orders live, and stops placing new buys. Your inventory liquidates naturally at the grid's own profit levels as price rises. Once all inventory has sold through the open sells, the grid auto-finalizes to stopped with no manual action needed. Use this when you want to exit a grid without taking a market-sell loss — the middle option between pause (hold everything) and stop (exit now). Safeguard: if price falls far below range or the drain runs longer than Grid Drain Timeout (hours) (GRID_DRAIN_TIMEOUT_H) (default 24h), the bot escalates per Grid Drain On Timeout (GRID_DRAIN_ON_TIMEOUT) (default: liquidate the remainder) so the drain never hangs indefinitely.
• /grid stop — Full exit. Cancels all resting grid orders and market-sells the grid's entire inventory back to your account's currency in one shot. Use this when you want to recover capital, switch symbols, or migrate. After /grid stop the grid is fully closed — no orders or inventory remain.

Capital sizing rule: each grid needs at least $50 allocated, and allocation ÷ symbols ÷ levels must be ≥ $10 per level — otherwise Binance rejects every individual order as below MIN_NOTIONAL. For example: $100 capital, 1 symbol, 5 levels = $20/level ✓. $100, 2 symbols, 10 levels = $5/level ✗.

Dashboard tip: the grid card's order list now shows the value in your account's currency alongside each coin amount — buy orders show the amount to be deployed, sell orders the amount to be returned, and held inventory shows the live value at current price.

In your dashboard Bot Config tab, change Primary Strategy (PRIMARY_STRATEGY) from dca, directional, or grid to tradingview. This disables ApexQuant's internal signal generation. TradingView alerts become the entry source. Restart the service after changing.

Open the TradingView tab in dashboard. Copy your unique webhook URL. Treat it like a password — anyone with this URL can trigger trades. Do not share or post publicly.

In TradingView, create or edit an alert on your strategy:

Click 🧪 Test in the TradingView dashboard tab. ApexQuant sends a synthetic webhook to itself. Check Telegram for the result and the Recent Signals table for the log entry.

When you open a manual SELL, you can close the whole position or sell only a portion. Pick a quick preset (25%, 50%, 75%, 100%), type any custom percentage in the % field, or enter an exact quantity in units. The remainder stays under automatic management — take-profit and trailing logic continue to run on whatever is left.

If the chosen amount would leave a remainder below the exchange’s minimum order size, the dialog blocks the partial and offers to close the whole position instead.

The same options are available in Telegram: the SELL menu offers 25/50/75/100% presets, Custom %, and Custom qty. You can also type /sell SYMBOL 30% for a quick percentage sell or /sell SYMBOL 0.5 for an exact quantity.

The FastAPI server on port 5005 is not running or crashed on startup.

All API calls are returning 401 or the JS file is not loading correctly.

Check which gate is blocking entries. On the dashboard → click the Gate Audit view or check logs.

• Confirm BINANCE_API_KEY (canonical: /root/apexquant-data/.env; /root/ApexQuant/.env should be a symlink to it) and BINANCE_API_SECRET are set in .env
• In Testnet mode: use keys from testnet.binance.vision — live keys do NOT work on testnet
• In Live mode: ensure the API key has Spot Trading enabled and IP whitelist includes your VPS IP
• Wallet must hold the currency you chose (USDT or USDC) — other stablecoins are not traded

An "unaccounted asset" is a balance in a coin other than your account's currency in your Binance account that ApexQuant's own trade history doesn't explain — for example, a position you manually opened, a transfer from another account, or a trade from before this install. Only balances above the Reconciliation Minimum (USDT or USDC) setting (RECONCILE_MIN_USDT, default 50.0) are flagged — smaller amounts are treated as exchange dust and never surface here.

Before an item gets Sell/Adopt buttons, ApexQuant requires two consecutive reconciliation passes to agree on what it found — a single flaky Binance read is never enough to surface an item as actionable. Reconciliation runs on the Position Reconciliation Interval setting (RECONCILE_INTERVAL_SEC, default 6 hours), and each pass waits out the full interval first — so two agreeing passes can take up to twice the interval (up to 12 hours at the default) after a fresh restart. If the banner shows nothing but you know you have an unaccounted balance, this is normal — give it time before assuming something is wrong.

ApexQuant only flags a balance in the first place if it can trace it to a bot BUY that was never matched by a later bot SELL — a genuine deposit or a manual transfer was never a bot purchase, so it's never even a candidate for this list. As an additional backstop, adopting also runs a check against Binance's own deposit and internal-transfer records (looking back 30 days) before completing — in the rare case that check finds a genuine deposit or transfer explaining the balance, the adopt is refused and the coins are instead folded into your wallet baseline (bookkeeping only, never sold or adopted). This is expected to almost never trigger for a normal Recovery-banner item, precisely because of the FIFO matching above — it exists as defense in depth, not as the primary gate.

• Sell to USDT / Sell to USDC (the button names your account's currency): ApexQuant sells the exact flagged quantity at market price and removes it from tracking. Irreversible — you're asked to confirm the quantity and USD value first.
• Adopt DCA or Adopt Directional: tell ApexQuant to start tracking this asset under the DCA basket or the Directional (exit-protected) strategy. It will then manage the exit with stops and take-profit as configured for whichever you choose.

There's no separate "dismiss" action — an item stays in the banner, unmanaged in your wallet, until you Sell or Adopt it.

Recovery does not apply in PAPER mode — there is no real Binance wallet to reconcile against. The recovery banner does not appear in PAPER.

Automatically selling a released position the moment management stops would force a sale at whatever price happens to be current — even a brief, meaningless dip. ApexQuant never does this. A released position keeps its cost basis and quantity on record, with zero auto-exit machinery attached, until you make an explicit choice.

• Keep: leave it exactly as it is — tracked, displayed, no auto-exit. The default state; you don't need to act.
• Sell: sell the position at market price right now. The only way a Held position is ever sold — always your explicit choice, always confirmed before it executes.
• Attach protection: choose a stop-loss and trailing-stop level and hand the position back to active management. Once attached, it behaves like any other auto-managed position and will exit automatically if the price hits your chosen stop.
• Re-assign: hand the position to DCA, Grid, or Directional as a fresh starting position for that strategy, using the same adoption logic as Recovery's own Adopt actions above.

There's no time limit or forced decision — a Held position can stay Held indefinitely with no consequence.

If a whole DCA basket (multiple buy-in legs across different prices) is released, ApexQuant collapses it into a single Held position at the basket's weighted average cost — matching how the position already displayed while it was active. The individual legs aren't tracked separately once Held.

If you already had a position released under an earlier version of ApexQuant with its own protective stop already attached, that protection is left exactly as it was — this feature never silently removes an existing stop from a position you already had. Only newly released positions default to the unprotected Held state described above.

3 consecutive Binance errors within 60 seconds triggers the API_DOWN state. This catches HTML error pages (Binance error 0), HTTP 5xx responses, connection timeouts, and stale ticker feeds.

• ApexQuant says so once: “Binance is unreachable right now. ApexQuant keeps retrying on its own and trades nothing until it is back.” If it lasts, one reminder every 15 minutes says how long (“Binance still unreachable for 42 min; still retrying.”), and when Binance answers again one line says it is over and how long it lasted
• All new entries blocked — engine tick, TradingView webhooks (coming soon), and Telegram /buy /sell all return immediately
• All auto-exits paused — no sell attempts on a dead API (avoids partial fills and orphan orders)
• Telegram spam suppressed — one "🚨 Binance API Down" alert fires, then silence until recovery
• The dashboard still opens and loads quickly. It shows what ApexQuant last knew, and says “Waiting for Binance” instead of an error (while ApexQuant is starting up, it says what it is waiting for). The banner shows the outage status, its duration and the skipped operations count (updates every 10s)
• Buttons that need Binance (manual buy and sell, the grid controls such as Pause, Drain, Resume and Reset, the recovery sells) are greyed out with the reason, and a request that gets through anyway is refused with one sentence: “Binance can't be reached right now, so this can't be done. It works again as soon as Binance is back.” A backtest or training run says it needs Binance's price history. Right after a restart it says “ApexQuant is still starting up. Try again in a moment.”
• Settings, the Emergency Stop and reading your data keep working
• Drawdown calc falls back to entry price for open positions — avoids false drawdown halt from missing ticker data

A background monitor pings api.binance.com/api/v3/time every 30 seconds. After 3 consecutive successful pings, the bot automatically resumes and sends a "✅ Binance API Recovered" Telegram alert with the outage duration and skipped operations count.

If you need to halt the bot during or after an outage:

• Dashboard → 🛑 EMERGENCY STOP button in the Bot Status card (asks for your dashboard password again; no PIN or 2FA code)
• Telegram → /stop command (asks for nothing)

To go on afterwards, press Resume on the dashboard (or send /resume in Telegram).

ApexQuant keeps itself up to date automatically. A daily check installs any new version, verifies it (SHA-256), preserves your settings, license and database, restarts the bot, and auto-rolls-back to the previous version if anything fails.

Automatic updates are enabled by default — you were asked during setup. You can change this any time:

Automatic updates run around 04:30 server time (with a small random jitter). The full log is at /var/log/aq-update.log.

1. Visit apexquant.tech/download
2. Download the latest ApexQuant-Setup.zip to your local machine
3. Upload the zip to your VPS using SCP from your local machine:
   Upload via SCPCopy

   scp ApexQuant-Setup.zip root@your-vps-ip:/root/
4. Or use SFTP (FileZilla, WinSCP, Cyberduck) and upload to /root/

Re-creates symlinks to /root/apexquant-data/ and rebuilds the venv with any new dependencies. Your config, license, trial timer, and trade history are never touched.

Verify license shows [LICENSE] Valid | Tier: .... Open dashboard, check F12 console — no errors. Watch for 5–10 minutes.

You'll be back on the previous working version. Report the issue to support.

Removes the bot software but preserves your license key, database, and configuration. You can reinstall at any time and everything re-attaches automatically. Your license seat stays bound — this is a "pause" not a release.

Use purge when you are decommissioning the server permanently or moving to a new one and want your license freed immediately.

You can optionally include a reason (stored for analytics, not shared publicly):

Flags for the uninstall script go after sudo bash -s --, not on the curl line. -s tells bash to read the script from the pipe; -- ends bash's own options so everything after (--purge, --force, etc.) is passed to the script. Putting flags directly after the curl URL would send them to curl instead, which errors with option --purge is unknown.

If you have open bot-managed positions the uninstaller will warn you and pause. Use the command below to skip the gate — you will need to manage those positions manually on Binance.