Building a Prediction Market From Scratch (2): The Concepts That Make the Rest Easy

There’s no code in this one. Before we open up the engine, I want to make sure a handful of words mean the same thing to you as they do to me — prediction market, YES and NO shares, the order book, price-time priority. Get these into your bones and the code in the next chapters stops looking like code and starts looking like common sense. Skip them and you’ll spend the whole series translating in your head.

(This is chapter two. The hands-on “boot it and place an order” walkthrough is chapter one, and it’ll land once the public repo is up. You can read this first either way — concepts before keyboard works fine here.)

What a prediction market actually is

The cleanest way I know to explain it: a prediction market lets people bet on whether something in the future will happen, and the price of that bet is the crowd’s estimate of the odds.

Take a concrete question: “Will it rain tomorrow?” The market turns it into a share.

• A YES share pays out 100 cents if it does rain, and nothing if it doesn’t.
• A NO share pays out 100 cents if it doesn’t rain, and nothing if it does.

So at any moment, the YES price plus the NO price comes to about 100 cents. If YES is trading at 60, the crowd is effectively saying “about 60% chance.” The price is a live, money-backed probability — which is exactly why these markets tend to read reality better than a poll. People are voting with their wallets, not their mouths.

Say Alice buys one YES share at 60 cents. If it rains, she gets 100 back — up 40. If it doesn’t, she’s out the 60. That’s the whole game, and everything we build sits on top of this one idea.

YES and NO are two faces of one coin

Here’s the observation that quietly simplifies the entire engine. Since YES and NO always add up to 100, “buying NO at 40” and “selling YES at 60” are the same bet wearing different clothes. Both of them are wagering that it won’t rain.

That has a real engineering payoff: an event only needs one order book. The person who wants to buy YES and the person who wants to buy NO are natural counterparties — you can quietly translate “buy NO at 40” into “sell YES at 60” and let them trade on the same YES book. The engine in this project does exactly that: a small normalization step flips a NO order into a YES order and routes it to the canonical book. We’ll watch it happen in the matching chapter.

There’s a second way to get shares, and it’s worth knowing now because it’s how Polymarket works too. It’s called split, or minting: you put up 100 cents of collateral and get one YES and one NO share in return. Then you sell the half you don’t want. The reverse is merge — hold one YES and one NO, hand them back, get your 100 cents. This project implements both.

The order book

The order book is the heart of any trading system. It’s just the ledger of everyone’s unfilled intentions — who wants to buy, who wants to sell, and at what price:

        ASKS — people willing to sell (higher prices on top)
        ┌──────────────────────────┐
        │  65¢ ──  20 shares        │
        │  62¢ ──  50 shares        │  ← best ask = 62
        ├──────────────────────────┤   ← the gap between them is the "spread"
        │  60¢ ── 100 shares        │  ← best bid = 60
        │  58¢ ──  30 shares        │
        └──────────────────────────┘
        BIDS — people willing to buy (lower prices on bottom)

A bid is “I’ll buy at this price” — say, 60¢ for 100 shares. An ask is “I’ll sell at this price.” A trade happens the moment some bid’s price meets or beats some ask’s price.

In this project the book is kept with a sorted map from price to quantity (so the levels stay in order automatically) and a queue of order IDs at each price (so we remember who showed up first). When we crack open the matching code, that’s all you’ll find under the hood — a bid walks down from the lowest ask, an ask walks up from the highest bid, and trades fall out where they cross.

Price-time priority, and why it’s fair

When a crowd lines up on the same side, who gets filled first? The rule is price first, then time.

Better price goes ahead — a higher bid, a lower ask, jumps the queue. When two orders sit at the same price, the one that arrived first gets filled first. That’s why each price level is a queue: newcomers join the back, fills come off the front.

I like this rule because it’s the quiet thing that keeps a market honest. You can’t buy your way to the front by being clever about timing or connections — you get ahead by offering a better price, or by being early. Nothing else. The first time you implement it yourself and watch three orders at the same price fill in the exact order they arrived, it stops being a definition and starts being something you trust.

And two flavors of order, while we’re here. A limit order names a price — “no worse than this” — and whatever doesn’t fill right away rests on the book and waits. (That’s the order Alice places in the hands-on chapter.) A market order skips the price and just takes whatever’s best available right now; anything it can’t fill is cancelled rather than left sitting.

The same shapes, on-chain: Polymarket

Everything you just read has a twin on Polymarket — the largest prediction market in the world — except theirs runs on a blockchain. I find the parallel genuinely useful, because it tells you what’s essential and what’s just an implementation choice.

Their matching is an off-chain order book, same idea as ours. Their YES/NO shares are on-chain tokens (the Conditional Token Framework — ERC-1155 tokens, each redeemable for 1 USDC if its side wins); ours are just numbers in a positions map. Their “split” and “merge” are contract calls that mint and burn those tokens against USDC collateral; ours are commands the engine handles in memory. When a trade settles, their CTF Exchange contract checks signatures and atomically swaps USDC for tokens; ours writes rows to a database. Their collateral is USDC; ours is an internal balance. And when the real-world event finally resolves, they lean on UMA’s optimistic oracle to decide the outcome; we let an admin call resolve.

Same skeleton — match off-chain, settle centrally — with the settlement layer swapped out. So none of this is a toy version of some “real” thing. It’s the real mechanism, with the database standing in for the chain. Each choice has its trade-offs, and I’ll put them side by side when we get to the money and to settlement.

Where we go next

That’s the whole vocabulary. A YES share is a 100-cent bet on something happening; YES and NO add to 100, so one book serves both sides; the book matches by price then time; limit orders rest, market orders don’t. Hold those four and the engine ahead will feel less like a wall of Rust and more like a careful write-down of things you already believe.

Next chapter we step back and look at the architecture — three services, talking over Redis, and the journey a single order takes from an HTTP call to a matched trade. And yes, every line of it lands in the open repo, free, no strings.