> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polysimulator.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick Start
> Get your API key and place your first trade in under 2 minutes.
# Quick Start
1. Sign up at [polysimulator.com/signin](https://polysimulator.com/signin).
2. Open [polysimulator.com/api-keys](https://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 theme={null}
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](https://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:
```bash theme={null}
# 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):**
```json theme={null}
{
"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](/concepts/api-keys#create-a-key).
| 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](/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](/authentication) page for the full
scope table.
```bash theme={null}
export POLYSIM_API_KEY="ps_live_abc123..."
export POLYSIM_BASE_URL="https://api.polysimulator.com"
```
```bash theme={null}
curl -H "X-API-Key: $POLYSIM_API_KEY" \
$POLYSIM_BASE_URL/v1/health
```
Expected response:
```json theme={null}
{"status": "ok", "timestamp": "2026-03-02T12:00:00Z", "version": "1.0.0"}
```
```bash theme={null}
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.
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 Python SDK theme={null}
# 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']}")
```
**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:
```bash cURL theme={null}
# 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\"}"
```
```python Python (requests) theme={null}
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())
```
```javascript JavaScript theme={null}
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:
```json theme={null}
{
"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](/trading/fees)) against the $10,000
Pro wallet leaves $9,993.41.
```bash theme={null}
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](/concepts/string-numerics) for details.
***
## What's Next?
* [Authentication deep dive](/authentication) — Key management, security, permissions
* [Rate Limits](/concepts/rate-limits) — Understand your tier's request budget
* [Build a trading bot](/bots/example-trading-bot) — Complete Python example