lumibot

LumiBot AI Trading

Build AI trading agents. Backtest them. Trade with the same strategy.

LumiBot is a free, open-source Python framework for building trading bots. Write your own trading rules, let AI agents make decisions, or combine both. Backtest on historical data, inspect trades and results, and use the same strategy class with a supported broker for paper or live trading.

Full docs: lumibot.lumiwealth.com · Managed cloud: BotSpot.trade · MCP: BotSpot for AI coding agents

Read this in 中文 · Español · Français · Deutsch · 日本語 · 한국어 · Português · Русский

Why LumiBot?

• Native AI trading: agents research, reason and place orders from your prompts.
• Backtest before trading: evaluate AI decisions and Python rules on historical data, with charts, trades and logs.
• Same strategy for backtesting and trading: keep your strategy class; change the data source and broker runner.
• Multiple asset classes: stocks, options, futures, forex, crypto and prediction markets through supported brokers.
• The decision reaches a broker. Inspect the orders, fills and decision records. How execution works.

Connect your AI assistant

Build faster with BotSpot MCP. Claude, ChatGPT, Codex, Cursor, VS Code or another MCP-compatible assistant can help you write and test LumiBot strategies. Your coding assistant builds the code; the agents inside an AI-native strategy make its trading decisions while it runs.

Connect the free BotSpot MCP for:

• Skills: build LumiBot strategies.
• Free data: news, economics and SEC filings.
• Backtests: run tests and inspect charts, trades and logs.
• Cloud hosting: run bots on a schedule.
• Community: share ideas and learn from other builders.
• Marketplace: discover and publish strategies.
• Broker linking: connect accounts through BotSpot.

Connect your AI assistant

Connecting is free; hosted usage depends on your plan. For local coding help, install the free LumiBot trading skills. Your running strategy's agents can get research tools too: give them BotSpot MCP superpowers.

Three ways to build a strategy

• AI-native strategies: write prompts for trading agents.
• Python strategies: write your rules in Python.
• Hybrid strategies: combine Python rules and AI decisions.

Run your first AI backtest

The trading rules go in the prompt. Edit system_prompt below to change what the agent does. initialize() creates it once; on_trading_iteration() calls it on every iteration. This example has one agent that makes the trading decisions and places orders.

Use Python 3.10+. This example uses Yahoo daily prices and an OpenAI model; model calls incur charges.

pip install lumibot
export OPENAI_API_KEY="your-openai-api-key"

Save as my_ai_strategy.py:

from datetime import datetime
from lumibot.backtesting import YahooDataBacktesting
from lumibot.strategies import Strategy


class MyAIStrategy(Strategy):
    def initialize(self):
        self.sleeptime = "1D"
        self.agents.create(
            name="trader",
            default_model="openai/gpt-6-luna",
            reasoning_effort="medium",
            allow_trading=True,
            system_prompt=(
                "Trade SPY using its last 20 completed daily bars. "
                "Buy when the latest completed close is above their average; "
                "sell an existing position when it is below. Otherwise hold. "
                "Keep the position at or below 10% of portfolio value. "
                "Check cash, positions and open orders before acting. "
                "No shorting or leverage. Do not duplicate pending orders. "
                "Use only information available as of the strategy time."
            ),
        )

    def on_trading_iteration(self):
        self.agents["trader"].run(
            task_prompt="Review SPY, apply your rules and verify any orders.",
            context={"as_of": self.get_datetime().isoformat()},
        )


if __name__ == "__main__":
    MyAIStrategy.backtest(
        YahooDataBacktesting,
        datetime(2026, 4, 6),
        datetime(2026, 4, 11),
        budget=100_000,
        benchmark_asset="SPY",
    )

python my_ai_strategy.py

Review the decisions, orders and backtest charts. This demonstrates the API; it is not a claim that this trading rule is profitable.

For a complete two-agent team, read the researcher-and-trader example and follow its walkthrough:

python -m lumibot.example_strategies.ai_researcher_trader

Recorded run (made with Gemini): the existing two-agent example has source, decisions and trade records. These are historical results, separate from the single-agent example above.

Give your agents superpowers—for free

Add BotSpot MCP to your LumiBot strategy. Your AI agents get economic data, news and SEC documents, Marketplace strategies and Community knowledge through one free connection.

Already connected BotSpot to Codex, Claude Code or Cursor? Tell it: “Connect this LumiBot project to BotSpot MCP.” It can create the key and save the settings for you. Give your agents superpowers.

Or connect from the directory containing my_ai_strategy.py:

lumibot connect botspot
python my_ai_strategy.py

Approve the BotSpot sign-in when prompted. The connection saves BOTSPOT_RESEARCH_MCP_URL and BOTSPOT_RESEARCH_MCP_TOKEN in your project's .env. LumiBot loads them and attaches research tools automatically when self.agents.create(...) creates an agent. Keep that file out of Git.

Tell the agent what to research. For example, add this to its system_prompt:

Use BotSpot research tools to find evidence relevant to this strategy.
Cite sources and dates, explain data gaps, and use only information
available at the strategy time.

The connection guide explains assistant-led setup, manual key settings and available research tools.

Backtest a strategy

This is a traditional rules-based strategy: buy 10 AAPL shares on the first iteration and hold. It uses Yahoo historical prices, requires internet access, and makes no AI calls. Use Python 3.10 or later.

pip install lumibot

Save this as my_strategy.py:

from datetime import datetime
from lumibot.strategies import Strategy
from lumibot.backtesting import YahooDataBacktesting

class MyStrategy(Strategy):
    def on_trading_iteration(self):
        if self.first_iteration:
            aapl = self.create_order("AAPL", 10, "buy")
            self.submit_order(aapl)

MyStrategy.backtest(
    YahooDataBacktesting,
    datetime(2023, 1, 1),
    datetime(2024, 1, 1),
)

python my_strategy.py

Build a hybrid strategy

Use Python for the rules you want to control directly and an agent for the research or decision you want it to handle. A moving-average entry can trigger a read-only risk review; Python checks the structured answer, sizes the position and submits the order. Set that reviewer's allow_trading=False. See the hybrid flow and structured-answer examples.

Run the same strategy with a paper broker

After the backtest works, keep the MyStrategy class and replace the final MyStrategy.backtest(...) call with a broker runner. This example uses Alpaca paper trading:

export ALPACA_API_KEY='your-alpaca-key'
export ALPACA_API_SECRET='your-alpaca-secret'
export ALPACA_IS_PAPER=true
python my_strategy.py

import os
from lumibot.brokers import Alpaca
from lumibot.traders import Trader

ALPACA_CONFIG = {
    "API_KEY": os.environ["ALPACA_API_KEY"],
    "API_SECRET": os.environ["ALPACA_API_SECRET"],
    "PAPER": os.environ.get("ALPACA_IS_PAPER", "true").lower() != "false",
}

broker = Alpaca(ALPACA_CONFIG)
strategy = MyStrategy(broker=broker)

trader = Trader()
trader.add_strategy(strategy)
trader.run_all()

Start with paper trading. When you are ready for live trading, use the same strategy class and switch your broker account/configuration intentionally.

For full setup guides, broker tutorials, AI-agent docs, examples, and deployment notes, use the Lumibot documentation.

Explore LumiBot

• Python strategies and AI strategies
• Strategy API, data sources and brokers
• Compare frameworks and migrate from Backtrader
• CLI setup, including lumibot demo and lumibot init
• Run locally or deploy and cash accounting

Want help building your first AI trading bot?

Join the free challenge with Rob Grzesik, creator of LumiBot. Follow the training and learn how to turn an idea into an AI trading strategy.

Looking for deeper training? Explore the AI Trading Bootcamp. Prefer a hosted workspace? Explore BotSpot.

Project Growth

AI Bootcamp

Learn to build, backtest, and deploy trading strategies using AI. Join 2,400+ traders.

Contributing

We welcome contributions! Here's a video to help you get started: Watch The Video

Steps:

1. Clone the repository
2. Create a new branch: git switch -c my-feature
3. Install dev dependencies: pip install -r requirements_dev.txt && pip install -e .
4. Make your changes
5. Run tests: pytest
6. Create a pull request

Running Tests

pytest                          # Run all tests
pytest tests/test_asset.py      # Run a specific test file
coverage run; coverage report   # Show code coverage

Remote Cache Configuration

Lumibot can mirror its local parquet caches to AWS S3. See docs/remote_cache.md for configuration.

Architecture Documentation

• Backtesting Architecture - Data flow diagrams for Yahoo, ThetaData, Polygon
• Acceptance Backtests - End-to-end acceptance suite
• Environment Variables - All configurable env vars
• Changelog - Release notes
• AI Assistant Guide - Instructions for AI coding assistants
• Production Safety - ThetaData and production rules

Disclaimer

This software is provided for educational and informational purposes only. It is not financial advice and does not constitute a recommendation to buy or sell any security. Lumibot and BotSpot are not registered broker-dealers or financial advisors. Algorithmic trading involves substantial risk of loss, including the possibility of losses greater than your initial investment. Software bugs and errors can lead to rapid financial losses. Past backtest performance does not guarantee future results. Use this software at your own risk. You are solely responsible for compliance with all applicable laws and regulations regarding the assets you choose to trade.

Affiliate disclosure: some provider links or promo codes, including ThetaData, may support continued Lumibot development.

License

GNU General Public License v3.0 - View License

Contribute

See CONTRIBUTING.md for reproducible bugs, examples, tests, and focused pull requests. If LumiBot is useful to your work, star the repository and share an example with another developer.