Paper Trader

Written by Katrina Ellison Geltman on Fri 26 September 2025.

Paper Trader

Paper Trader is a command-line trading simulation that I work on for fun. It's nowhere near being a real trading application - for starters, it's written in Python, so performance is atrocious - but it's fun to build and, hopefully, fun to play.

It exists in a perpetually unfinished state, so everything is a bit rough.

The code is on Github.

Gameplay

Here's what it looks like when you fire it up with python3 main.py:

Paper Trader Intro Screen

You have some products - forex and commodities because I like those, stocks because I felt compelled to throw those in - with a bid/ask spread for each.

You have a book with $10,000 cash.

Everything else is empty because you haven't started trading yet.

But market data is ticking, so you can see the bid and ask prices moving.

You decide to buy something. You make it a market order because #yolo.

You have to use the super janky CLI interface:

Type: 'b' <ret> 'AAPL' <ret> 5 <ret> 'market' <ret>

BAM! You got filled. The fill shows up in your Recent Fills list, and the position is added to your book.

Paper Trader One Fill

Then say you decide to sell some of your AAPL position. You put in a sell order, limit this time because you've wised up to reality. Now you have an active order

Paper Trader Active Order

until it fills

Paper Trader Two Fills

And that's the game. You sit there like a desk trader staring at the prices and trying to maximize your P&L. There's no way to win or lose, you just stop when you feel like it. I honestly don't find the gameplay all that compelling, which means either (1) I haven't optimized it for engagement enough, or (2) I am not cut out to be a desk trader (probably both). But I do really love hacking on it.

Cool Aspects

Some of my favorite parts are:

Market data

There are three market data modes: simulation, CLOB, and Twelve Data

  • Simulation is the default mode. It generates prices for each product by simulating the product's volatility. There are random events that cause price dislocations, keeping things spicy. This is my favorite mode to play.

  • CLOB (central limit order book) generates simulated orders (not simulated prices) and enters them in the exchange's order book. Your orders get matched (or not) against these simulated orders. This was fun to code because it felt more realistic, and also it's cool because you have the potential to impact the market, but I haven't really gotten into gameplay with it yet.

  • Twelve Data queries Twelve Data for real market data. This never really worked very well: it only worked when the market was open, it kept rate limiting me (to be fair I was on an el cheapo plan) and it didn't have any of my favorite commodity and bond products (I think you might be able to rectify this by upgrading from the el cheapo plan). But I keep the code around because, hey! it might come in handy someday.

Positions

There's a lot of tricky logic related to positions. When you buy or sell, you can add to or reverse your existing position in that product. For example, if you're long 5 lots of something and then you sell 7, you end up short 2 lots. P&L is calculated FIFO, so if you buy 2 lots at $100, then buy 3 lots at $105, then sell 3 lots at $110, you realize $25 in profit (2($110-100) + 1($110-105)). Getting all this position stuff working was a bit tough.

Order Types

You can enter market orders (filled immediately at market price) and limit orders (to be executed at your specified price or better).

What's Next (maybe)

I just kind of do what I want on this project, but here are some of my ideas:

  • Migrate to Rust (mostly because I want to learn Rust, also to see how much of a performance improvement I can squeeze out)

  • Split the simulation into multiple processes. Right now the exchange runs in the same process as the trading book, which is... not realistic lol 🙃.

  • Add more order types. I think I'll start with TWAP (time weighted average price) and iceberg (only a small portion of the order is shown to the market).

  • Improve the UI. This is not really my forte, but maybe I can pair with someone on it, or at least strongarm Claude Code into helping me.

Again, this is my favorite project, I just find working on it relaxing. Probably because I have worked on trading systems before and so know sorta kinda what they're supposed to do. And also because I am reasonably fluent in Python and can express my thoughts in code easily. I find it really easy to go into a flow state with this one and can work on it for hours.

If you have questions about or ideas for this project, please let me know! I'd love to improve it through collaboration with others.

Want to become a better programmer? Join the Recurse Center!