# Simulation Logic & Risk Controls PaperMarket is not a price oracle and not an execution venue.\ Its only job is to answer a narrow question: > “Given the current Polymarket book and this user’s virtual account state, what would have happened if this order had been sent right now?” The simulation engine is designed around three goals * stay as close as reasonably possible to Polymarket’s live order book * enforce simple but strict risk constraints on every user account * keep results deterministic and reconstructable from stored data This section describes how that engine behaves without exposing implementation details. ### Event driven simulation model The simulation is event driven. The only moments when state changes are: * when a user submits a virtual order * when a user triggers a balance top up Everything else (UI updates, streaming changes, chart redraws) is treated as read only. For each simulation event the engine performs a fixed sequence of steps 1. load the latest persisted state for the user (cash, positions) 2. load or resolve the relevant Polymarket market and token 3. obtain a fresh snapshot of the order book for that token 4. run the matching algorithm against that snapshot under account constraints 5. write the resulting order, trades and updated balances/positions to the datastore There is no background process that “drifts” positions over time and no hidden adjustments.\ If there is no explicit event, the simulation state does not change. ### Matching against the Polymarket book The engine treats the Polymarket CLOB as an immutable snapshot for the duration of a single simulation step. Conceptually, matching follows these rules * the snapshot from Polymarket defines the full ladder of bids and asks * prices are processed from best to worse on the opposite side of the order * trades are generated level by level until one of three limits is hit: * requested size is fully filled * there is no more liquidity at acceptable prices * account level risk limits (cash or position size) are reached From this process the engine generates * a single logical order record that reflects the user’s intent * one or more trade records representing the actual executed slices at concrete prices The original Polymarket book is not modified. PaperMarket never sends any updates back to it. ### Account level risk constraints The simulation engine enforces a small set of non negotiable risk rules on every request. **Cash constraint** * virtual cash must never go below zero * a buy is limited by the remaining cash divided by execution prices * if available cash cannot fund even the minimum slice at a price level, that level is skipped and no trade is created **Position constraint** * net position per token cannot go below zero * a sell is limited by the current long position in that token * if the user has no position, a sell order cannot generate trades **No leverage, no shorting** * the engine does not simulate borrowing, margin or cross collateral * all positions are fully cash backed at simulated entry * any order that would result in negative cash or negative size is automatically truncated to the maximum allowed safe size These constraints mean that a user can blow up their virtual balance but cannot create synthetic states that would be impossible on a fully collateralized venue. ### Handling partial fills Because the engine respects the actual state of the Polymarket book, orders frequently fill only partially. When there is insufficient liquidity or tight risk limits * the engine fills as much as possible at valid price levels * the executed part is recorded as one or more trades * the unfilled remainder is handled according to the time in force semantics of the order (for example discarded for IOC, kept as an open residual for GTC) From the user’s perspective this mirrors real trading behaviour\ big orders in thin markets fill in chunks and sometimes do not reach the originally requested size. ### Time and market state PaperMarket does not attempt to simulate latency, queue priority or order interaction between multiple traders. The model of time is intentionally simple * each simulation step assumes a single atomic interaction with the current Polymarket book * the snapshot used for matching is fetched as close as possible to the moment of the request * no assumptions are made about what happens between two independent simulation events This design keeps the engine focused on “what would have executed at this moment” rather than on replaying the full microstructure of the market. ### Determinism and reproducibility Given the same inputs the engine is expected to produce the same outputs. The key inputs for a simulation step are * the user account state before the event (cash and positions) * the order parameters (side, size, type, limit price, time in force) * the Polymarket order book snapshot used for matching The resulting data is * one order record with its final status * zero or more trade records with executed sizes and prices * updated balances and positions Because all of these outputs are persisted, it is possible to reconstruct * why the user’s position has a given size and average entry * why the cash balance moved in a specific way * how much of a requested order was actually filled and at which prices The engine does not retroactively edit historical trades to “clean” the track record. ### What the engine does not simulate For clarity, the simulation is deliberately narrower than a full Polymarket model.\ It does **not** include: * any notion of order queue priority or maker/taker roles * market impact beyond the visible liquidity in the current book * cross margining between unrelated markets * liquidity provision, LP shares or AMM style curves PaperMarket restricts itself to a simple, conservative approximation * take Polymarket’s current order book as given * apply transparent account level constraints * record exactly what would have traded under those constraints This is enough to build a meaningful paper trading track record without pretending to reproduce every detail of Polymarket’s internal engine. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://papermarket.gitbook.io/papermarket/technical/simulation-logic-and-risk-controls.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.