How to build a trading bot with Python and Alpaca
The seven parts every trading bot needs, and how Charles builds each one in plain Python on Alpaca's free paper account.
A trading bot is less code than most people expect. Strip one down and you find the same seven parts every time: a broker connection, prices, a plan, a schedule, a record of what it did, a way to watch it and a way to stop it.
Below is each part, what it has to do, and how Charles does it. Charles is a free trading bot with all of its code public on GitHub. It's plain Python, so you can open each file named here and read it.
1. A broker connection
The bot needs somewhere to send orders. Alpaca is a common choice for Python because its API is built for code, and it offers a free paper account: orders fill against real market data, but the money is pretend.
Charles trades a free Alpaca paper account by default. The connection lives in alpaca_executor.py. Your keys don't go in the code. They sit in a .env file on your server, and you add or change them with one command:
charles-keys
If you build your own bot, keep this rule from the start. Keys in a file that git ignores, never in the code, never pasted into a chat.
2. Prices
A plan can't decide anything without data. At a minimum you need recent daily prices for everything the plan might hold, plus enough history to work out averages and momentum.
In Charles, the same decision code runs on live prices and on history. That matters more than it sounds. If your backtest and your bot use different code, you end up testing one program and running another.
3. A plan
This is the part people think of as "the bot", and it's often the smallest. Charles keeps its rules in allocator.py as pure functions: prices and settings go in, target holdings come out. No orders, no network calls. That makes the rules easy to test and easy to read.
The settings themselves live in strategy.json, checked against limits before they're used. The default plan is 80% in the whole market (SPY), plus 4 momentum picks at 5% each, chosen monthly from 100 big US companies, with a safety switch and aggressive mode on top. Aggressive mode is on in the default plan: while SPY is above its 200-day average and calm, the core sits in SSO, a 2x S&P 500 fund that moves about twice as much as the market each day, up and down. Any choppy day sends it back to SPY. Every part of the plan can be changed, and aggressive mode can be turned off.
A useful habit: give your plan a dry run that prints what it would do today without placing anything.
python rebalancer.py --dry-run
4. A schedule
Something has to wake the bot up. Charles runs as a service on your server: main.py holds the schedule, and once a weekday rebalancer.py checks the plan and places orders only if something needs to change. Most days it places no orders, so there's not much to watch. That's the trade-off of a slow plan: less happens.
5. A record of what it did
A bot you can't explain is a bot you can't trust. Every decision should leave a trace: what it held, what it bought or sold, and why.
Charles keeps its records in data/ and its logs in logs/. To read the log from the server:
charles-logs
Treat these folders as the bot's history. Don't delete them to tidy up.
6. A way to watch it
Logs are fine at a desk. On a phone you want a page. Charles has a web dashboard, webdash.py, that works on a phone: what each bot holds, what it did and why, and the news about what it holds.
The login has no passwords. The server prints a one-time link:
charles-login
A new install gets HTTPS, so the page isn't sent in the clear.
7. A way to stop it
Build the stop button before you need it. Charles has two. A daily loss limit, in risk_manager.py, pauses buys for the rest of the day. Pause holds all orders until you resume, from the dashboard or the server:
charles-pause charles-resume
How the parts fit together
Your server runs the schedule, the plan and the dashboard. Alpaca's paper account takes the orders. Your keys, settings and history stay on the server, and there's no subscription.
The shortcut: start from working code
Writing all seven parts yourself teaches you a lot. It also takes a while, and the boring parts (login, logs, pausing, undoing a change) are where home-made bots tend to be thin.
The other route is to install Charles and change it. One command installs it on a fresh Ubuntu server. The setup guide takes about 30 minutes, mostly waiting for installs, and a server at DigitalOcean costs about $6 a month.
Then change what you want. Charles is plain Python, so you can edit it by hand. Run the tests after each change:
python -m unittest discover -s tests -t tests
If you'd rather describe the change in plain words, Claude Code can do the editing. It isn't part of the free setup: it needs a paid Claude plan or Anthropic API credit, on your own bill, and a larger server than Charles needs on its own. The setup guide explains how to move up. Claude Code reads the code, makes the change you describe and runs the tests. You start it from the Charles folder:
curl -fsSL https://claude.ai/install.sh | bash exec bash cd ~/charles claude
Then ask things like "Add a card to the dashboard that shows my trades by month" or "Why did Charles pick these stocks this month?". The repo includes a CLAUDE.md file that tells Claude Code how the parts fit together and the rules to keep: paper money first, keys stay in .env, run the tests, and keep your changes on a git branch so updates still work.
Read what it changed before you keep it. It's your bot, on your server, and the code is yours to check.