Skip to main content

​
WebSocket Feeds

The PolySimulator API provides two WebSocket feeds for real-time data:
FeedEndpointDescription
Price FeedWS /v1/ws/pricesReal-time price updates for subscribed markets
Execution FeedWS /v1/ws/executionsLimit order fill notifications

​
Authentication

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

Mint a WebSocket Token

TOKEN=$(curl -s -X POST \
  -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/keys/ws-token \
  | jq -r '.token')
Response:
{"token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 60}
2

Connect Immediately

wscat -c "wss://api.polysimulator.com/v1/ws/prices?token=$TOKEN"
The token expires in 60 seconds. Connect immediately after minting.

​
Protocol

All messages are JSON. The protocol supports these client actions:
ActionDescription
subscribeSubscribe to price updates for markets
unsubscribeStop receiving updates for markets
pingHeartbeat check

​
Ping/Pong

// Client sends:
{"action": "ping"}

// Server responds:
{"type": "pong", "ts": 1705312200000}

​
Connection Limits

TierMax WS ConnectionsMax Subscriptions/Connection
free250 markets
pro1050 markets
enterprise5050 markets

​
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

WS Close CodeMeaning
4001Invalid or expired JWT token
4002Maximum WebSocket connections exceeded
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