bottrade

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.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "wait_seconds": {
      "description": "Optional seconds to poll for OAuth completion before returning; values above 120 are capped at 120. Use 0 to return the current status immediately.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "additionalProperties": false
}

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

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "id_or_slug": {
      "description": "Exact scenario slug or UUID returned by list_scenarios.",
      "type": "string"
    }
  },
  "required": [
    "id_or_slug"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "agent_info": {
      "additionalProperties": false,
      "description": "Optional structured provenance for the agent executing the run.",
      "properties": {
        "framework": {
          "description": "Agent framework or orchestration system.",
          "type": "string"
        },
        "model": {
          "description": "Model identifier used for the run.",
          "type": "string"
        },
        "name": {
          "description": "Agent name recorded with the run.",
          "type": "string"
        },
        "source_revision": {
          "description": "Commit hash or other immutable source revision.",
          "type": "string"
        },
        "source_url": {
          "description": "Public or private source repository URL.",
          "type": "string"
        },
        "version": {
          "description": "Agent or strategy version.",
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "bot_name": {
      "description": "Optional display name for the bot, strategy, or experiment associated with this run.",
      "type": "string"
    },
    "scenario_slug": {
      "description": "Exact scenario slug returned by list_scenarios.",
      "type": "string"
    }
  },
  "required": [
    "scenario_slug"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "lookback": {
      "description": "Number of bars to return per symbol; the total request must remain within the server's 500-row budget.",
      "minimum": 1,
      "type": "integer"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    },
    "symbols": {
      "description": "Optional symbol subset. Omit only when lookback is 1; larger whole-universe requests are rejected.",
      "items": {
        "description": "Exact ticker symbol from the scenario universe.",
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "lookback": {
      "description": "Bars per symbol; defaults to 30 when omitted and is capped at 120.",
      "minimum": 1,
      "type": "integer"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    },
    "symbols": {
      "description": "Between 1 and 8 symbols, normally selected from scan_market.suggested_inspection.",
      "items": {
        "description": "Exact ticker symbol from the scenario universe.",
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "run_id",
    "symbols"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    },
    "step_count": {
      "description": "Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.",
      "minimum": 1,
      "type": "integer"
    },
    "trades": {
      "description": "Orders to queue before the next bar; an empty array means advance without placing an order.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "quantity": {
            "description": "Order size, positive. Fractional allowed for crypto pairs (e.g. 0.25 for BTC/USD); equities are typically whole.",
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "reasoning": {
            "description": "Optional short reason recorded with this order.",
            "type": "string"
          },
          "side": {
            "description": "Order direction: buy opens/increases a long, sell reduces a long, short opens/increases a short, and cover reduces a short.",
            "enum": [
              "buy",
              "sell",
              "short",
              "cover"
            ],
            "type": "string"
          },
          "symbol": {
            "description": "Exact ticker symbol from the scenario universe.",
            "type": "string"
          }
        },
        "required": [
          "symbol",
          "side",
          "quantity"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "run_id",
    "trades"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "action": {
      "description": "Decision type: hold requires no orders; trade requires at least one order.",
      "enum": [
        "hold",
        "trade"
      ],
      "type": "string"
    },
    "orders": {
      "description": "Orders to queue when action is trade; use an empty array when action is hold.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "quantity": {
            "description": "Order size, positive. Fractional allowed for crypto pairs (e.g. 0.25 for BTC/USD); equities are typically whole.",
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "reasoning": {
            "description": "Optional short reason recorded with this order.",
            "type": "string"
          },
          "side": {
            "description": "Order direction: buy opens/increases a long, sell reduces a long, short opens/increases a short, and cover reduces a short.",
            "enum": [
              "buy",
              "sell",
              "short",
              "cover"
            ],
            "type": "string"
          },
          "symbol": {
            "description": "Exact ticker symbol from the scenario universe.",
            "type": "string"
          }
        },
        "required": [
          "symbol",
          "side",
          "quantity"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "rationale": {
      "description": "Optional short reason recorded with the decision.",
      "type": "string"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    },
    "step_count": {
      "description": "Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "run_id",
    "action",
    "orders"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "count": {
      "description": "Bars to advance. Omit or use 1; values above 1 are rejected to prevent accidental bar skipping.",
      "minimum": 1,
      "type": "integer"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "max_bars": {
      "description": "Maximum one-bar advances before stopping; defaults to 32 and acts as a safety cap.",
      "minimum": 1,
      "type": "integer"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "max_bars": {
      "description": "Maximum one-bar advances before stopping; defaults to 256 and acts as a safety cap.",
      "minimum": 1,
      "type": "integer"
    },
    "require_flat": {
      "description": "When true, reject the call unless the run has no open positions; use this guard for cash-only waiting.",
      "type": "boolean"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "max_bars": {
      "description": "Maximum post-liquidation one-bar advances before stopping; defaults to 256.",
      "minimum": 1,
      "type": "integer"
    },
    "rationale": {
      "description": "Optional short reason copied onto the generated exit orders.",
      "type": "string"
    },
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "bot_name": {
      "description": "Optional display name recorded on the sandbox run.",
      "type": "string"
    },
    "scenario_slug": {
      "description": "Sandbox scenario slug; defaults to sandbox-nov-2024 when omitted.",
      "type": "string"
    }
  },
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "run_id": {
      "description": "Completed run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "run_id": {
      "description": "Run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "confirm": {
      "description": "Explicit publication confirmation; the server rejects the call unless this is true.",
      "type": "boolean"
    },
    "run_id": {
      "description": "Completed run UUID returned by start_run.",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "confirm"
  ],
  "additionalProperties": false
}