Market mechanics & the record

Deals

Every session each market publishes a menu of wholesale deals. A deal is:

• an item bundle (a primary item family plus optional add-on perks, with a grade and an origin) — the unit you buy;
• a landed unit cost — what you pay per unit;
• the list price — what a unit resells for on the market (fixed per market);
• a quoted sales velocity — expected units sold per session, a property of the item family;
• a maximum volume per order.

Landed costs and menu sizes move with market conditions. What the platform publishes about them is what is on the menu itself — the lowest, mean and highest landed cost listed, the number of deals and desk bids (quote in the API, the book and the ticker in the terminal) — never the state of the engine behind it.

Execution and settlement

At session close the desk buys the inventory of every funded order. Over the next 8 sessions each position sells into that deal's realised demand at list price; proceeds are credited to the account every session. Each unit still in stock costs a holding fee per session. After the horizon, unsold units are written off. Some deals sit in a hidden downside event: demand is cut sharply and a logistics surcharge of up to 55 % of the inventory cost basis is charged at settlement.

Realised profit of a position = revenue − inventory cost − fulfilment fee − holding fees − surcharge (write-offs are the inventory cost never recovered).

The desk's own book

The desk runs a legacy policy on every menu: it scores margin and velocity against a strictness level that drifts over time, executes deals above the threshold at a volume of roughly 1.25–2 sessions of expected demand, and takes a small share of exploratory positions. Its bids are shown on every menu (desk bids ×N) and its results are on record.

The record: executed vs rejected

• The desk has traded these markets for months before this platform went live; that history is loaded into the record at first start (newest sessions first; progress at /api/v1/markets/{id}/coverage).
• Since going live, every session close records what actually happened: the desk's executions plus every account holder's fill.
• A menu row is therefore either executed / observed — somebody actually bought it, and its session-by-session sell-through and realised result are on record — or rejected — nobody bought it and no outcome exists. Results of executed trades are revealed session by session: sales as they happen, the final P&L once the horizon has passed.
• Sales are observed, demand is not. A position reveals what it sold each session, capped by the stock it had. Once it sells out, demand beyond that stock is unknown, so the realised profit of an executed deal is on record at every volume only if it never sold out — otherwise only up to the executed volume. No engine state, driver or latent variable is ever served.
• The history API (/history, /trades, /tape, /dataset.csv), the terminal, the asset browser and the deal analyser all serve this record and nothing else. Estimates built from it inherit the selection of whoever executed the trades.
• Projections are naive by construction. The only forecasts on the platform — the trend overlay of the terminal and the deal analyser — are a least-squares line (or a plain average) through the observed points on screen, extended over the settlement sessions, and the plain cash arithmetic of a position applied to that path. Every input is shown; the API returns them so the fit can be redone.
• Menus are deterministic from the engine's recorded seed and configuration, frozen at first start and verified at every start.

For research deployments only, XGM_ORACLE=1 enables an oracle that also reveals outcomes of rejected deals (history?reveal=full, extra series in the explorer). It is off by default.

Datasets

dataset.csv?split=labeled returns executed trades of settled sessions (date, key, cluster, unit_cost, list_price, sv, isv, actor, executed_qty, realized_pnl, units_sold, sold_out, qty, profit, is_executed_qty; with expand_qty=true one row per volume at which the realised profit is knowable: every volume for deals that never sold out, up to the executed volume for deals that did). split=unlabeled returns every menu row of recorded sessions with accepted (executed by anyone), desk_policy_accepted and desk_qty, and no outcomes.

Fees (defaults)

Swapping the market engine

The engine behind the menus implements a small interface (offers(tick), ground(offer), settlement()) in xgames/sim/kernel.py; xgames/sim/core.py is the production engine and a toy random_walk engine is included as a template. Select with XGM_KERNEL. Orders, settlement, cash, the record and the console are engine-agnostic.