AlphaBook

Nothing you write runs on our servers — your strategy runs on your machine and only ever sends us orders. That means you can use any language, any library, and any amount of compute you like; the server is just the exchange.

1. Join or create a run. On the run page, open Connect your bot.
2. Download the ready-made Python client (algo_client.py) — plain standard-library Python, no installs — and paste in your run id and API token.
3. Run it: python algo_client.py. It polls the market, calls your on_tick, and posts the orders you return.
4. Edit on_tick, re-run, iterate. Prefer another language? Hit the same REST endpoints yourself.

Every player who joins gets a base on a shared map, and one line of arithmetic decides what they can do with it:

credits = 2000 starting grant + your trading P&L + what your buildings earn - what you have spent

Trade well and the map opens up. Trade badly and the budget closes: credits floor at zero rather than going negative, so a losing run stalls your expansion but never takes back what you have already built. The map advances once every 5 seconds; production lands and units get their movement back on that beat.

The four resources

• Credits pay for everything. They come from your trading P&L, and from factories and markets once you have built them.
• Materials come from lumber camps and mines, and are needed alongside credits for most buildings and every military unit.
• Food comes from farms. Every worker eats one per tick. Run out and workers start leaving.
• Workers staff your buildings and crew your units. You start with a cap of 6 and raise it with housing. Population grows on a food surplus.

Workers are the constraint that bites first. Food producers are staffed before anything else, so a shortage idles a factory rather than starving the farm feeding it, but a factory you cannot crew earns nothing at all.

Buildings

Your base cannot be built or demolished. It claims the ground around it at the start, and losing it puts you out of the world game.

Units

Terrain

Taking ground

• An explorer claims any unclaimed tile it walks over, so movement is territory. It never takes a tile someone already owns.
• A settler spends itself to claim a two-tile radius anywhere it can reach, which is how you jump to a distant patch of hills.
• To take owned ground you have to fight for it. Units standing on a tile shield whatever is underneath, so you beat the garrison first, then bring the building down.
• Attacking costs the unit its turn, and the defender always strikes back. Probing a fort with an explorer is a real loss, not a free look.
• Terrain and forts add to the defender's strength, and a fort stiffens the tiles around it as well as its own.
• A cannon does double damage to buildings and folds quickly if it is caught in the open.
• Raze someone's base and you take their entire territory. They are out of the world half of the game, though they keep trading.

How the world is ranked

Development score, and it rewards exactly what it sounds like: 3 points per tile you hold, the value of every building standing, 4 points per worker, and the value of your army. A building is worth roughly a third of its credit cost, so putting money into the map always beats sitting on it.

You can play this half by hand from the Empire tab on the run page, or drive it from your bot's on_world_tick. Both go through the same rules, so neither is a shortcut.

The client wraps these, but here they are if you want to roll your own. Authenticate with Authorization: Bearer <token> from the Connect panel.

GET  /market-sim-py/run/{id}/market      # snapshot: books, your position, pnl, seconds_left
POST /market-sim-py/run/{id}/orders      # {"orders": [ ... ]}  — matched on arrival
POST /market-sim-py/run/{id}/cancel      # {"item": "WIDGET"}   — or {} for all
GET  /market-sim-py/run/{id}/token       # your bearer token

GET  /market-sim-py/world/catalogue      # costs, yields and unit stats (static)
GET  /market-sim-py/run/{id}/world       # the whole map, your empire, the standings
POST /market-sim-py/run/{id}/world/actions   # {"actions": [ ... ]}

A world action looks like

{"type": "build",  "building": "farm", "x": 5, "y": 7}
{"type": "train",  "unit": "explorer", "count": 2}
{"type": "move",   "unit_id": "u3", "x": 6, "y": 7}
{"type": "attack", "unit_id": "u3", "x": 7, "y": 7}    # must already be adjacent
{"type": "found",  "unit_id": "u9"}                    # spend a settler on an outpost
{"type": "trade",  "side": "buy", "resource": "materials", "qty": 20}

Actions apply in order and are reported on one by one, so a batch of six builds you can only half afford gets you the ones you can pay for plus a reason for the rest.

An order looks like

{"item": "WIDGET", "side": "BUY",  "price": 99.95, "qty": 10}   # resting limit order
{"item": "WIDGET", "side": "SELL", "qty": 10}                  # market order, remainder pulled
{"action": "cancel_all"}                                        # pull all your resting orders
{"action": "cancel_all", "item": "WIDGET"}                      # pull one item's orders

The market snapshot gives you

market[item] = {"bid", "ask", "bid_qty", "ask_qty", "mid", "spread", "last"}
             # any price may be null if that side of the book is empty
me = {"positions", "open_orders", "cash", "pnl", "fills", "last_reject"}

The rules the exchange enforces

• Position limit 1000 per item, long or short. Resting orders count — an order that could breach the limit if fully filled is rejected outright.
• Rate limit 10 orders/second per player (with a small burst). Send more and the extra come back marked rate_limited rather than applied — so a fast connection can't turn the game into a latency race. The client paces itself for you.
• Matched on arrival. Orders hit the live book the moment they land, first-come-first-served within the rate limit.

The house bots

Every run starts with a market maker and a liquidity taker, but the host can add more from the run page — different archetypes (market maker, conservative, mean-reversion, bull/long, bear/short, liquidity taker, momentum) at four skill levels (noob → normal → good → cracked). A smarter bot tracks the hidden fair value faster and quotes tighter, so it's a tougher opponent. Bots can be scheduled to enter partway through a run, and all of them respect the same 1000 limit you do.