PolySimulator API

Virtual prediction market trading API — build and test HFT bots with real Polymarket data, then go live with one config change.

PolySimulator HFT API v1

Build, test, and deploy prediction market trading bots in a risk-free environment powered by real-time Polymarket data. When you’re ready, switch to live trading by changing a single environment variable.

Quick Start

Get your API key and place your first trade in under 2 minutes.

API Reference

Interactive playground — test every endpoint with your API key.

Example Bot

Copy-paste a working Python trading bot and start experimenting.

---

Why PolySimulator?

Feature	Description
Real Data	Live mid-prices, bids, asks from Polymarket’s CLOB order book
Book Walking	Market orders fill against real order book depth — no infinite liquidity
Slippage Protection	Configurable max_slippage_bps on market orders
Limit Orders	GTC, IOC time-in-force with sub-second matching engine
Batch Orders	Up to 50 orders in a single request (tier-dependent)
WebSocket Feeds	Real-time price ticks and execution notifications
OHLCV Candles	Historical candlestick data for backtesting
CLOB-Compatible	/v1/clob/order mirrors Polymarket’s schema — URL-swap migration
String Numerics	All price/size/balance values are strings — no float precision loss

---

Architecture Overview

                    ┌─────────────────────────┐
                    │     Your Trading Bot     │
                    │   (REST + WebSocket)     │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   PolySimulator API v1   │
                    │   FastAPI + Redis + PG   │
                    └────────────┬────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                   │
    ┌─────────▼──────┐  ┌───────▼────────┐  ┌──────▼─────────┐
    │   PostgreSQL   │  │     Redis      │  │  Polymarket    │
    │  (Supabase)    │  │  (Price Cache) │  │  CLOB + Gamma  │
    └────────────────┘  └────────────────┘  └────────────────┘

---

Base URLs

Environment	URL
Production	https://api.polysimulator.com/v1
Local Dev	http://localhost:8000/v1

---

One Config Change to Go Live

1. Build with PolySimulator

   Develop and test your bot against the virtual API with a simulated $1,000 balance.

2. Validate Strategy

   Review your portfolio, trade history, and equity curve to confirm your edge.

3. Switch to Live

   Set TRADING_MODE=live and add your Polymarket credentials. Same API, real money.

The /v1/clob/order endpoint uses the same schema as Polymarket’s real CLOB API. When migrating to live, you can even point your bot directly at clob.polymarket.com with zero code changes.

---

AI Agent Integration (MCP)

PolySimulator docs are MCP-enabled. AI coding assistants like Cursor, Windsurf, and Claude Desktop can query the API schema directly:

# Add to your Cursor MCP settings
npx @mintlify/mcp@0.1.3 polysimulator

Your AI assistant will then be able to answer questions like:

• “Write a Python script to place a limit order on PolySimulator”
• “What rate limits apply to the free tier?”
• “Show me the WebSocket price feed message format”

---

What’s Next?

Authentication

Learn how API key auth works and create your first key.

Place a Trade

Execute market and limit orders with string-precision numerics.

WebSocket Feeds

Subscribe to real-time price updates and execution notifications.

Error Handling

Handle rate limits, errors, and build retry strategies for your bot.