Skip to main content

WebSocket Feeds

The PolySimulator API provides two shape families of WebSocket feeds for real-time data: a polysim-native shape (compact, condition-id keyed) and a Polymarket-compatible shape that mirrors Polymarket’s CLOB WS contract field-for-field so existing py-clob-client / PM-port bots can drop in without rewriting their event handlers.

PolySim-native feeds

Polymarket-compatible feeds

The PM-compat routes:
  • Accept PM’s subscribe message — {"type": "market", "assets_ids": ["TOKEN_ID", ...]}
  • Emit PM-shape events — book / price_change / last_trade_price / best_bid_ask, plus PM-shape trade fill frames on /ws/user
  • Field names match PM verbatim (asset_id, market, hash, tick_size, timestamp, stringified prices)
  • Accept inline auth via the subscribe message — "auth": {"apiKey": "ps_live_..."} (PM’s L2 secret/passphrase fields are accepted but ignored — polysim is single-secret)
  • Also accept ?token=<jwt> for back-compat with the polysim-native auth model
See PM-compat Market Channel for the full PM-shape protocol.

Authentication

WebSocket connections require a short-lived JWT token (60 seconds), separate from your API key.
1

Mint a WebSocket Token

Response:
2

Connect Immediately

The token expires in 60 seconds. Connect immediately after minting.

Protocol

All messages are JSON. The protocol supports these client actions:

Ping/Pong


Connection Limits

The Max WS Connections column is authoritative on the wire via GET /v1/keys/tiers — the max_ws_connections field. The Max Subscriptions/Connection value is fixed at 50 per connection across all tiers (a hardcoded server cap, not tier-configurable and not returned by /v1/keys/tiers).
See also Rate Limits for the full tier matrix.

Reconnection & Token Rotation

WebSocket tokens are short-lived — they expire after 60 seconds. They are not single-use: a token may be reused for multiple connections while it is still valid. The short TTL means most reconnect flows mint a fresh one anyway, so your bot must still implement automatic reconnection with token minting near expiry.

Key Rules

  1. Mint a fresh token near expiry — a token may be reused for multiple connections while still valid, but the 60-second TTL means most reconnect flows mint a new one anyway
  2. Re-subscribe after reconnect — the server does not remember your subscriptions
  3. Exponential backoff — start at 1s, cap at 30s, reset on successful connect
  4. Handle close code 4001 immediately — no backoff needed, just mint and reconnect

Best Practices

Connect Immediately

WS tokens expire in 60 seconds. Mint and connect in the same code block.

Implement Reconnection

Use exponential backoff for reconnection. Mint a fresh token on each reconnect attempt.

Prefer WS Over Polling

WebSocket subscriptions don’t count against REST rate limits. Use them instead of polling GET /v1/markets.

Use Execution Feed

Subscribe to the execution feed for limit order fill confirmations instead of polling GET /v1/orders.

Error Handling

When you receive close code 4001, mint a fresh token and reconnect. When you receive close code 4002, close idle connections before reconnecting.

Next Steps