API Keys

API keys are the primary authentication mechanism for the PolySimulator API. Each key is tied to a user account, has configurable permissions, and can be revoked instantly.

Open beta. Anyone can mint a key. Free keys issued on or after 2026-09-05 can trade (["read", "trade"], against a

100 non-renewable API wallet, capped at 100 order placements per UTC day per account). **Free keys issued before 2026-09-05 are read-only** (`["read"]`) — `trade` is stripped on every request even if the stored key carries it; create a new key to get a trade-capable one. Paid Pro / Pro+ keys trade against a

10,000 / $25,000 API wallet with no daily cap. See Authentication → Open Beta for the default path and residual CLOSED_BETA / ACCESS_RESTRICTED codes.

Create a Key

curl -X POST https://api.polysimulator.com/v1/keys \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-trading-bot",
    "permissions": ["read", "trade"],
    "tier": "pro"
  }'

import requests, os

resp = requests.post(
    f"{os.environ['POLYSIM_BASE_URL']}/v1/keys",
    headers={"X-API-Key": os.environ["POLYSIM_API_KEY"]},
    json={
        "name": "my-trading-bot",
        "permissions": ["read", "trade"],
        "tier": "pro",
    },
)
resp.raise_for_status()
key_data = resp.json()
print(f"Save this key: {key_data['raw_key']}")

The default permission set is ["read", "trade"] at every self-serve tier, free included (free since 2026-09-05). Omit permissions to take it. What still returns 403 TIER_REQUIRES_UPGRADE: asking for a paid tier (pro / pro_plus / enterprise) you are not subscribed to, asking for admin (never self-issued), or asking for trade while your account holds an expired paid grant (such keys stay read-only).

Response (201 Created):

{
  "id": 1,
  "raw_key": "ps_live_kJ9mNx2pQrStUvWxYz01Ab3CdEfGhI4j...",
  "key_prefix": "ps_live_kJ9mNx2p",
  "name": "my-trading-bot",
  "rate_limit_tier": "pro",
  "permissions": ["read", "trade"],
  "created_at": "2026-02-06T12:00:00Z"
}

The raw_key field is shown exactly once. Store it securely — it cannot be retrieved again. Only the SHA-256 hash is stored in the database.

Field	Description
`id`	Numeric key ID (used for revocation)
`raw_key`	Full API key — save this immediately
`key_prefix`	First 16 chars (used for identification in listings)
`name`	Your label for this key
`rate_limit_tier`	`free`, `pro`, `pro_plus`, or `enterprise` (see `GET /v1/keys/tiers`)
`permissions`	Array of granted permissions
`created_at`	ISO 8601 timestamp

List Keys

Returns all keys for your account. Only prefixes are shown — never the full key.

curl -H "X-API-Key: $API_KEY" https://api.polysimulator.com/v1/keys

[
  {
    "id": 1,
    "key_prefix": "ps_live_kJ9mNx2p",
    "name": "my-trading-bot",
    "permissions": ["read", "trade"],
    "rate_limit_tier": "pro",
    "is_active": true,
    "created_at": "2026-02-06T12:00:00Z",
    "expires_at": null
  }
]

Revoke a Key

Permanently deactivates a key. This action cannot be undone.

curl -X DELETE -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/keys/1

{
  "message": "Key revoked successfully"
}

Key Limits

Constraint	Value
Max keys per user	5
Key format	`ps_live_<64 hex chars>`
Storage	SHA-256 hash only
Expiration	Not set at creation — `expires_at` is server-managed (populated on a rotated key’s old half during its 24h overlap, and on beta keys as their cutoff). Use `POST /v1/keys/{id}/rotate` for short-lived keys.

Error Handling

Status	Endpoint	Meaning
`201`	`POST /v1/keys`	Key created — save `raw_key` immediately
`400`	`POST /v1/keys`	Max 5 keys reached, or unknown tier (`X-Polysim-Code: VALIDATION_FAILED`)
`400`	`POST /v1/keys/bootstrap`	You already have key(s) — use `POST /v1/keys` with `X-API-Key`
`401`	Any	Invalid, expired, or deactivated API key
`401`	`POST /v1/keys/bootstrap`	Invalid or expired Supabase JWT
`403`	`POST /v1/keys`, `POST /v1/keys/bootstrap`	`TIER_REQUIRES_UPGRADE` if a free caller asked for a paid `tier` it is not subscribed to, for `admin`, or for `trade` while holding an expired paid grant. Plain free + `trade` is not refused (keys issued on or after 2026-09-05 may trade). Residual `CLOSED_BETA` / `API_PRO_COMING_SOON` only on an emergency close. Branch on `X-Polysim-Code`.

# Robust key creation with error handling
resp = requests.post(
    f"{BASE_URL}/v1/keys",
    headers={"X-API-Key": API_KEY},
    json={"name": "my-bot", "permissions": ["read", "trade"]},
)

if resp.status_code == 201:
    key_data = resp.json()
    print(f"Save this key NOW: {key_data['raw_key']}")
elif resp.status_code == 400:
    err = resp.json()
    print(f"Cannot create key: {err.get('message', err.get('error'))}")
elif resp.status_code == 401:
    print("API key is invalid or expired — re-authenticate")
elif resp.status_code == 403:
    # Branch on the stable machine code in the `X-Polysim-Code` header
    # (the body's `error` is the human message).
    code = resp.headers.get("X-Polysim-Code")
    if code == "TIER_REQUIRES_UPGRADE":
        # A paid tier you are not subscribed to, "admin", or "trade" on an
        # expired paid grant. Plain free + "trade" is allowed (since 2026-09-05).
        print("Requested tier or permission needs an upgrade — see /pricing")
    elif code == "INSUFFICIENT_PERMISSION":
        print("Key lacks the required permission for this endpoint")
    elif code == "CLOSED_BETA":
        # Residual emergency close only. Default open beta does not return this.
        print("Issuance temporarily closed — retry later or contact support")
    else:
        print(f"403 [{code}]: {resp.json().get('error')}")
else:
    print(f"Unexpected error: {resp.status_code}")

Next Steps

Rate Limits — Understand your tier’s request budget
Authentication — Security model deep dive

Getting Started

Core Concepts

Trading Guide

Market Data

Simulation

Account & Portfolio

WebSocket Feeds

Bot Development

Going Live

API Keys

API Keys

Create a Key

List Keys

Revoke a Key

Key Limits

Error Handling

Next Steps

​API Keys

​Create a Key

​List Keys

​Revoke a Key

​Key Limits

​Error Handling

​Next Steps

API Keys

Create a Key

List Keys

Revoke a Key

Key Limits

Error Handling

Next Steps