WS /v1/ws/executions?token=<jwt>

# Mint a WS token
TOKEN=$(curl -s -X POST -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/keys/ws-token | jq -r '.token')

# Connect
wscat -c "wss://api.polysimulator.com/v1/ws/executions?token=$TOKEN"

{
  "event_id": "fill_42",
  "type": "fill",
  "order_id": 42,
  "client_order_id": "limit-001",
  "market_id": "0x1a2b3c...",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0.65",
  "quantity": "10.0",
  "filled_at": "2026-02-06T12:00:45Z"
}

import asyncio
import json
import random
import time

import requests
import websockets

API_KEY = "ps_live_..."
BASE = "https://api.polysimulator.com/v1"
headers = {"X-API-Key": API_KEY}

# 1. Place a limit order
order = requests.post(f"{BASE}/orders", headers=headers, json={
    "market_id": "0x1a2b3c...",
    "side": "BUY",
    "outcome": "Yes",
    "quantity": "10",
    "order_type": "limit",
    "price": "0.60",
    "time_in_force": "GTC",
    "client_order_id": "limit-001",
}).json()

print(f"Limit order placed: {order['status']}")

# 2. Listen for fills, reconnecting with replay and reconciling through REST
my_open = {order["order_id"]}   # resting orders this bot is waiting on
seen = set()                    # event_ids already handled (delivery is at-least-once)
last_order_id = None            # replay watermark: the newest fill order_id processed
RECONCILE_EVERY_S = 45          # REST reconciliation cadence while connected

def call(method, path, **params):
    """One REST call that waits out a 429 (Retry-After + jitter) and raises on other errors."""
    while True:
        resp = requests.request(method, f"{BASE}{path}", headers=headers, params=params, timeout=10)
        if resp.status_code == 429:
            time.sleep(float(resp.headers.get("Retry-After", "1")) + random.uniform(0, 0.5))
            continue   # retry the SAME request, don't restart the scan
        resp.raise_for_status()
        return resp.json()

def reconcile():
    """REST is authoritative: page through PENDING orders, then look up any of
    ours that left the list (filled, cancelled or expired)."""
    pending, cursor = set(), None
    while True:
        page = call("GET", "/orders", status="PENDING", limit=50, **({"cursor": cursor} if cursor else {}))
        pending |= {o["order_id"] for o in page["orders"]}
        if not page.get("has_more"):
            break
        cursor = page["next_cursor"]
        time.sleep(0.6)   # stay under free's 2 requests/second
    for oid in list(my_open - pending):
        final = call("GET", f"/orders/{oid}", source="pending")   # ids live per table (`source`)
        print(f"Order {oid} is now {final['status']}")
        my_open.discard(oid)

def handle_frame(raw):
    global last_order_id
    msg = json.loads(raw)
    # Fill frames are FLAT (no `data` wrapper) and use type == "fill".
    if msg.get("type") != "fill" or msg["event_id"] in seen:
        return
    seen.add(msg["event_id"])
    last_order_id = max(last_order_id or 0, int(msg["order_id"]))
    print(f"Filled: {msg['side']} {msg['quantity']}x {msg['outcome']} @ {msg['price']}"
          f" (client_order_id={msg.get('client_order_id')})")

async def drain_replay(ws, quiet_s=2.0, max_s=5.0):
    """Handle the frames already waiting (replayed fills arrive first after connect).
    Bounded by `max_s` so steady live traffic cannot postpone reconciliation."""
    deadline = time.monotonic() + max_s
    while time.monotonic() < deadline:
        try:
            handle_frame(await asyncio.wait_for(ws.recv(), timeout=min(quiet_s, deadline - time.monotonic())))
        except asyncio.TimeoutError:
            return

async def listen_fills():
    delay = 1.0
    while my_open:
        try:
            token = call("POST", "/keys/ws-token")["token"]
            url = f"wss://api.polysimulator.com/v1/ws/executions?token={token}"
            if last_order_id is not None:
                url += f"&watermark={last_order_id}"   # replay up to 50 missed fills
            async with websockets.connect(url) as ws:
                await drain_replay(ws)                # handle replayed fills first
                await asyncio.to_thread(reconcile)    # first connect, and any gap the replay cannot cover
                delay, next_reconcile = 1.0, time.monotonic() + RECONCILE_EVERY_S
                while my_open:
                    try:
                        raw = await asyncio.wait_for(ws.recv(), timeout=max(1.0, next_reconcile - time.monotonic()))
                    except asyncio.TimeoutError:
                        raw = None
                    if time.monotonic() >= next_reconcile:
                        await asyncio.to_thread(reconcile)   # cancels / expiries never arrive as frames
                        next_reconcile = time.monotonic() + RECONCILE_EVERY_S
                    if raw is not None:
                        handle_frame(raw)
                await drain_replay(ws)   # fills queued while the last reconcile ran
        except (websockets.ConnectionClosed, websockets.InvalidHandshake,
                OSError, asyncio.TimeoutError, requests.RequestException):
            pass   # network blip, deploy, expired token: back off and reconnect
        if my_open:
            await asyncio.sleep(delay)
            delay = min(delay * 2, 30.0)

asyncio.run(listen_fills())