How to use Alpaca's free paper account with a self-hosted bot
What an Alpaca paper account is, how Charles sends it orders, and how to make the keys and add them to your own server with charles-keys.
Charles trades through Alpaca, and by default it trades in Alpaca's paper account. This guide covers what that account is, what Charles does with it, and how to get its keys onto your server.
What a paper account is
A paper account is a practice account at a broker. It has a balance of pretend money and real market data. You send it orders the same way you would send them to a real account, and it fills them against real prices. Nothing you do there touches money of your own.
Alpaca gives every account a paper account for free. You don't add money to it. It has two keys, and those are what Charles needs.
For a trading bot, that's a useful place to start. You can watch a plan run on today's prices and see every order it places, without a deposit.
How Charles uses it
Charles is a free trading bot that runs on a server you own. All of its code is public on GitHub, in plain Python.
The pieces fit together like this:
- Your server runs Charles. It reads market data and follows the plan you've set.
- When the plan calls for a trade, Charles sends the order to your Alpaca paper account through Alpaca's API.
- Alpaca fills it against real market prices and keeps the paper balance and holdings.
- The dashboard on your server shows what the bot holds, what it did and why.
The code that talks to Alpaca lives in alpaca_executor.py. If you want to see exactly which calls it makes and when, that file is where to read. The plan's rules are in allocator.py, and the daily check that decides whether anything needs to change is in rebalancer.py.
One thing to expect: most days Charles places no orders. The plan is checked daily but changes rarely, so the paper account can sit still for a while. That's normal. It also means there isn't much to watch from one day to the next.
Why paper is the default
A new install trades paper money linked to real market data. You don't have to change a setting to get there, and you don't have to remember to.
The point is to let you see the whole plan work before you change or keep anything. You can read the plan, watch the orders it sends, check the reasons on the dashboard, change a slider and see what happens. If you don't like how it behaves, nothing is lost but a little time.
Paper trading isn't the same as a forecast. Real markets can fill orders differently, and what a plan did on paper says nothing about what it will do next. It's a way to understand the mechanism, not to judge an outcome.
Make your Alpaca paper keys
You need an Alpaca account. It's free.
- Sign up at alpaca.markets.
- Open your paper account in Alpaca's dashboard. Make sure you're looking at paper, not anything else.
- Generate API keys for it. You get two values: a key ID and a secret key.
- Copy both somewhere private for the next few minutes. Treat the secret like a password.
To change a key later, run charles-keys.
Add them with charles-keys
This assumes Charles is already installed. If it isn't, the setup guide walks through it: one command on a fresh Ubuntu server, about 30 minutes in all, most of it waiting for installs. A server at DigitalOcean costs about $6 a month.
Open a terminal on your server and run:
charles-keys
Add your Alpaca paper key ID and secret. The keys are saved in .env in the Charles folder on your server. They don't go anywhere else: there's no Charles account and nothing hosted for you. Your keys, settings and history stay on your server.
If you'd rather edit the file yourself, the setup guide does it this way:
nano ~/charles/.env
Then start the bot and get a link to the dashboard:
charles-start charles-login
charles-login prints a one-time link. There's no password to set.
If Charles was already running when you changed the keys, restart it so it picks them up:
charles-restart
If the keys don't work
The most common reason the bot won't start is a mistyped key. Check what it's saying:
charles-logs
Things to look for:
- A stray space at the start or end of a key.
- The key ID and the secret swapped.
- Keys from a different Alpaca account than the paper one you meant.
Fix the key with charles-keys, then run charles-restart. charles-status tells you whether it's running.
Changing how it uses Alpaca
Because Charles is plain Python on your own server, you can change anything about how it talks to Alpaca. Read alpaca_executor.py, change it, and run the tests:
python -m unittest discover -s tests -t tests
Claude Code can also do this for you: describe the change in plain words, and it reads the code, makes the change and runs the tests. Read what it changed before you keep it.
If you want to hold every order while you look around, use Pause on the dashboard's Home page, or run charles-pause. Pausing never sells anything. charles-resume lets orders through again.