Real-time (WebSocket)
Live fills, mid-price moves, and resolutions over wss://ws.polyrank.app.
Handshake
Mint a short-lived token (requires a session — sign in at polyrank.app):
curl -s -X POST https://api.polyrank.app/v1/auth/ws-token \
-H "Cookie: __Secure-polyrank_sid=…"Returns a JWT valid for 5 minutes — it authorizes the handshake, not the connection lifetime.
Connect with the token:
wss://ws.polyrank.app/?t=<JWT>Subscribe:
{ "action": "subscribe", "topics": ["trader:0xabc…", "market:0xdef…:book"] }Topics
| Topic | Auth | Stream |
|---|---|---|
trader:{proxy} | session | Public fills for one wallet — powers the Follow feed |
market:{conditionId}:trades | public | Trade prints for a market |
market:{conditionId}:book | public | Live mid + best bid/ask (first to shed under backpressure) |
market:{conditionId}:resolved | public | Resolution events |
user:{userId}:notify | session | Your notification stream |
Limits: 100 topics per connection, of which at most 50 trader: topics.
Client best practices
Mirror what the Polyrank web app does:
- Send an app-layer ping every 10 seconds.
- When the JWT has less than 60s of validity left, mint a fresh token and reconnect silently; close the old socket before opening the new one.
- Treat
401and403as terminal — re-auth or stop; do not hot-loop reconnects. - Diff your subscription set on change (unsubscribe removed topics) instead of reconnecting.
Event shape
Events are JSON with a topic field plus the payload (fill, book update, or
resolution). Fills carry wallet, market, side, price, and notional — enough
to drive a copy-feed UI without further lookups.