BotSpot: AI Trading, Backtests and Bots

Connect a broker or create a paper account

broker_connections

Destructive

Connect an existing broker using its supported credentials, prepare a deferred paper account request, create an internal simulated trading account, add/remove/set its virtual cash, delete it, or read operation progress. Creation is a write; progress is read-only. Each action retains its independent permission and owner checks. Reuse the same UUID requestId and unchanged inputs when retrying one creation; use distinct request IDs for multiple intended accounts.

Set "action" to choose the operation. Only send the fields listed for that action.

action="connect_existing": Create saved broker credential

Required fields: broker, displayName, paperOrLive, credentialValues. Stores broker credential material in Vault and returns only metadata for the authenticated user. Values are encrypted at rest and are not returned to MCP. Use this for broker login/trading credentials only. Do not add a brokerCredentialId to a deployment by default; let the user choose on the approval page unless they explicitly named the exact saved broker connection/account. The broker field controls validation for known Lumibot/BotSpot brokers; use the exact environment variable key names below. Kalshi (kalshi): KALSHI_API_KEY_ID + KALSHI_PRIVATE_KEY. Optional: KALSHI_SUBACCOUNT, KALSHI_EXCHANGE_INDEX, KALSHI_BASE_URL, KALSHI_WS_URL. Do not pass KALSHI_IS_DEMO; BotSpot derives it from paperOrLive. Example credentialValues: {"KALSHI_API_KEY_ID":"key-id...","KALSHI_PRIVATE_KEY":"private-key-pem..."}. Alpaca (alpaca): ALPACA_API_KEY + ALPACA_API_SECRET OR ALPACA_OAUTH_TOKEN. Do not pass ALPACA_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"ALPACA_API_KEY":"PK...","ALPACA_API_SECRET":"secret..."}. Tradier (tradier): TRADIER_ACCOUNT_NUMBER + TRADIER_ACCESS_TOKEN OR TRADIER_ACCOUNT_NUMBER + TRADIER_API_KEY OR TRADIER_ACCOUNT_NUMBER + TRADIER_TOKEN. Optional: TRADIER_REFRESH_TOKEN, TRADIER_OAUTH_CLIENT_ID, TRADIER_OAUTH_CLIENT_SECRET. Do not pass TRADIER_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"TRADIER_ACCOUNT_NUMBER":"6AB12345","TRADIER_ACCESS_TOKEN":"token..."}. Charles Schwab (schwab): SCHWAB_ACCOUNT_NUMBER + SCHWAB_TOKEN. Example credentialValues: {"SCHWAB_ACCOUNT_NUMBER":"123456789","SCHWAB_TOKEN":"base64url-token-payload..."}. Tradovate (tradovate): TRADOVATE_USERNAME + TRADOVATE_DEDICATED_PASSWORD + TRADOVATE_CID + TRADOVATE_SECRET. Optional: TRADOVATE_APP_ID, TRADOVATE_APP_VERSION. Do not pass TRADOVATE_IS_PAPER; BotSpot derives it from paperOrLive. Example credentialValues: {"TRADOVATE_USERNAME":"username...","TRADOVATE_DEDICATED_PASSWORD":"dedicated-password...","TRADOVATE_CID":"client-id...","TRADOVATE_SECRET":"secret..."}. TopstepX (projectx-topstepx): PROJECTX_TOPSTEPX_API_KEY + PROJECTX_TOPSTEPX_USERNAME. Optional: PROJECTX_TOPSTEPX_PREFERRED_ACCOUNT_NAME. Example credentialValues: {"PROJECTX_TOPSTEPX_API_KEY":"key...","PROJECTX_TOPSTEPX_USERNAME":"username..."}. WEEX (weex): WEEX_API_KEY + WEEX_API_SECRET + WEEX_API_PASSPHRASE. Example credentialValues: {"WEEX_API_KEY":"key...","WEEX_API_SECRET":"secret...","WEEX_API_PASSPHRASE":"passphrase..."}. Bitunix (bitunix): BITUNIX_API_KEY + BITUNIX_API_SECRET. Optional: BITUNIX_TRADING_MODE. Example credentialValues: {"BITUNIX_API_KEY":"key...","BITUNIX_API_SECRET":"secret..."}. Kraken (kraken): KRAKEN_API_KEY + KRAKEN_API_SECRET. Example credentialValues: {"KRAKEN_API_KEY":"key...","KRAKEN_API_SECRET":"secret..."}. Coinbase (coinbase): COINBASE_API_KEY_NAME + COINBASE_PRIVATE_KEY. Optional: COINBASE_API_PASSPHRASE, COINBASE_SANDBOX. Example credentialValues: {"COINBASE_API_KEY_NAME":"organizations/.../apiKeys/...","COINBASE_PRIVATE_KEY":"-----BEGIN EC PRIVATE KEY-----..."}. Any other CCXT 4.5.64 exchange id (for example okx, binance, bybit, bitget, hyperliquid): use that id as the broker and the credentials it requires, named _API_KEY, _API_SECRET, _API_PASSPHRASE, _UID, _PRIVATE_KEY or _WALLET_ADDRESS. Do not pass _SANDBOX; BotSpot derives it from paperOrLive. Do not put data-provider API keys, screener rows, CSV data, workbooks, JSON dumps, or BotSpot internal keys here; use saved_env_vars(action="create") for non-broker runtime secrets.

action="prepare_paper": Prepare paper trading account

No other fields required. Prepares editable paper account creation inputs for the signed-in user. No account is created or funded by this tool. Use when the user wants a paper account creation button in chat. Pass name and initialBalance whenever the user supplied them; preserve those requested values in the prepared action. Omit them only when unspecified: name then defaults to Paper trading account and initialBalance to 10000 simulated USD. General broker, data and backtesting questions do not authorize account creation. Existing suitable connections should be reused for research. External MCP clients that want to create an account directly can use broker_connections(action="create_paper") instead.

action="create_paper": Create paper trading account

Required fields: requestId, name. Creates an internal simulated trading account and attaches it to its own saved broker connection for the authenticated user. Call only when the user requests a new paper account. Supply one UUID requestId per intended account; reuse that exact requestId, name and initialBalance on retries. For multiple accounts, use a distinct UUID for each account. initialBalance is virtual USD, defaults to 10000, and supports at most two decimals. No bank link or API keys are needed. A pending result is not ready or funded: use broker_connections(action="paper_progress") with the returned creationId to read progress. Only state ready includes the saved brokerCredentialId. Do not start a deployment until ready, and select that connection only when the user requests it. Returns metadata only, never provider credentials. Operational account and creation-rate limits apply.

action="paper_progress": Get paper account creation progress

Required fields: creationId. Reads the authenticated owner's paper account creation progress using the creationId returned by broker_connections(action="create_paper"). This read does not create or fund an account. Only state ready means its saved broker connection is ready. No credentials are returned.

action="manage_paper": Manage paper account cash or delete an account

Required fields: brokerCredentialId, requestId, operation. Change virtual USD cash in an existing internal paper account. Use only when the user requests this exact change. Select its exact brokerCredentialId from saved connections. operation add_cash adds amount, remove_cash subtracts amount, set_cash sets the cash balance (not total equity). Cash changes keep positions, orders and history. Do not call a cash adjustment a fresh-account reset. operation close removes the internal paper account from BotSpot immediately and automatically stops its bots, cancels orders, closes simulated positions and removes cash before provider closure. History stays. The user does not do these steps manually. Supply one UUID requestId per intended operation. Repeat identical inputs and requestId to continue pending or uncertain replies; never generate a fresh requestId to retry a transfer. For cash changes, only completed confirms funding. For close, pending means removed from BotSpot with automatic provider cleanup still in progress; do not claim provider closure until completed. rejected is a failure. The tool cannot manage externally linked or live accounts and never returns credentials.

action="paper_operation": Read paper account operation progress

Required fields: brokerCredentialId, operationId. Read a cash-change or deletion receipt by its exact brokerCredentialId and operationId. This read never submits funding or closes an account. To continue pending work, repeat broker_connections(action="manage_paper") with its original requestId and unchanged inputs.

action="paper_options": Read paper account options permission

Required fields: brokerCredentialId. Read the selected managed paper account options approved level, effective trading level and buying power. This does not submit an application or verify market-data access.

action="request_paper_options": Request paper account options permission

Required fields: brokerCredentialId, level. Request options trading permission for an explicitly selected owned managed paper account when the user asks. level 1 covers covered calls and cash-secured puts; 2 adds long calls/puts; 3 adds supported spreads. A pending, rejected or lower-level application is not full approval. Read the returned effective permission; quote/data subscriptions require a separate check. An uncertain error must be reconciled with a permission read before another submission. This does not trade, buy data, or change a live brokerage account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "broker_connections"
  }
}

Input Schema

Name	Required	Description
`name`	No	Used with action="prepare_paper", action="create_paper". Required for action="create_paper".
`level`	No	Used with action="request_paper_options". Required for action="request_paper_options".
`action`	Yes	Which operation to run: "connect_existing", "prepare_paper", "create_paper", "paper_progress", "manage_paper", "paper_operation", "paper_options", "request_paper_options". See the tool description for each one.
`amount`	No	Used with action="manage_paper".
`broker`	No	Used with action="connect_existing". Required for action="connect_existing".
`operation`	No	Used with action="manage_paper". Required for action="manage_paper".
`requestId`	No	Used with action="create_paper", action="manage_paper". Required for action="create_paper", action="manage_paper".
`creationId`	No	Used with action="paper_progress". Required for action="paper_progress".
`displayName`	No	Used with action="connect_existing". Required for action="connect_existing".
`operationId`	No	Used with action="paper_operation". Required for action="paper_operation".
`paperOrLive`	No	Used with action="connect_existing". Required for action="connect_existing".
`initialBalance`	No	Used with action="prepare_paper", action="create_paper".
`credentialValues`	No	Used with action="connect_existing". Required for action="connect_existing".
`brokerCredentialId`	No	Used with action="manage_paper", action="paper_operation", action="paper_options", action="request_paper_options". Required for action="manage_paper", action="paper_operation", action="paper_options", action="request_paper_options".

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 3, 2026

changedInput schema / properties / action / description

Previous value: -"Which operation to run: \"connect_existing\", \"prepare_paper\", \"create_paper\", \"paper_progress\", \"manage_paper\", \"paper_operation\". See the tool description for each one."New value: +"Which operation to run: \"connect_existing\", \"prepare_paper\", \"create_paper\", \"paper_progress\", \"manage_paper\", \"paper_operation\", \"paper_options\", \"request_paper_options\". See the tool description for each one."

changedInput schema / properties / action / enum

Previous value: -[
-  "connect_existing",
-  "prepare_paper",
-  "create_paper",
-  "paper_progress",
-  "manage_paper",
-  "paper_operation"
-]New value: +[
+  "connect_existing",
+  "prepare_paper",
+  "create_paper",
+  "paper_progress",
+  "manage_paper",
+  "paper_operation",
+  "paper_options",
+  "request_paper_options"
+]

changedInput schema / properties / brokerCredentialId / description

Previous value: -"Used with action=\"manage_paper\", action=\"paper_operation\". Required for action=\"manage_paper\", action=\"paper_operation\"."New value: +"Used with action=\"manage_paper\", action=\"paper_operation\", action=\"paper_options\", action=\"request_paper_options\". Required for action=\"manage_paper\", action=\"paper_operation\", action=\"paper_options\", action=\"request_paper_options\"."

addedInput schema / properties / level

Added value: +{
+  "description": "Used with action=\"request_paper_options\". Required for action=\"request_paper_options\".",
+  "maximum": 3,
+  "minimum": 1,
+  "type": "integer"
+}

Changed7 schema fields changedNov 1, 2026

changedInput schema / properties / action / description

Previous value: -"Which operation to run: \"connect_existing\", \"prepare_paper\", \"create_paper\", \"paper_progress\". See the tool description for each one."New value: +"Which operation to run: \"connect_existing\", \"prepare_paper\", \"create_paper\", \"paper_progress\", \"manage_paper\", \"paper_operation\". See the tool description for each one."

changedInput schema / properties / action / enum

Previous value: -[
-  "connect_existing",
-  "prepare_paper",
-  "create_paper",
-  "paper_progress"
-]New value: +[
+  "connect_existing",
+  "prepare_paper",
+  "create_paper",
+  "paper_progress",
+  "manage_paper",
+  "paper_operation"
+]

addedInput schema / properties / amount

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 18,
+      "type": "string"
+    },
+    {
+      "minimum": 0,
+      "type": "number"
+    }
+  ],
+  "description": "Used with action=\"manage_paper\"."
+}

addedInput schema / properties / brokerCredentialId

Added value: +{
+  "description": "Used with action=\"manage_paper\", action=\"paper_operation\". Required for action=\"manage_paper\", action=\"paper_operation\".",
+  "format": "uuid",
+  "type": "string"
+}

addedInput schema / properties / operation

Added value: +{
+  "description": "Used with action=\"manage_paper\". Required for action=\"manage_paper\".",
+  "enum": [
+    "add_cash",
+    "remove_cash",
+    "set_cash",
+    "close"
+  ],
+  "type": "string"
+}

addedInput schema / properties / operationId

Added value: +{
+  "description": "Used with action=\"paper_operation\". Required for action=\"paper_operation\".",
+  "format": "uuid",
+  "type": "string"
+}

changedInput schema / properties / requestId / description

Previous value: -"Used with action=\"create_paper\". Required for action=\"create_paper\"."New value: +"Used with action=\"create_paper\", action=\"manage_paper\". Required for action=\"create_paper\", action=\"manage_paper\"."

Changed4 schema fields changedOct 31, 2026

changedInput schema / properties / action / description

Previous value: -"Which operation to run: \"connect_existing\", \"create_paper\", \"paper_progress\". See the tool description for each one."New value: +"Which operation to run: \"connect_existing\", \"prepare_paper\", \"create_paper\", \"paper_progress\". See the tool description for each one."

changedInput schema / properties / action / enum

Previous value: -[
-  "connect_existing",
-  "create_paper",
-  "paper_progress"
-]New value: +[
+  "connect_existing",
+  "prepare_paper",
+  "create_paper",
+  "paper_progress"
+]

changedInput schema / properties / initialBalance / description

Previous value: -"Used with action=\"create_paper\"."New value: +"Used with action=\"prepare_paper\", action=\"create_paper\"."

changedInput schema / properties / name / description

Previous value: -"Used with action=\"create_paper\". Required for action=\"create_paper\"."New value: +"Used with action=\"prepare_paper\", action=\"create_paper\". Required for action=\"create_paper\"."

AddedOct 28, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Well beyond the annotations, the description discloses state machines (pending/ready/rejected), that pending means not ready or funded, that close automatically stops bots, cancels orders, closes simulated positions and removes cash while history stays, and that credentials are encrypted in Vault and never returned. It also warns about operational and creation-rate limits. The only gap is that the blanket idempotentHint=false sits in mild tension with the requestId-reuse retry contract described for create_paper and manage_paper, which is not reconciled explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but the length is earned by eight actions and a genuinely needed broker-credential matrix; markdown headers per action plus front-loaded idempotency and read/write framing make it scannable. The retail-broker and CCXT credential enumeration is the one section that could be pushed into the schema or a reference, which keeps it off a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, action-multiplexed, destructive tool with no output schema, the description supplies everything an agent needs: requestId discipline for multi-account creation, where progress lives (creationId/operationId), what to tell the user about pending states, and the reconciliation rule that an uncertain error must be checked with a permission read before resubmitting.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a 3 would be the baseline, but the description adds real meaning the schema cannot: per-broker required credential keys with worked examples (KALSHI_API_KEY_ID + KALSHI_PRIVATE_KEY, etc.), explicit prohibition on passing KALSHI_IS_DEMO/ALPACA_IS_PAPER because paperOrLive derives it, initialBalance as virtual USD with a two-decimal cap and 10000 default, set_cash meaning cash balance not total equity, and level 1/2/3 option-tier definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource for every one of the eight dispatched actions ("Create saved broker credential", "Creates an internal simulated trading account", "Reads the authenticated owner's paper account creation progress") and explicitly classifies which are writes versus reads. It also differentiates from siblings by routing non-broker secrets to saved_env_vars and credential CRUD to the delete/update/list_broker_credential tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each action carries explicit when-to-use and when-not-to-use gates: "Call only when the user requests a new paper account", "General broker, data and backtesting questions do not authorize account creation", "Use only when the user requests this exact change", and "The tool cannot manage externally linked or live accounts". It also names alternatives directly, pointing external MCP clients at broker_connections(action="create_paper") instead of prepare_paper.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All BotSpot: AI Trading, Backtests and Bots tools Inspect

Try in Browser