Bots

A bot is a dedicated compute instance that runs your trading strategy — either continuously or during configured trading sessions. Each bot connects to your exchange via an API key and executes trades based on the strategy template you assign to it.

The Bots page shows all your deployed bots as cards in a grid. Each card displays the bot's label, status, last heartbeat, assigned API key, template, and region. You can search bots by label or ID, and access a deployment history of past (stopped) instances.

Bots assigned a testnet API key connect to the exchange's sandbox environment and are clearly badged as testnet throughout the dashboard. Testnet bots use the same strategy engine, risk controls, and analytics as live bots — only the exchange endpoint differs.

To deploy a new bot, click the "Deploy Bot" button on the Bots page. You'll be prompted to provide:

• Bot name — A label to identify this bot instance (e.g. "BTC Trend Follower").
• Region — The cloud region where the bot will run. Choose a region close to your exchange's servers for lower latency.

After deploying, the bot will appear with a "Deploying" status. Once provisioning completes, it transitions to "Online" and begins processing market data. You'll then need to assign an API key and strategy template before it can trade.

A bot goes through the following states:

1. Deploying — The compute instance is being provisioned. This typically takes under a minute. No charges are incurred during provisioning.
2. Online — The bot is live and processing market data. It sends regular heartbeats to confirm connectivity. Compute charges apply.
3. Paused — The bot is still running on its dedicated instance but will not open new positions. Exit rules continue to be evaluated for existing positions. Compute charges still apply because the instance remains provisioned and active.
4. Offline — The bot has lost connectivity (missed heartbeats) but the compute instance is still provisioned. Compute charges still apply. Check the bot's activity feed for errors and consider stopping and redeploying if the issue persists.
5. Error — The bot has encountered a critical error. Compute charges still apply while the instance is provisioned. Review the error in the activity feed and stop the bot if the error is unrecoverable.
6. Sleeping — The compute instance has been temporarily deprovisioned to save costs. No charges are incurred. The bot will automatically wake before the next trading session. Your configuration, API key assignment, and strategy template are all preserved.
7. Waking — The bot is resuming from sleep. A compute instance is being provisioned and the bot will transition to Online before the next trading session begins.
8. Winding Down — The bot is gracefully shutting down (e.g. due to a stop command or zero balance). The instance is being deprovisioned.
9. Stopped — The compute instance has been deprovisioned. No charges are incurred. Your bot configuration is preserved and you can redeploy at any time.

Each bot needs an API key to connect to your exchange. You assign keys on the bot's detail page.

• Each API key can only be assigned to one bot at a time.
• The key must be active (not disabled) to be assignable.
• API key assignment can only be changed when the bot has no open positions — this prevents orphaned positions on the exchange.

Each bot runs one strategy template at a time. You can select or change the template from the bot's detail page under the Template tab.

Each bot has its own configurable risk parameters, separate from its strategy template. Risk limits act as hard safety guardrails that override strategy behaviour — they cannot be bypassed by signals or exit rules. Configure them on the bot's detail page under the Risk Limits tab across three categories: Position Limits (per-asset and total caps), Loss Limits (per-trade, daily kill switch, consecutive loss pause), and Execution Safety (max leverage, max slippage, API error threshold).

Bots use sensible defaults when no custom risk limits are configured. Changes are picked up in real time — no restart required. For detailed explanations and example scenarios, see Risk Management.

You can pause a running bot to temporarily stop it from opening new positions. While paused:

• The bot will not open new positions.
• Existing positions remain open and exit rules continue to be evaluated — the bot will still close positions when exit conditions are met.
• The bot continues receiving market data and processing signals internally, so when resumed it has full context.

Resume the bot at any time to allow it to open new positions again.

Two controls exist for exiting positions on demand:

• Pause & Close All — closes every open position at market and pauses the bot. Realized PnL is recorded immediately. Not reversible. Gated by the "Close all positions" permission (owner, admin, risk_manager).
• Close a single position — from the fleet overview, close one specific position without touching the others. Useful when a risk manager wants to exit a specific symbol without nuking the whole book. Same permission tier as Close All.

Restart tears down the bot process and rebuilds it from scratch. Trading is paused during the restart and resumes automatically once the bot reconciles its state with the exchange. Use this if your bot gets stuck in an unexpected state.

Restart is rate-limited to one restart per hour per bot. The button disables itself for the remainder of the cooldown window. Owners and admins can trigger restart; other roles must ask an admin or open a support ticket.

Plutarc staff can, in limited circumstances, pause, resume, or restart one of your bots — for example when responding to an incident you've escalated. Every staff action is transparent:

• The command shows a "Plutarc staff" badge in your bot's command history, along with the staff member's reason.
• The org's owner receives an email notification each time staff acts on one of your bots.
• Staff cannot close positions, update your bot version, or change your configuration — only pause, resume, or restart.

Bots with trading sessions configured can automatically sleep between sessions to reduce compute costs. When all active sessions end and no positions are open, the bot enters a Sleep state — the compute instance is deprovisioned and no charges are incurred.

Before the next trading session begins, the bot automatically wakes — a new compute instance is provisioned and the bot transitions to Online, ready to trade. Wake typically takes 1–3 minutes and is scheduled ahead of the session start time.

How sleep interacts with other states

• Open positions — The bot will not sleep while it has open positions. Exit rules continue to be evaluated until all positions are closed.
• Paused bots — Paused bots still follow the sleep schedule. If a session ends while the bot is paused and there are no open positions, the bot will sleep as normal.
• No sessions configured — Bots without trading sessions run 24/7 and never sleep automatically. You can always stop a bot manually to halt charges.

Bot updates are opt-in. When a new version is available, an amber Update available badge and an Update Bot button appear on the bot card and detail page.

When you click Update Bot:

1. The bot pauses trading and cancels any pending orders
2. The new version is pulled and the bot container is replaced
3. The bot restarts, reconciles its state, and resumes normal operation

The update runs in-place on the same compute instance — your IP address does not change, so API key whitelists remain valid. The bot will be briefly unavailable during the update, typically 1–2 minutes. Open positions are preserved throughout.

You can see the current running version of each bot on its card and detail page.

Clicking a bot card opens its detail page. The header displays the bot's IPv4 and IPv6 addresses, which you can copy and add to your exchange's IP whitelist for API key access.

The detail page has three tabs: