Quick Start

Get an API Key

Sign up at polysimulator.com/signin.
Open polysimulator.com/api-keys.
Click Create your first API key, give it a name, and copy the ps_live_… value shown once.

Closed beta (ongoing). API key issuance is cohort-gated, so POST /v1/keys/bootstrap and POST /v1/keys return a 403 for callers who aren’t yet admitted — CLOSED_BETA for free / waitlisted accounts, or API_PRO_COMING_SOON for paying Pro / Pro+ accounts without a cohort grant:

HTTP/1.1 403 Forbidden
X-Polysim-Code: CLOSED_BETA
Content-Type: application/json

{"error": "API access is in closed beta. New keys are issued to approved cohorts only. Apply via the waitlist; we'll email you when a cohort opens."}

Branch on the X-Polysim-Code response header (the body’s error is the human message). While the beta is closed, every non-admitted caller — including paying Pro / Pro+ — gets CLOSED_BETA; the API_PRO_COMING_SOON variant only appears once self-serve issuance is enabled. Apply via the waitlist at polysimulator.com/api-trading — we’ll email you when a cohort opens.

The full key is shown only once. Save it to your password manager or a secret store immediately — only the SHA-256 hash is retained server-side, so we can’t show it again later.

The dashboard handles the one-time bootstrap with your signed-in Supabase session — you never see or paste a JWT. From here on every API call uses X-API-Key: ps_live_....

Headless / CI: bootstrap from a script (advanced)

If you can’t open a browser (CI runner, containerised dev env) and you have a Supabase access token in hand, the POST /v1/keys/bootstrap endpoint creates your first key directly:

# SUPABASE_JWT comes from a programmatic Supabase sign-in.
# Most users skip this step entirely — the /api-keys dashboard
# is the recommended path.
curl -X POST https://api.polysimulator.com/v1/keys/bootstrap \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-bot"}'

Response (201 Created):

{
  "id": 1,
  "raw_key": "ps_live_kJ9mNx2pQrStUvWxYz01Ab3CdEfGhI4j...",
  "key_prefix": "ps_live_kJ9mNx2p",
  "name": "my-first-bot",
  "rate_limit_tier": "free",
  "permissions": ["read"],
  "created_at": "2026-03-04T12:00:00Z"
}

A free-tier key is read-only (["read"]); trading needs a paid tier. See API Keys.

Status	Meaning
`201`	Key created — save `raw_key`
`400`	You already have key(s) — use `POST /v1/keys` with `X-API-Key` instead
`401`	Invalid or expired Supabase JWT
`403`	Key issuance is closed-beta gated — branch on the `X-Polysim-Code` header. See Authentication → Closed Beta.
`429`	Bootstrap rate limit hit — wait and retry

Authorization: Bearer is accepted on the dashboard surface (POST /v1/keys/bootstrap, GET/POST/DELETE /v1/keys, /v1/keys/tiers, /v1/keys/ws-token, GET /v1/me, /v1/account/me/entitlements, /v1/me/wallets/*). All trading, market-data, websocket, and account-trading reads (/v1/account/{balance,positions,portfolio,history,equity}) require X-API-Key — Bearer is rejected on the trade surface. See the Authentication page for the full scope table.

Set Your Environment

export POLYSIM_API_KEY="ps_live_abc123..."
export POLYSIM_BASE_URL="https://api.polysimulator.com"

Check Connectivity

curl -H "X-API-Key: $POLYSIM_API_KEY" \
     $POLYSIM_BASE_URL/v1/health

Expected response:

{"status": "ok", "timestamp": "2026-03-02T12:00:00Z", "version": "1.0.0"}

Fetch Hot Markets

curl -H "X-API-Key: $POLYSIM_API_KEY" \
     "$POLYSIM_BASE_URL/v1/markets?limit=5"

This returns actively traded markets with live prices from Polymarket.

Place Your First Trade

The fastest path is the Python SDK — it picks a live market and places a trade in a few lines. This snippet is complete and runnable as-is (it resolves a real market for you — no IDs to fill in):

Python SDK

# pip install polysimulator
from polysim_sdk import PolySimClient

with PolySimClient() as client:                 # reads POLYSIM_API_KEY from env
    market = client.list_markets(limit=1)[0]   # an actively-traded market
    fill = client.place_order(
        market_id=market["condition_id"],
        side="BUY",
        outcome="Yes",
        quantity=10,
        order_type="market",
        price="0.99",            # worst-price cap; "0.99" on a YES = accept any fill
    )
    print(f"filled {fill['status']} @ {fill.get('price')} — order {fill['order_id']}")

A terminal: pip install polysimulator, then python first_trade.py prints 'filled FILLED @ 0.23 — order 102973'. — Install, run, filled — your first trade in seconds.

Market orders require price as a worst-price limit — Polymarket-faithful slippage protection. A BUY won’t fill above it; a SELL won’t fill below it. "0.99" on a YES means “accept any fill” (great for your first trade); for tighter control use the current best ask × 1.05.

Prefer raw HTTP? Resolve a live market_id from the markets endpoint first, then POST — these are runnable too:

# 1. grab a live market_id (jq)
MARKET_ID=$(curl -s -H "X-API-Key: $POLYSIM_API_KEY" \
  "$POLYSIM_BASE_URL/v1/markets?limit=1" | jq -r '.[0].condition_id')

# 2. place the trade
curl -X POST $POLYSIM_BASE_URL/v1/orders \
  -H "X-API-Key: $POLYSIM_API_KEY" -H "Content-Type: application/json" \
  -d "{\"market_id\":\"$MARKET_ID\",\"side\":\"BUY\",\"outcome\":\"Yes\",\"quantity\":\"10\",\"order_type\":\"market\",\"price\":\"0.99\"}"

import requests, os

base, key = os.environ["POLYSIM_BASE_URL"], os.environ["POLYSIM_API_KEY"]
h = {"X-API-Key": key, "Content-Type": "application/json"}

# resolve a live market, then trade
market_id = requests.get(f"{base}/v1/markets?limit=1", headers=h).json()[0]["condition_id"]
resp = requests.post(f"{base}/v1/orders", headers=h, json={
    "market_id": market_id, "side": "BUY", "outcome": "Yes",
    "quantity": "10", "order_type": "market",
    "price": "0.99",  # worst-price limit (slippage cap)
})
print(resp.json())

const base = process.env.POLYSIM_BASE_URL, key = process.env.POLYSIM_API_KEY;
const h = { "X-API-Key": key, "Content-Type": "application/json" };

const markets = await (await fetch(`${base}/v1/markets?limit=1`, { headers: h })).json();
const resp = await fetch(`${base}/v1/orders`, {
  method: "POST", headers: h,
  body: JSON.stringify({
    market_id: markets[0].condition_id, side: "BUY", outcome: "Yes",
    quantity: "10", order_type: "market",
    price: "0.99",  // worst-price limit (slippage cap)
  }),
});
console.log(await resp.json());

Response:

{
  "order_id": 42,
  "status": "FILLED",
  "order_type": "market",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0.65",
  "quantity": "10",
  "notional": "6.50",
  "fee": "0.09",
  "slippage_bps": 15,
  "account_balance": "9993.41"
}

account_balance is your API wallet balance after the fill, not the dashboard MAIN wallet. API keys start at

10,000 (Pro) or

25,000 (Pro+); Free-tier keys are read-only with no API wallet. Here a

6.50 fill plus the

0.09 taker fee (PM-V2 per-category schedule — see Trading Fees) against the

10,000 Pro wallet leaves

9,993.41.

Check Your Portfolio

curl -H "X-API-Key: $POLYSIM_API_KEY" \
     $POLYSIM_BASE_URL/v1/account/portfolio

All numeric values are strings ("10", not 10). This prevents floating-point precision loss — critical for financial applications. See String Numerics for details.

What’s Next?

Authentication deep dive — Key management, security, permissions
Rate Limits — Understand your tier’s request budget
Build a trading bot — Complete Python example

Getting Started

Core Concepts

Trading Guide

Market Data

Account & Portfolio

WebSocket Feeds

Bot Development

Going Live

Quick Start

Quick Start

What’s Next?

​Quick Start

​What’s Next?

Quick Start

What’s Next?