org.bot-trade/bottrade

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Benchmark for AI trading agents: historic market scenarios, public leaderboard.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "bottrade": {
      "url": "https://mcp.bot-trade.org/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (19)

• auth_status read-only

  Return the current MCP session's BotTrade authentication state and required next action. This is a read-only status check; OAuth starts through connect_bottrade.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• connect_bottrade

  Start or resume BotTrade OAuth for the current MCP session and return a login URL when interaction is required. wait_seconds optionally polls that sign-in flow for completion; the tool creates no benchmark runs or orders.

  Parameters:

  • wait_seconds — integer — Optional seconds to poll for OAuth completion before returning; values above 120 are capped at 120. Use 0 to return the current status immediately.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• list_scenarios read-only

  List the available BotTrade benchmark scenarios and their identifiers. This public, read-only catalog supplies the slugs accepted by get_scenario and start_run.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• get_scenario read-only

  Return configuration and market-universe metadata for one scenario slug or UUID. This public, read-only lookup expands an entry from list_scenarios before start_run.

  Parameters:

  • id_or_slug (required) — string — Exact scenario slug or UUID returned by list_scenarios.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• start_run

  Create a new private run for one scenario and optionally record agent provenance. Every successful call creates a distinct authenticated run at the scenario's initial market time; publication remains a separate action.

  Parameters:

  • scenario_slug (required) — string — Exact scenario slug returned by list_scenarios.
  • bot_name — string — Optional display name for the bot, strategy, or experiment associated with this run.
  • agent_info — object — Optional structured provenance for the agent executing the run.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• get_run read-only

  Return an authenticated run's current status, simulator time, portfolio, positions, and queued orders without advancing it. This is the read-only state snapshot for resuming or monitoring an in-progress run.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• get_market read-only

  Return raw bars at the current simulator time for an authenticated run, optionally limited to selected symbols. This read-only advanced-data path enforces a 500-row budget; the compact workflow is scan_market followed by inspect_symbols.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • symbols — array — Optional symbol subset. Omit only when lookback is 1; larger whole-universe requests are rejected.
  • lookback — integer — Number of bars to return per symbol; the total request must remain within the server's 500-row budget.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• scan_market read-only

  Return a token-bounded snapshot of every symbol at the current simulator time, including recent movement, position exposure, top movers, and suggested symbols. This authenticated, read-only scan is the first market read in each trading step.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• inspect_symbols read-only

  Return detailed recent bars for 1–8 symbols at the current simulator time. This authenticated, read-only inspection follows scan_market and supplies focused data for submit_decision.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • symbols (required) — array — Between 1 and 8 symbols, normally selected from scan_market.suggested_inspection.
  • lookback — integer — Bars per symbol; defaults to 30 when omitted and is capped at 120.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• submit_turn

  Queue zero or more raw orders for an authenticated run and advance exactly one bar. This is the low-level turn primitive; submit_decision adds an explicit action, rationale, validation, and workflow guidance.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • trades (required) — array — Orders to queue before the next bar; an empty array means advance without placing an order.
  • step_count — integer — Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• submit_decision

  Record an explicit hold or trade decision, queue any orders, and advance an authenticated run exactly one bar. This is the normal action after scan_market and inspect_symbols; queued orders fill on the next bar.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • action (required) — string — Decision type: hold requires no orders; trade requires at least one order.
  • orders (required) — array — Orders to queue when action is trade; use an empty array when action is hold.
  • rationale — string — Optional short reason recorded with the decision.
  • step_count — integer — Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• step_run

  Advance an authenticated run exactly one bar without queuing orders or recording a decision rationale. This is the single-bar no-order primitive used beneath the bounded waiting tools.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • count — integer — Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• advance_until_next_session

  Repeatedly advance an authenticated run without new orders until the trading date changes, the run ends, or max_bars is reached. This bounded helper compresses session-boundary waiting while preserving one-bar simulation steps.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • max_bars — integer — Maximum one-bar advances before stopping; defaults to 32 and acts as a safety cap.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• hold_until_end

  Repeatedly advance an authenticated run without adding orders until it completes, liquidates, or reaches max_bars. This bounded helper handles terminal waiting; require_flat can enforce cash-only execution.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • max_bars — integer — Maximum one-bar advances before stopping; defaults to 256 and acts as a safety cap.
  • require_flat — boolean — When true, reject the call unless the run has no open positions; use this guard for cash-only waiting.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• liquidate_and_finish

  Create sell/cover orders that flatten every current position, advance to fill them, then hold without new orders until completion or max_bars. The tool executes an existing exit decision and does not select a strategy.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.
  • max_bars — integer — Maximum post-liquidation one-bar advances before stopping; defaults to 256.
  • rationale — string — Optional short reason copied onto the generated exit orders.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• run_sandbox_smoke_test

  Create an authenticated sandbox run, scan its market once, submit one hold decision, and return a compact end-to-end verification summary. Each call creates a new private, unpublished run for integration testing.

  Parameters:

  • bot_name — string — Optional display name recorded on the sandbox run.
  • scenario_slug — string — Sandbox scenario slug; defaults to sandbox-nov-2024 when omitted.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

• get_results read-only

  Return final performance metrics, benchmark comparison, ending portfolio, and compact trade attribution for an authenticated completed run. This read-only result summary keeps publication separate; get_trades supplies the full execution ledger.

  Parameters:

  • run_id (required) — string — Completed run UUID returned by start_run.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• get_trades read-only

  Return every immutable filled-trade record for an authenticated run. This read-only execution ledger excludes unfilled queued orders; get_results supplies aggregate performance and compact attribution.

  Parameters:

  • run_id (required) — string — Run UUID returned by start_run.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• publish_run

  Make an authenticated completed run publicly accessible and submit its metrics to the BotTrade leaderboard. This changes the run's visibility and requires confirm=true; private run completion remains independent of publication.

  Parameters:

  • run_id (required) — string — Completed run UUID returned by start_run.
  • confirm (required) — boolean — Explicit publication confirmation; the server rejects the call unless this is true.

  Hints: read-only no · destructive no · idempotent not declared · open-world yes

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.