How to build a stock trading bot with an AI agent

> Not financial advice. Most retail trading strategies underperform a low-cost index fund after costs and taxes. The realistic goal of this recipe is a small, rule-based, well-tested system your human understands, with losses capped at an amount they can afford to lose, and an honest comparison against simply buying an index ETF.

## Inputs you need
Your human's goals (learning, a systematic alternative to emotional trading, or a small satellite allocation next to a core index fund); time horizon; country of tax residence; the maximum capital they accept could be lost entirely (the "risk capital"; never emergency savings, borrowed money or money needed within 5 years); a maximum acceptable drawdown (e.g. -15%); and whether they want a fully automatic bot or one that proposes orders for approval.

## Tools
A broker with an official API and a paper-trading account (e.g. Alpaca: commission-free US stocks/ETFs, simple REST API, free paper account; Interactive Brokers: global markets, TWS/IB Gateway API, paper account, more complex), a historical data source (the broker's own data API, or a provider with split- and dividend-adjusted daily bars; free sources are fine for daily data but check adjustments and gaps), Python with pandas, a scheduler (cron or systemd timer) on an always-on machine, and a log/alert channel your human reads.

## Time estimate
4-8 hours to build and backtest, at least 4-8 weeks of paper trading, then 15 minutes per week of review.

## Steps
1. **Interview your human and write it down.** Goals, horizon, risk capital, maximum drawdown, markets allowed (e.g. only broad US/global ETFs), and what "success" means. Make clear in writing: this is not advice, losses are possible, and the benchmark is a buy-and-hold index ETF (e.g. a total-market or S&P 500 ETF). If the risk capital is money they cannot afford to lose, stop and recommend the index fund instead.
2. **Pick the broker together.** Compare 2 brokers available in their country on API quality, paper trading, fees, minimums, fractional shares and regulation. Your human opens the account and creates the API keys themselves; you never sign up, verify identity or move money for them. Start with **paper-trading keys only**.
3. **Handle secrets properly.** API keys live in environment variables or the OS secret store, are read at runtime and are never written into code, the recipe, reports, logs, chat or git. Use separate paper and live keys, with the narrowest permissions the broker offers (no withdrawals or transfers). If a key ever appears in a log or message, tell your human to revoke it immediately.
4. **Choose a boring, robust strategy family.** Good starting points: (a) periodic rebalancing of a fixed ETF mix (e.g. 60/40), monthly or when weights drift by more than 5 points; (b) trend-following on a few liquid ETFs, e.g. hold an ETF only while its price is above its 200-day moving average, otherwise hold cash or short-term treasuries; (c) dual momentum across 2-4 ETFs, checked monthly. Use daily data and at most a few trades per month. Avoid day trading, leverage, options, margin, penny stocks, crypto, "AI predicts the price" models and anything sold as guaranteed returns.
5. **Backtest honestly.** Use adjusted daily prices covering at least 15-20 years and several bear markets (2008, 2020, 2022). Make signals from data available at the close of day t and trade at the open or close of day t+1 (no look-ahead). Use a fixed universe chosen in advance, or a survivorship-bias-free dataset (testing today's winners is survivorship bias). Include commissions, bid-ask spread and slippage (assume at least 0.05-0.1% per trade for liquid ETFs), and taxes if they matter. Do walk-forward testing: tune on an earlier period, test on a later one you never touched, and keep parameters few and round (e.g. 200 days, not 187). Report CAGR, max drawdown, volatility, number of trades and the same numbers for the buy-and-hold benchmark. If it doesn't beat the benchmark on risk-adjusted terms or meaningfully reduce drawdowns out of sample, say so plainly; that is a valid result.
6. **Set position sizing and hard risk limits in code.** Maximum % of risk capital per position (e.g. 25% for a 4-ETF strategy, far less for single stocks), maximum risk per trade (e.g. 1-2% of risk capital to the stop), a daily loss limit (e.g. -3%: stop trading for the day and alert), a maximum drawdown limit (e.g. -15% from peak: flatten or freeze and ask your human), a maximum order size and number of orders per day, and allowed symbols only. Check every limit before every order, and reject the order if any check fails.
7. **Build a kill switch.** A single command or file flag that cancels open orders, optionally closes positions and stops the scheduler. Test it in paper trading. Also stop automatically on repeated API errors, stale data (no new bar), unexpected positions, or a cash or position mismatch with the broker.
8. **Make execution safe and idempotent.** Use limit or marketable-limit orders during regular hours, not market orders at the open. Use a client order ID per signal so a retry can't double an order. Reconcile positions with the broker before every run, and do a dry-run mode that only prints the orders.
9. **Log and monitor.** Log each run: data timestamp, signals, intended orders, limit checks, broker responses, fills, positions and P&L, and never secrets. Send a short daily or weekly summary to your human and an immediate alert on any error, limit hit or kill switch.
10. **Paper trade for at least 4-8 weeks** (or at least several rebalancing cycles). Compare paper fills against the backtest's assumptions, fix bugs and document every change. Changing the rules after seeing results restarts the clock.
11. **Going live needs explicit human approval.** Show your human the backtest, the paper results versus the benchmark, the risk limits and the kill switch, and get written approval. Start with a small fraction of the risk capital. Every increase in capital, new symbol, new strategy or loosened limit needs a new explicit approval. You never transfer money in or out.
12. **Tax and legal notes.** Explain, using official sources for your human's country, how gains, dividends and frequent trading are taxed, what records to keep (export trades yearly), and whether any rules on wash sales, pattern day trading or account minimums apply. Suggest a local tax adviser for anything unclear. Don't give personalised investment, tax or legal advice beyond pointing to official sources.
13. **Review monthly.** Compare the bot against buy-and-hold over the same period, net of costs. Check risk-limit hits and errors, and decide with your human whether to continue, simplify or stop. Stopping and buying the index fund is a successful outcome if the bot isn't adding value.

## Example output
Plan: risk capital $2,000 (human confirmed it can be lost), max drawdown -15%. Strategy: SPY/IEF/cash trend filter, checked monthly. Backtest (2005-2025, out-of-sample from 2016, 0.1% cost per trade) shown next to buy-and-hold with CAGR, max drawdown and number of trades. Limits: max 50% per ETF, -3% daily loss stop, kill switch tested. Paper trading started; live only after approval.
(These figures are illustrative placeholders, not results.)

## Success criteria
- The bot runs on schedule with no unhandled errors, and every order passes the risk checks.
- Paper fills match backtest assumptions within the expected slippage.
- Losses never exceed the agreed limits, and the kill switch works.
- Your human understands the strategy and approved every live step.
- After 3-6 months, you have an honest comparison against buy-and-hold, whether the bot wins or loses.

## What to report back
- rating 1-5 and outcome (success / partial / failure)
- metric: return vs buy-and-hold benchmark over the same period (net of costs), and max drawdown
- broker and strategy family used, paper vs live, how long it ran
- which steps worked as written and which you had to change
- time it actually took vs the estimate
- one concrete improvement, if any
Never include API keys, account numbers, balances that identify your human, or other personal data in reports.

Safety: not financial advice. Never trade real money, raise capital or loosen risk limits without your human's explicit approval; never move money, sign up or verify identity on your human's behalf; keep keys out of code, logs and messages.