Skip to main content

​
Simulation Realism & Honest Limits

PolySimulator is designed to provide venue-compatible paper trading for bot development: develop and validate a Polymarket trading bot against a compatible API (CLOB-compatible routes + drop-in SDK integration), with real-time prices and real accounting, without risking capital — then switch endpoints to go live. This page documents exactly what PolySimulator does and does not simulate. Transparent execution boundaries build reliable trading systems.

​
The Execution Model

​
1. ~1-Second Matching Loop

  • Resting limit orders are evaluated by a background matching loop running approximately every 1 second.
  • When the live venue price crosses your limit price, your resting order is filled on the next loop cycle.
  • Latency implication: High-frequency, sub-second latency arbitrage strategies will observe optimistic fills compared to live venue execution, because paper resting orders do not contend with exchange gateway transit latency or colocation queues.

​
2. Live-Price Fill Source

  • Every fill executes against live Polymarket venue prices sampled in real time from the Polymarket CLOB WebSocket and REST feeds.
  • Fills evaluate prices through a priority cascade:
    1. Order Book Walk (VWAP): Size-aware execution walking the merged primary and complementary order books.
    2. Top of Book (Best Bid/Ask): Best available touch price with complement-aware merging.
    3. CLOB Midpoint Cache: Sub-millisecond cached midpoint (best_bid + best_ask) / 2.
    4. Cached Display Price: Sanity-checked outcome price.

​
What Is and Is Not Simulated

​
Numeric exceptions (honest, not hidden)

​
Simulation Boundaries in Detail

​
No Queue-Position Modelling

In a live matching engine, when you place a limit order at the current bid, your order joins the back of the queue at that price level and only fills after all orders placed before yours have been matched or canceled. In PolySimulator paper trading, resting orders match whenever the venue price crosses your limit. If you place a limit BUY at 0.50andthevenuetradesat0.50 and the venue trades at 0.50, your order fills on the next loop iteration without simulating queue depletion ahead of you.
For realistic backtesting that models queue dynamics and historical book reconstruction, use the upcoming Simulation SKU rather than paper trading.

​
No Self-Impact

In live markets, large orders consume liquidity and shift the market price against the trader. In PolySimulator, your trades update your virtual portfolio and ledger, but do not affect external Polymarket order books. Size-aware VWAP book walking simulates the price you would receive given current book depth, but does not move the market for subsequent orders.

​
What PolySimulator Guarantees

Decimal-Safe String Numerics

Price, quantity, and balance values are transmitted as JSON strings (e.g. "0.52") except the documented Polymarket-parity exceptions in String Numerics (GET /v1/tick-size/{token_id} minimum_tick_size and /v1/markets/updown live_price.buy/sell). The backend still enforces exact decimal math without binary float rounding errors.

Multi-Wallet Isolation

API keys trade exclusively against an isolated API Sandbox Wallet (10,000baselineforPro,10,000 baseline for Pro, 25,000 for Pro+). The primary UI wallet (MAIN) is never modified by API trading.

Deterministic Idempotency

Duplicate submissions carrying the same client_order_id (or Idempotency-Key header) return the existing order without double-executing.

Lifelike Error Taxonomy

Order validation rejects off-grid ticks (INVALID_ORDER_MIN_TICK_SIZE), below-minimum sizes (INVALID_ORDER_MIN_SIZE), and insufficient balance with identical Polymarket-style error envelopes.

​
Operational Boundaries & Beta SLA

  • Beta Availability: PolySimulator API Beta is a development and validation environment. While we aim for high uptime (>99.9%), the beta surface does not carry a formal financial SLA.
  • Rate Limits: Per-key rate limits are enforced with fixed windows — a per-second bucket and a per-minute bucket, each keyed on the current clock second/minute (e.g. Free: 2 RPS / 120 RPM, Pro: 30 RPS / 1,800 RPM).
    A fixed window has a boundary burst: because the counter resets at each clock second, a client aligned to that boundary can send its full per-second allowance just before the tick and again just after — briefly about twice the nominal RPS. We do not treat that as abuse, but do not design around it either: it is a property of the window, not a documented allowance, and tightening it later would break a client that relied on it.
    The limiter fails open. If Redis is unreachable the limit check returns full headroom rather than rejecting your request, so during a cache outage the stated limits are not enforced. This is a deliberate availability trade — we would rather serve you unthrottled than fail your requests because our cache is down — and it is stated here so the guarantee you are buying is the guarantee you actually get.
  • Deprecation Policy: Breaking API or schema changes during public beta will be communicated with at least 14 days notice via email and documentation changelogs.