Build, simulate, and validate trading bots against live market structure before deploying real capital.
Endpoints mirror the Polymarket CLOB API. Orders walk the live order book — real fills, real slippage, real depth. Ship to production by swapping the base URL.
What it is
03 · pillarsEndpoint shapes mirror the Polymarket CLOB API — request payloads, response models, market identifiers. A CLOB-compat shim covers most read-side calls plus cancel and the write-side `POST /v1/clob/order`. Strategies built here translate to live trading with a base-URL swap and wallet credentials.
Orders walk the live Polymarket order book. BUY fills at best ask, SELL at best bid, against actual depth. The `price` field is a worst-acceptable limit — identical to Polymarket. FOK / IOC / GTC supported. There is no midpoint-fill cheat code.
Every key carries a tier — `Free` for self-serve, `Pro` for the closed-beta cohort, `Enterprise` on invite. `X-RateLimit-Remaining` headers + `Retry-After` on 429 let SDKs pace proactively. The reference Python SDK does this for you.
Quickstart · the minimum viable trade
POST. A real fill.Once your beta cohort is activated, set POLYSIM_API_KEY and place an IOC market BUY. The order walks the live book and you get back the realised price, fee, slippage in basis points, and your new account balance.
# Place an IOC market BUY on Yes — fills against the live book.
curl -X POST https://api.polysimulator.com/v1/orders \
-H "X-API-Key: $POLYSIM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"market_id": "0x57e6...d4d8",
"side": "BUY",
"outcome": "Yes",
"quantity": 10,
"order_type": "market",
"price": "0.99",
"time_in_force": "IOC"
}'
{
"order_id": "ord_8f2c…",
"status": "FILLED",
"price": "0.378",
"quantity": "10",
"notional": "3.78",
"fee": "0.0000",
"slippage_bps": 12,
"account_balance": "9996.22"
}sample · v1 endpoints, schema may shift before public release
from polysim_sdk import PolySimClient
with PolySimClient() as client: # POLYSIM_API_KEY from env
me = client.me()
print(me["api_balance"])
fill = client.place_order(
market_id="0x57e6...d4d8",
side="BUY",
outcome="Yes",
quantity=10,
order_type="market",
price="0.99", # worst-acceptable fill
time_in_force="IOC",
)
print(f"filled at {fill['price']} — fee ${fill['fee']}")Reference SDK
Sync HTTP wrapper. Auth, request pacing, exponential back-off on 429 and 5xx, structured exceptions. This is a reference implementation — clone or copy it from examples/python-sdk/ in the polysimulator repo. Not yet on PyPI. Async client and a WebSocket helper are next.
The surface
| Method | Path | Notes |
|---|---|---|
| GET | /v1/me | Caller profile, tier, balance, api_balance. |
| GET | /v1/markets | List markets. Filter by hot_only, tag, etc. |
| GET | /v1/markets/{condition_id} | Single market — question, outcomes, prices. |
| GET | /v1/markets/{condition_id}/book | Live order book snapshot. |
| POST | /v1/orders | Place order — market or limit, FOK / IOC / GTC. |
| GET | /v1/orders | List the caller’s orders (filterable by status). |
| DELETE | /v1/orders/{order_id} | Cancel a single open order. |
| POST | /v1/cancel-all | Cancel every open order on the account. |
| GET | /v1/account/positions | Current positions (OPEN / CLOSED filter). |
| GET | /v1/account/portfolio | Equity, exposure, realised + unrealised P&L. |
| POST | /v1/clob/order | Polymarket-CLOB-shaped order endpoint. |
| GET | /v1/keys/tiers | Authoritative rate-limit + balance per tier. |
| WS | /v1/ws/prices | Real-time price stream for subscribed markets. |
| WS | /v1/ws/executions | Fill notifications for limit orders (GTC). |
Limits
authoritative · GET /v1/keys/tiers
Documented limitations, not bugs. Filing them as bugs will be closed wontfix until the relevant fix lands.
Every API key a user owns hits the same `accounts.api_balance` pool. Per-key isolation is tracked as issue #840 and ships shortly after the public beta opens. Until then, treat `api_balance` as user-scoped, not key-scoped.
Currently `is_maker = (time_in_force == "GTC")`. A GTC limit that crosses on submit is booked as a maker fill (zero fee) in the simulator, but would be a taker on Polymarket. We over-count makers by design until the classifier is tightened post-launch.
Order-book cache TTL is 300s (env-tunable via `POLYMARKET_ORDERBOOK_TTL_SECONDS`). For markets where Polymarket pushes book updates less often than five minutes, a fill can revert to displayed midpoint. A ±15% sanity guard prevents this from drifting too far. Hot markets always fill at real ask/bid.
Strategies that need the actual strike price for momentum or mean-reversion logic should source it from Polymarket Gamma directly until the column is backfilled. Tracked separately in DevEx.
Tooling for serious research workflows: backtesting, per-key isolation, an async client, and a strategy harness — in that order.
Full roadmap →Replay resolved markets day-by-day with the same authentication and order surface as live paper trading. Validate before going live.
Each API key gets its own `api_balance` pool — clean separation between research keys, live-paper keys, and CI keys. Issue #840.
Async client variant (`polysim_sdk.aio.PolySimClient`) and a WebSocket helper covering `/v1/ws/prices` and `/v1/ws/executions`. Pagination iterators next.
Run the strategy pack against historical Loki dumps and diff realised fills against the upstream `clob/book/{token_id}` REST data. Continuous DevEx.
Closed beta · request access
API access during the closed beta is gated by a Pro subscription. Upgrade to Pro to unlock the cohort, then tell us what you’re building on the waitlist below — we widen the cohort in batches and reach out again when public beta opens.
Pro subscription required · cohort widens in batches · public beta to follow.
Fair use · paper trading
PolySimulator is a paper-trading simulator. No real capital is at risk through the API. Nothing here is investment advice. The platform is a research and engineering tool — not a brokerage and not a betting venue. Use within the terms of service and applicable local law.
v1 · in closed beta · public beta to follow