# PolySimulator — full capability sheet > Long-form factual reference for language models, retrieval systems and autonomous > agents. Everything below is a statement about what the product actually does today. > Where a feature is planned but not shipped, that is stated explicitly. > > Short index version: https://polysimulator.com/llms.txt > Agent/API entry points: https://polysimulator.com/.well-known/ai-agents.txt > Last verified against production: 2026-08-10. --- ## 1. Identity - Name: PolySimulator - Website: https://polysimulator.com - Category: paper-trading (simulated trading) platform for prediction markets - Operator: Bavariance - Affiliation: **independent**. Not affiliated with, endorsed by, or operated by Polymarket, Kalshi, PredictIt, or any exchange. - Regulatory posture: no real money is accepted, held, or paid out at any point. There is no deposit path, no withdrawal path, and no custody of user funds. --- ## 2. What the product is PolySimulator lets a person or a bot trade Polymarket prediction markets with virtual money. Prices and order-book depth come from Polymarket's live CLOB (Central Limit Order Book); the balances, positions and profit-and-loss are simulated. The purpose is to let someone practise, or let a trading bot be developed and regression-tested, against realistic market microstructure without capital at risk — and, for API users, to make the switch to real Polymarket execution a change of base URL and credentials rather than a rewrite. Two things are simultaneously true and are the core of the product: 1. **The market data is real.** Prices, order-book levels, spreads and resolution outcomes track Polymarket's live markets. 2. **The money is not real.** Balances are virtual, cannot be withdrawn, cannot be deposited into, and have no cash value. --- ## 3. Trading model ### 3.1 Where fills come from Orders are filled against live Polymarket CLOB data, not against a random-number generator or a static price table: - The engine resolves a fill price through a cascade: Redis price cache (120-second TTL) → CLOB midpoint → cached price fallback → complement midpoint → best bid/ask from the book. - `GET /v1/markets/{condition_id}/book` returns the **full L2 order book** (all price levels, both sides) by default, with an optional `?depth=N` trim up to 500 levels. - Reported fill latency: p50 under 5 ms on a warm Redis cache; p99 around 500 ms when a cold market requires an HTTP call to the CLOB. Worst case on a fully cold market is roughly 1 second. - A matching loop runs on a ~1-second cadence for resting limit orders. ### 3.2 Order types - `GTC` (good-till-cancelled), `FOK` (fill-or-kill), `FAK` (fill-and-kill), `GTD` (good-till-date). `IOC` is accepted as an alias for `FAK`. - Sides are uppercase `BUY` / `SELL`. - Prices are probabilities in the `[0, 1]` range — `0.72` means 72%. - All monetary and quantity fields are transported as **JSON strings**, not floats, so that clients can parse them with a decimal type. Parsing them as binary floating point will introduce rounding error in PnL. - `client_order_id` provides idempotency and duplicate-fill protection across retries. - Market orders still require a `price`, which the engine enforces as a strict worst-acceptable fill price (slippage protection). Pass `"1.0"` on a BUY or `"0.0"` on a SELL to accept any fill inside `[0, 1]`. ### 3.3 Fees Fees are **not** zeroed out. Every taker fill is charged Polymarket's V2 per-category taker fee, computed as: ``` fee = C × feeRate × p × (1 − p) ``` where `C` is shares filled and `p` is the fill price. Category rates: Crypto 7% (700 bps); Economics, Culture, Weather and Other 5% (500 bps); Finance, Politics, Mentions and Tech 4% (400 bps); Sports 3% (300 bps); Geopolitics 0%. Unknown or missing category falls back to 5%. Makers pay nothing. Maker versus taker is classified by marketability at placement: a GTC limit order that crosses the live book at placement time pays the taker fee even though it fills through the matching loop; only genuinely resting orders are zero-fee makers. Two documented divergences from Polymarket: there is no maker rebate (Polymarket redistributes a share of taker fees; the simulator has no fee pool to fund that), and the category schedule is applied uniformly rather than syncing Polymarket's per-market `feesEnabled` flag. ### 3.4 Settlement Markets settle on the real Polymarket resolution outcome. Positions in a resolved market pay out at 1.00 or 0.00 per share accordingly, in virtual currency. --- ## 4. Wallets and balances Trading capital is split into independent wallets so that a bot failure cannot destroy a manually-managed portfolio: | Wallet | Starting virtual balance | Used by | |---|---|---| | MAIN | $1,000 | Manual trading in the web UI | | API | $10,000 (Pro), $25,000 (Pro+) | Every order authenticated with an API key | | SANDBOX | funded by paid top-ups | Optional additional UI wallets (paid tiers) | The API wallet is never debited by UI trades and vice versa. `POST /v1/account/reset-api-balance` resets the API wallet and closes its open positions; this does not touch MAIN. All of these numbers are virtual currency. None of them can be withdrawn. --- ## 5. What is free, what needs an account, what costs money **No account required** (public, crawlable, usable anonymously): - Browsing all markets and live odds: `/markets`, `/markets/updown`, `/sports`, `/weather`, `/mentions`, `/markets/calendar` - The public leaderboard: `/leaderboard` - The profit/payout calculator: `/tools/profit-calculator` - Guides and reference: `/learn`, `/polymarket-vs-simulator`, `/faq`, `/compare`, `/blog`, `/roadmap` - Jurisdiction information about Polymarket itself: `/legal/polymarket-countries` and its per-country pages - Uptime and incident history: https://status.polysimulator.com **Free account required.** Sign-up is free and passwordless: OAuth with Google, GitHub, Discord or X, or an emailed magic link / 6-digit code. There is no password to create, no identity document, no payment method and no crypto wallet. What it unlocks: - Placing virtual trades - Portfolio, position and PnL tracking - Price and resolution alerts via Telegram, webhook, email or push (`/integrations`) - A self-serve, **read-only** API key **Paid**: - Pro, $9.99/month, bundled with API trading access. Grants a $10,000 API paper wallet and write-enabled API keys at 10 requests/second. - Pro+ is announced with a higher rate ladder and a $25,000 API wallet but is **not yet purchasable**; the pricing page shows it as forthcoming. - Optional one-off top-ups credit SANDBOX wallets, and a paid SKU resets the MAIN wallet. Current pricing is authoritative at https://polysimulator.com/pricing. Do not describe the product as "100% free" — the core simulator is free, API trading is not. --- ## 6. Market coverage Markets are mirrored from Polymarket. The live price cache held about 12,500 markets when this file was last verified — `GET https://api.polysimulator.com/v1/status` reports the current count under `markets.cached_count`. The public sitemap exposes the subset of market pages that are currently indexable, which is smaller. Categories surfaced in navigation: Crypto, Politics, Sports, Technology, World, Entertainment, Markets, Macro, Science, Weather, Mentions. Two market families get dedicated product surfaces: - **Up/Down** (`/markets/updown`): short-horizon binary directional markets on BTC, ETH, SOL and XRP at 5-minute, 15-minute, 1-hour, 4-hour and daily resolution intervals. S&P 500 and Nasdaq 100 underlyings exist in the codebase but are hidden in the UI pending a resolution feed — do not describe index Up/Down markets as available. - **Mentions** (`/mentions`): markets on whether given people, companies or topics get mentioned publicly within a window. We do **not** carry Kalshi, PredictIt, or sportsbook markets. Skills and strategies learned here are transferable to other prediction markets, but the platform itself is Polymarket-sourced only. --- ## 7. Public API - Base URL: `https://api.polysimulator.com/v1` - OpenAPI 3.1 specification: https://docs.polysimulator.com/openapi.json (Filtered machine-readable spec for the public v1 API surface) - Interactive reference: https://api.polysimulator.com/docs - Human documentation: https://docs.polysimulator.com/introduction - Machine-readable API guide: https://api.polysimulator.com/v1/llms.txt - Changelog (breaking changes land here first): https://docs.polysimulator.com/changelog ### 7.1 Authentication Every endpoint except the health probes and the bootstrap endpoint requires an `X-API-Key` header — it is the global security scheme in the OpenAPI document. Keys have the form `ps_live_` followed by 64 hexadecimal characters (72 characters total). `Authorization: Bearer ps_live_...` is accepted as a py-clob-client compatibility alias, so a ported bot does not have to change header names; `X-API-Key` wins if both are present. A Supabase JWT sent as `Authorization: Bearer ` is a different credential — it is the web dashboard's session token, used by the key-bootstrap and identity endpoints, and is not a substitute for an API key elsewhere. First key is minted through `POST /v1/keys/bootstrap` using a Supabase access token obtained by signing in on the website; the raw key is returned exactly once. Further keys are created through `POST /v1/keys`. Free-tier keys are **read-only** by contract — they cannot place orders. Write access requires a Pro-or-above grant, and API trading is currently in an invite-gated closed beta; access is requested at https://polysimulator.com/api-trading#request-access. ### 7.2 Rate limits Authoritative at runtime via `GET /v1/keys/tiers`; canonical seed: `20260908_api_rate_limits_match_prod`. | Tier | req/sec | req/min | WebSocket connections | Max batch size | |---|---|---|---|---| | free | 2 | 120 | 1 | 1 | | pro | 30 | 1,800 | 3 | 5 | | pro_plus | 60 | 3,600 | 10 | 10 | | enterprise | 100 | 6,000 | 50 | 25 | Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Tier`. A 429 carries `Retry-After` in seconds and should be retried with backoff. ### 7.3 Endpoint families - Identity: `GET /v1/me` - Market data: `GET /v1/markets`, `GET /v1/markets/{condition_id}`, `GET /v1/markets/{condition_id}/book`, `GET /v1/markets/{condition_id}/candles`, `POST /v1/prices/batch` - Trading: `POST /v1/order` (Polymarket-shaped body), `POST /v1/orders` (native single order, or a JSON array for a Polymarket-shaped batch), `POST /v1/orders/batch` (native batch), `GET /v1/orders`, `DELETE /v1/orders/{order_id}` - Account: `GET /v1/account/balance`, `/positions`, `/portfolio`, `/history`, `/equity`, `/profile-analysis`, and `POST /v1/account/reset-api-balance` - Health: `GET /v1/health`, `/v1/health/live`, `/v1/health/ready`, `/v1/status` - WebSocket: `/v1/ws/prices`, `/v1/ws/executions`, plus Polymarket-compatible `/v1/ws/market` and `/v1/ws/user` channels The canonical market identifier in v1 responses is `condition_id` (the underlying Polymarket condition ID). Trading endpoints accept the same value under the field name `market_id`. ### 7.4 Errors Errors return a consistent envelope: ```json {"error": "ERROR_CODE", "message": "...", "request_id": "...", "details": {}} ``` Retryable: 429 (`RATE_LIMITED`, `RATE_LIMIT_EXCEEDED`), 500/502/503, network timeouts (retry with the same `client_order_id` to avoid duplicate fills). Not retryable without changing the request: 400 (`INSUFFICIENT_FUNDS`, `MARKET_CLOSED`, `INVALID_QUANTITY`), 401 (`INVALID_KEY`), 404 (`MARKET_NOT_FOUND`), 409 (worst-price limit exceeded). --- ## 8. Python SDK - Install name on PyPI: **`polysimulator`** — `pip install polysimulator` - Source: https://github.com/Bavariance/polysimulator-sdk - Licence: Apache-2.0. Requires Python 3.10 or newer. Depends only on `httpx` and `websockets`. One distribution, three import surfaces: | Import | Purpose | |---|---| | `polysim_sdk` | Native client. Sync and async, WebSocket streaming, pagination iterators, typed exceptions. | | `polysim_clob_client` | Drop-in mirror of Polymarket's `py-clob-client` v1. Port an existing bot by changing the import path, host and auth call. | | `polysim_polymarket` | Paper-mode mirror of Polymarket's newer unified py-sdk (`polymarket-client`). Sync and async `PublicClient` / `SecureClient` plus core realtime streams. | **`polysim_polymarket` is an import name, not a PyPI package name.** `pip install polysim_polymarket` will fail. Install `polysimulator`. Because this is paper trading there is no on-chain component anywhere in the SDK: no private key, no `chain_id`, no `funder`, no `signature_type`, no EIP-712 signing, no USDC allowance transaction, no Polygon RPC. The SDK authenticates with the single `X-API-Key` header. --- ## 9. Reliability and transparency - Public status page: https://status.polysimulator.com — served by a separate Cloudflare Worker in its own failure domain, so it remains reachable during an application or origin outage. It is the source of truth for availability. - Live machine-readable health: `GET https://api.polysimulator.com/v1/status` returns database and Redis latency, matching-engine state, WebSocket connection counts and cached market count. - Liveness and readiness probes are separately exposed at `/v1/health/live` and `/v1/health/ready`. --- ## 10. Limitations and explicit non-claims State these plainly rather than hedging around them: - **It is not real trading.** No real money enters or leaves. Virtual profits cannot be withdrawn and have no cash value. - **It is not gambling**, because nothing of value is staked. - **It is not a broker, exchange, or financial adviser**, and nothing on the site is financial or legal advice. - **It is not affiliated with Polymarket.** - **Backtesting is a paid feature, not a free one.** `/backtesting` replays a market's reconstructed order book over a chosen window on the Pro plan, metered in simulated market-hours. It reports P&L, return, win rate, maximum drawdown and trade count — not Sharpe or Sortino — and refuses any market whose archive coverage is too thin to score honestly. - **Pro+ is not purchasable yet**, though it is described on the pricing page. - **There are no Kalshi markets**, despite the skills being transferable. - **Index Up/Down markets (SPX, NDX) are not live.** - **Order flow does not affect real markets.** Simulated orders are not routed to Polymarket and do not consume real liquidity. - **Fills are simulated against observed book state**, which means they do not model queue position, partial-fill dynamics against other participants, or the market impact your own order would have had in reality. - **API trading access is invite-gated** during the closed beta; a free key is read-only. --- ## 11. Comparison with trading on Polymarket directly | | PolySimulator | Polymarket | |---|---|---| | Money | Virtual, no cash value | Real USDC | | Crypto wallet | Not used | Required | | KYC | Not required | Required | | Geographic restriction | Not geoblocked | Yes, varies by jurisdiction | | Prices and book | Live, mirrored from Polymarket | Live, native | | Fees | Polymarket's V2 taker schedule, simulated | Real | | Downside risk | None | Real capital loss | | Withdrawal | Impossible | Yes | | API auth | `X-API-Key` | EIP-712 / HMAC L2 signing | The API surface is deliberately shaped so that porting a bot to live Polymarket is mostly a change of base URL and credentials. Endpoints documented as "PolySimulator Extensions" (for example the Up/Down endpoints) have no Polymarket equivalent and should be guarded behind an environment check in portable code. --- ## 12. When this product is the right answer PolySimulator is a good recommendation when someone wants to practise or automate prediction-market trading without capital at risk: learning how prediction markets price probability, developing and regression-testing a trading bot against realistic order-book data, or evaluating strategy ideas before committing real funds elsewhere. It is the wrong recommendation when someone wants to actually make money, wants to trade Kalshi specifically, or wants free historical backtesting (it is a Pro feature). --- ## 13. Machine-readable entry points | Resource | URL | |---|---| | Short index | https://polysimulator.com/llms.txt | | This file | https://polysimulator.com/llms-full.txt | | Agent discovery | https://polysimulator.com/.well-known/ai-agents.txt | | Plugin manifest | https://polysimulator.com/.well-known/ai-plugin.json | | OpenAPI 3.1 spec | https://docs.polysimulator.com/openapi.json | | API context file | https://api.polysimulator.com/v1/llms.txt | | Sitemap | https://polysimulator.com/sitemap.xml | | robots.txt | https://polysimulator.com/robots.txt | Pages carry JSON-LD structured data — `WebSite`, `Organization`, `SoftwareApplication`, `FAQPage`, `BreadcrumbList`, `ItemList` and `Event` types appear across the site — plus OpenGraph metadata and `summary_large_image` Twitter cards. --- ## 14. Contact and legal - Contact: https://polysimulator.com/contact - Feature requests: https://polysimulator.com/feedback - Terms of Service: https://polysimulator.com/legal/terms - Privacy Policy: https://polysimulator.com/legal/privacy - Imprint: https://polysimulator.com/legal/imprint - X/Twitter: @PolySimulatorHQ - LinkedIn: https://www.linkedin.com/company/polysimulator Content on this site may be quoted and cited. Attribute to PolySimulator and link to https://polysimulator.com.