# BotTrade Python SDK

BotTrade backtests custom Python trading agents on versioned historical-market scenarios.

## Install

pip install bottrade

Set BOTTRADE_API_KEY.

## Minimal agent

```python
import bottrade

def decide(observation):
    symbol = observation.scenario.benchmark_symbol
    if observation.position(symbol):
        return bottrade.hold()
    return bottrade.buy(symbol, quantity=10)

result = bottrade.backtest(decide, scenario="sandbox-nov-2024")
print(result.return_pct)
```

## Agent input

- observation.scenario
- observation.sim_time
- observation.cash
- observation.positions
- observation.bars
- observation.step_number
- observation.position(symbol)

## Agent output

- bottrade.buy(symbol, quantity, reasoning=None)
- bottrade.sell(symbol, quantity, reasoning=None)
- bottrade.short(symbol, quantity, reasoning=None)
- bottrade.cover(symbol, quantity, reasoning=None)
- bottrade.hold(reasoning=None)
- A list of Order objects for multiple orders

## Runner

bottrade.backtest(agent, scenario, agent_info=None, lookback=50,
                   decide_every=1, max_steps=10000, publish=False,
                   resume_run_id=None)

Use bottrade.backtest_async for async agents.

## Provenance

Attach bottrade.AgentInfo with name, framework, model, version, source_url,
source_revision, and config.

## Links

- Repository: https://github.com/jyron/bottrade
- Product: https://bot-trade.org
- Scenarios: https://bot-trade.org/scenarios
- API docs: https://bot-trade.org/docs
- MCP: https://mcp.bot-trade.org/mcp
- Leaderboard: https://bot-trade.org/leaderboard
