# Key Concepts This page explains the main concepts that appear in PaperMarket.\ The goal is to keep the mental model as close as possible to Polymarket while making clear what is simulated and what is taken from live data. ### User account Every person who uses PaperMarket has a user account that is stored on the backend. A user account includes * login with email and password * a virtual cash balance * a list of orders * a list of trades * open and closed positions All of this data exists only inside PaperMarket. It is not linked to a wallet address and it is not visible on chain. ### Virtual cash balance Each account has a single cash balance that is measured in virtual dollars.\ On first sign up the account receives a starting amount of virtual cash for example ten thousand virtual dollars. The balance moves when the user trades * buys reduce cash * sells increase cash There are no deposits and no withdrawals from external wallets.\ The balance changes only through simulated trades and through the balance top up action. When the balance becomes low or is fully used the user can press a button in the interface to top up the virtual cash.\ The top up sets the balance to the starting amount again.\ If the user has one thousand dollars left and presses the button the balance becomes ten thousand.\ If the user has seven thousand dollars and presses the button the balance also becomes ten thousand.\ The balance never goes above the configured starting amount because of a top up. The top up does not remove orders trades or positions and it does not clear the account history. ### Markets and tokens PaperMarket works with the same markets that exist on Polymarket. For each loaded market the app keeps * the event and market slugs * the market question * the YES and NO token identifiers that come from Polymarket * a link back to the original Polymarket market A user never creates their own markets in PaperMarket.\ They always start from an existing Polymarket market and bring it into the app by pasting a link or a slug. The YES and NO tokens in PaperMarket represent the same outcomes as on Polymarket.\ The simulation buys and sells these tokens in quantities that the user specifies. ### Order book and price For each token PaperMarket queries the Polymarket CLOB API to get the current order book. The order book consists of * bids which are buy offers from other participants * asks which are sell offers from other participants Each level has a price and a size.\ Prices are expressed between zero and one.\ A price represents the cost in dollars to buy one unit of a YES or NO token in the simulation. PaperMarket also derives a mid price for each token.\ The mid price is used as a reference to value open positions in the portfolio. ### Orders When a user trades they submit an order.\ An order describes what the user wants to do in the simulation. Each order has * side which is buy or sell * token which is YES or NO for a selected market * size which is the number of tokens to buy or sell * type which can be market or limit For limit orders the user also sets a limit price between zero and one. PaperMarket supports two time behaviors for orders * Immediate or cancel where the system tries to fill against the live book at once and cancels any unfilled remainder * Good till cancel where any unfilled part of a limit order stays open in the PaperMarket database until it is filled or canceled Orders are never sent to Polymarket.\ They are only used inside PaperMarket to simulate how the user would trade against the live order book. ### Trades Trades are the filled parts of orders. Whenever an order matches with bids or asks from the Polymarket book PaperMarket creates one or more trade records.\ Each trade has a size and a price.\ The combination of all trades in an order determines how much of the order was filled and at what average price. The simulation uses trades to * adjust the cash balance * update positions in each token * build the portfolio and PnL history that the user sees ### Positions A position shows how many tokens a user currently holds in a specific YES or NO token. For each token PaperMarket keeps * the net size after all buys and sells * an average entry price computed from past trades * the current value based on the latest mid price * the unrealized PnL for that position If the net size is positive the user is long that token in the simulation.\ If the net size is zero the user has no open position in that token. Positions change only when trades are created.\ There is no separate manual adjustment of positions in the app. ### Portfolio and PnL The portfolio aggregates all positions and shows how the virtual account is doing. The portfolio view includes * cash balance * a list of open positions by token * for each position its size average entry price current value and PnL PnL represents the difference between what the user paid for a position and what it is worth at current mid price.\ It is used as a simple measure of how a trading idea is performing over time inside the simulation. ### Balance top up At any moment a user can increase their available virtual cash through the top up control in the app. Topping up the balance * sets the cash balance back to the starting amount * does not remove or change open positions * does not delete orders or trades * does not clear the portfolio or PnL history This allows a trader to continue paper trading when their virtual balance has been reduced while keeping the full record of how their strategy has behaved so far. --- # 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/get-start/key-concepts.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.