Skip to main content
Glama
jyron

BotTrade

by jyron
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

BotTrade Python SDK

Backtest any Python trading agent on a versioned historical-market benchmark.

CI PyPI Python MIT MCP Registry

Quick start

python -m pip install 'bottrade==0.2.0'
export BOTTRADE_API_KEY="bt_your_key_here"

Create my_agent.py:

import bottrade


def decide(observation: bottrade.Observation):
    symbol = observation.scenario.benchmark_symbol or observation.scenario.universe[0]
    bars = observation.bars[symbol]

    if observation.position(symbol):
        return bottrade.hold("Position is open")

    if len(bars) >= 2 and bars[-1].close > bars[-2].close:
        return bottrade.buy(symbol, quantity=10, reasoning="Positive one-bar momentum")

    return bottrade.hold("Waiting for momentum")


result = bottrade.backtest(
    decide,
    scenario="sandbox-nov-2024",
    agent_info=bottrade.AgentInfo(
        name="My momentum agent",
        framework="python",
        version="1.0",
    ),
)

print(result.run_id)
print(result.return_pct)
print(result.sharpe)
print(result.max_drawdown)

Run it:

python my_agent.py

backtest() calls the agent, submits its orders, advances the scenario, computes final metrics, and returns a typed BacktestResult.

Get an API key at bot-trade.org/account.

Related MCP server: backtester-mcp

Agent decisions

An agent receives one Observation and returns an order, a list of orders, or hold().

return bottrade.buy("AAPL", quantity=10, reasoning="Breakout")
return bottrade.sell("AAPL", quantity=5, reasoning="Reduce exposure")
return bottrade.short("TSLA", quantity=2, reasoning="Bearish signal")
return bottrade.cover("TSLA", quantity=2, reasoning="Close short")
return bottrade.hold("No signal")

Multiple orders:

return [
    bottrade.buy("AAPL", quantity=10),
    bottrade.buy("MSFT", quantity=5),
]

Each order owns its symbol, side, quantity, and reasoning.

Observation reference

observation.scenario       # Scenario metadata and universe
observation.sim_time       # Current simulated timestamp
observation.cash           # Available cash
observation.positions      # Current positions
observation.bars           # Visible OHLCV bars by symbol
observation.step_number    # Current runner step
observation.position("SPY")

Bars are typed objects:

latest = observation.bars["SPY"][-1]
print(latest.open, latest.high, latest.low, latest.close, latest.volume)

Stateful agents

import bottrade


class MovingAverageAgent:
    def decide(self, observation: bottrade.Observation):
        symbol = "SPY"
        closes = [bar.close for bar in observation.bars[symbol]]
        average = sum(closes) / len(closes)

        if closes[-1] > average and observation.position(symbol) is None:
            return bottrade.buy(symbol, quantity=10)

        return bottrade.hold()


result = bottrade.backtest(
    MovingAverageAgent(),
    scenario="sandbox-nov-2024",
    lookback=20,
)

Async agents

import asyncio
import bottrade


async def decide(observation: bottrade.Observation):
    signal = await get_model_signal(observation)
    if signal == "buy":
        return bottrade.buy("SPY", quantity=10)
    return bottrade.hold()


async def main():
    result = await bottrade.backtest_async(decide, scenario="sandbox-nov-2024")
    print(result.return_pct)


asyncio.run(main())

Agent provenance

Attach reproducible identity to every run:

info = bottrade.AgentInfo(
    name="AI Hedge Fund technical",
    framework="ai-hedge-fund",
    model="gpt-4.1",
    version="2026.7.10",
    source_url="https://github.com/virattt/ai-hedge-fund",
    source_revision="09dd33167bd6b4ea63ae32e7246e70e80632cc81",
    config={"analysts": ["technical_analyst"], "lookback": 180},
)

result = bottrade.backtest(agent, scenario="tech-2024-q2", agent_info=info)

Published run pages display this identity with the benchmark evidence.

Runner options

result = bottrade.backtest(
    agent,
    scenario="tech-2024-q2",
    lookback=50,
    decide_every=1,
    max_steps=10_000,
    resume_run_id=None,
    publish=False,
)

Option

Meaning

scenario

Ready scenario slug

lookback

Visible bars per symbol at each decision

decide_every

Call the agent every N bars

max_steps

Maximum simulator steps for this invocation

resume_run_id

Continue an existing active run

publish

Publish the completed run and trades

Command line

Export a function or agent object from a module:

bottrade backtest my_agent:decide --scenario sandbox-nov-2024
python -m bottrade backtest my_agent:decide --scenario sandbox-nov-2024

Add provenance:

bottrade backtest my_agent:decide \
  --scenario tech-2024-q2 \
  --name "My momentum agent" \
  --framework python \
  --agent-version 1.0 \
  --source-revision abc123

Run bottrade backtest --help for the complete command reference.

Explicit reference strategy

import bottrade
from bottrade.strategies import buy_and_hold

result = bottrade.backtest(
    buy_and_hold(quantity=10, symbol="SPY"),
    scenario="sandbox-nov-2024",
)

Here, quantity configures the selected buy-and-hold agent.

Integrations

Integration

Example

Plain Python

Custom momentum agent

OpenAI Agents SDK

Streamable HTTP MCP agent

LangChain / LangGraph

MultiServerMCPClient agent

OpenAI, Gemini, Grok

Multi-provider agent

AI Hedge Fund

AI Hedge Fund adapter

Result object

result.run_id
result.agent_info
result.scenario
result.return_pct
result.final_equity
result.sharpe
result.sortino
result.max_drawdown
result.trade_count
result.published

Publish a result with publish=True, then embed its evidence badge:

[![Tested on BotTrade](https://bot-trade.org/run/RUN_ID/badge.svg)](https://bot-trade.org/run/RUN_ID)

Low-level client

Use session() for explicit observation, submission, and stepping:

import bottrade

info = bottrade.AgentInfo(name="My manual agent", framework="python")

with bottrade.session("sandbox-nov-2024", agent_info=info) as run:
    while run.active:
        observation = run.observe()
        run.submit(decide(observation))
        run.step()

    results = run.results()

BotTradeClient exposes scenario discovery, run creation, observations, orders, stepping, results, publication, public runs, URLs, and badges. AsyncBotTradeClient provides the same operations with async methods.

import bottrade

with bottrade.BotTradeClient.from_env() as client:
    scenarios = client.list_scenarios()
    print([scenario.slug for scenario in scenarios])

Development

python -m pip install -e '.[dev]'
ruff check .
mypy
pytest
python -m build
twine check dist/*

BotTrade is designed for software evaluation, education, and research.

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
4Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jyron/bottrade'

If you have feedback or need assistance with the MCP directory API, please join our Discord server