Skip to main content

​
Quick Start

1

Get an API Key

  1. Sign up at polysimulator.com/signin.
  2. Open polysimulator.com/api-keys.
  3. 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_....
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.
StatusMeaning
201Key created — save raw_key
400You already have key(s) — use POST /v1/keys with X-API-Key instead
401Invalid or expired Supabase JWT
403CLOSED_BETA — key issuance is in closed beta (the default for every non-admitted caller, including paying Pro / Pro+). The API_PRO_COMING_SOON variant appears only once self-serve issuance is enabled. Branch on the X-Polysim-Code header; apply via the waitlist (see the callout above).
429Bootstrap 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.
2

Set Your Environment

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

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"}
4

Fetch Hot Markets

curl -H "X-API-Key: $POLYSIM_API_KEY" \
     "$POLYSIM_BASE_URL/v1/markets?hot_only=true&limit=5"
This returns actively traded markets with live prices from Polymarket.
5

Place Your First Trade

Market orders require price as a worst-price limit —
Polymarket-faithful slippage protection. BUY won’t fill above
this price; SELL won’t fill below it. Use the current best
ask + a small buffer (e.g. ask × 1.05) to allow normal fills.
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)or10,000 (Pro) or 25,000 (Pro+); Free-tier keys are read-only with no API wallet. Here a 6.50fillplusthe6.50 fill plus the 0.09 taker fee (PM-V2 per-category schedule — see Trading Fees) against the 10,000Prowalletleaves10,000 Pro wallet leaves 9,993.41.
6

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?