Skip to main content

Python SDK

The official Python client is published on PyPI as polysimulatorpip install polysimulator.

Start here: PolySimClient

New to PolySimulator? Use the native client. It’s the cleanest path — sync and async, WebSocket + SSE streaming, pagination iterators, typed exceptions — and the Quickstart places your first trade in ~5 lines. That’s the one path most developers want; jump to Install below.
Porting an existing bot? The package ships two drop-in mirrors so you don’t rewrite your strategy — use one only if you already have a bot on that library; otherwise stick with PolySimClient above.
On CLOB V1 vs V2. Polymarket has archived py-clob-client (v1) and moved production to CLOB V2, with py-clob-client-v2 as the current client. Our drop-in mirrors the v1 surface, so it is the right tool for porting an existing v1 bot — and it is not a V2 client.And V2 is not where Polymarket is pointing new projects either. py-clob-client-v2’s own package README says “We recommend Polymarket/py-sdk for new projects” — the unified SDK published on PyPI as polymarket-client. So porting to V2 CLOB would be porting to something already being sidelined.If you are starting fresh today and intend to go live on Polymarket, use polysim_polymarket — our paper-mode mirror of that unified SDK — and treat the move to Polymarket as a real port rather than a base-URL swap. Check its pinned version against polymarket-client before relying on a specific method: the mirror tracks a release, not upstream HEAD.
| Polymarket’s unified py-sdk (polymarket-client) | polysim_polymarket | Paper-mode mirror of PublicClient / SecureClient — swap the import prefix + host + auth. See the py-sdk Mirror overview + compatibility. |
Because PolySimulator is paper trading, there is no on-chain anything — no private key, no chain_id, no signing, no USDC allowances. The package depends only on httpx and websockets, and auth is a single ps_live_… key sent as X-API-Key.

polysimulator on PyPI

pip install polysimulator — the published package, with the complete README and method reference.

CLOB compatibility

The full py-clob-client → PolySimulator migration map.

Install

Targets Python 3.10+.
The install name is polysimulator; the import name stays polysim_sdk (the same way pip install pillow gives you import PIL). The older polysim-sdk package name is now a thin alias that installs polysimulator for you, so existing installs keep working unchanged.
Provide your key via the POLYSIM_API_KEY environment variable (recommended) or pass it to the constructor. Point at staging with POLYSIM_BASE_URL:

Quickstart — native polysim_sdk

Async is the same API with await:
The native client also ships WebSocket price/execution streams (polysim_sdk.ws), an SSE underlying-spot firehose (polysim_sdk.sse), Up/Down helpers (polysim_sdk.updown), and pagination iterators (polysim_sdk.pagination). The full README on PyPI documents every surface. The native client also exposes client.simulation for the dark /v1/simulation surface (fill, coverage, book, create_backtest / wait, list/get/cancel). Methods exist so typed clients can generate; the live router stays 404 until FEATURE_SIMULATION_API_ENABLED is on. See Simulation.

Migrating a py-clob-client bot

Change three things and delete the on-chain prelude — method names, argument shapes, and return shapes all stay the same:
The full per-method mapping (mirror / adapt / stub-noop), the token_id ↔ market+outcome seam, and the read-vs-write parity rules are documented in CLOB compatibility.

Rate limits & pacing

The client paces itself (a 50 ms floor between requests) and backs off on 429/5xx using Retry-After. Authoritative tier limits come live from client.tiers() — see Rate limits for the per-tier table.

Errors

Catch PolySimError to handle every SDK-raised error (PolyApiException, the drop-in alias, is the same class):