# Overview

PaperMarket lets a trader load any supported Polymarket market, see the live order book and chart for that market and place virtual trades that are executed against the current Polymarket book.\
All balances, orders, positions and trades are stored on the PaperMarket backend and are separate from the real Polymarket system.

This page gives a high level view of what a typical session in PaperMarket looks like from sign up to closing a position.

### From sign up to first trade

1. Sign up and sign in

   A user creates an account with email and password.\
   On first sign up the backend creates a user record, assigns an internal user id and credits the account with a virtual cash balance.\
   After sign in the app shows the main trading page.
2. Load a Polymarket market

   On the main page there is a field where the user can paste a link or slug from Polymarket.\
   The backend parses this input and calls the public Polymarket APIs to find the related event and market.\
   It retrieves the question, the market and event slugs, the YES and NO token identifiers and other basic data and sends this information back to the frontend.\
   The app then shows the market question and prepares to display the book and the price history.
3. See live book and chart

   For the selected market the app fetches the current order book for the YES and NO tokens from the Polymarket CLOB API.\
   It also loads historical price data for the YES token to build a basic price chart.\
   A websocket connection subscribes to live updates so that bids, asks and mid price move in real time while the user watches the market.
4. Place a virtual order

   On the right side of the main page the user chooses

   * buy or sell
   * YES or NO token
   * order size
   * order type which can be market or limit

   For limit orders the user also sets a price between zero and one.\
   When the user submits the form the frontend calls the PaperMarket trade API.\
   The backend pulls the latest order book for the selected token and simulates how much of the request can be filled against current bids or asks.\
   It checks available virtual cash for buys and available position size for sells and then records the order and the resulting trades in the database.
5. Track positions and PnL

   Each time a trade is recorded the system updates the user cash balance and their position in the traded token.\
   The portfolio view shows open positions for each YES or NO token that the user has traded.\
   For every position the app displays size, an average entry price that is derived from past trades and a current value that is based on the latest mid price from the live book.\
   The difference between value and cost is shown as PnL so the user can see how their virtual strategy is performing.
6. Close or adjust a position

   To reduce or close a position the user places a new order on the opposite side in the same market.\
   Buys increase position size and sells decrease it.\
   When the position size in a token returns to zero the user is flat in that market and the result of the sequence of trades remains visible as PnL in their history.

### What runs on Polymarket and what runs on PaperMarket

Polymarket provides

* markets with questions and outcomes
* live order books through the CLOB API
* historical price data through the public APIs

PaperMarket provides

* user accounts, virtual cash and positions
* order simulation based on the live Polymarket book
* portfolio, history and PnL views
* an optional balance top up that restores the starting virtual cash amount while keeping all positions and trades

The live market comes from Polymarket.\
The simulation and all account state live inside PaperMarket and never touch real USDC or on chain contracts.


---

# 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/overview.md?ask=<question>
```

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.