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.
Fill events
One event per on-chain fill. Values arrive as strings, as the stream carries them:
{
"type": "fill",
"ts": 1792500001234,
"msg_id": "1792500001200-0",
"tx_hash": "0xab12…",
"log_index": "41",
"block_number": "95891234",
"taker": "0x1234…",
"usdc_size": "250.5",
"price": "0.72",
"token_id": "7134…",
"taker_side": "buy",
"exchange_version": "v2",
"exchange_kind": "binary",
"condition_id": "0x5f65…"
}| Field | Meaning |
|---|---|
taker | The wallet whose order this fill belongs to |
taker_side | buy = paid USDC for token_id, sell = received USDC |
usdc_size, price | Notional in USDC and the fill's price per share |
tx_hash, log_index | The fill's on-chain log |
block_number | The fill's block. Sort by (block_number, log_index) for chain order: events can reach you out of order, and msg_id is the order they were published in, not the chain's |
condition_id | Present when the fill's token maps to a known market |
block_number was added on 2026-10-21. It is additive: no field was removed or renamed. Events published
before it, or replayed from that time, do not carry it — treat it as optional and fall back to log_index within
one tx_hash.