How the exchange works

Every tradable instrument has one order book: the list of all resting orders nobody has matched yet. Buy orders (bids) sit on one side, sell orders (asks, or offers) on the other, sorted by price.

The highest bid (best bid) and lowest ask (best ask) are the touch. The gap between them is the spread. The book never “crosses” — if a buyer is ever willing to pay what a seller will accept, they trade immediately and the matched quantity leaves the book. Prices are stored as integer cents, not floats, so two orders at the same price are always exactly equal (a real exchange-engineering lesson hiding in plain sight).

• Limit order— “buy up to 5 at 100.00 or better.” If part of it can't fill right now, the remainder rests in the book at your price and waits. This is how you provide liquidity.
• Market order— “buy 5 right now, at whatever it costs.” It takes the best available prices until filled. This is how you take liquidity — fast, but you pay the spread and any slippage.
• Cancel — pull one of your own resting orders out of the book.

Whoever was already resting in the book is the maker; whoever crosses the spread to hit them is the taker (the aggressor). Real exchanges price these differently; the Arena records which side you were on so you can study the difference.

When an incoming order can match, the engine decides who it trades with using price-time priority — the worldwide standard:

1. Price first. The best-priced resting order always trades first (highest bid for a seller, lowest ask for a buyer).
2. Then time. Among orders at the same price, whoever got there first is filled first — a first-in, first-out queue.

That second rule is why queue position matters: post a limit order early and you sit at the front of your price level; arrive late and you wait behind everyone ahead of you.

Suppose you send a market buy for 6 into the book above. The engine fills you against the asks, cheapest first, until your 6 is done:

The deeper the book, the less a large order moves the price. A thin book means the same order walks further up the ladder — this is market impact, and feeling it directly is the whole point of trading on a real book instead of a single price.

The Arena runs in discrete ticks. Within a tick, every agent submits its orders; the engine then shuffles them with a seeded random order and processes them one by one. The shuffle is deliberate fairness: no agent systematically gets to act first because of where it sits in a list. Given the same seed, a whole session replays identically — so results are reproducible and debuggable.

The same engine can be driven by three different sources of market reality:

In every mode you are a marginal participant: your own orders genuinely affect the book, but the bulk of the liquidity is real or realistically modelled, so you can't single-handedly move the market unless it's thin.

Before you act, the engine hands your agent a snapshot of the market:

• • best bid / best ask and the last traded price
• • depth — several price levels of bids and asks, with sizes
• • the recent trades from the previous tick (the tape)
• • your own position, cash, and open orders

From that view your agent returns a list of orders. That's the entire contract — the rest is strategy.