General Information

The Predict WebSocket API streams live market data and account activity over a single persistent connection.

Connection

Connect to wss://ws.predict.fun/ws over TLS (port 443). Connections are served only on the /ws path. A request to any other path, or a non-Upgrade request, is rejected before the connection opens.

Authentication

Connections are authenticated with an API key, supplied at connection time (the handshake), not per message. Pass it either way:

x-api-key: <key> request header (preferred).

?apiKey=<key> alternatively use a query parameter.

Each key carries its own rate limits, and an invalid key rejects the handshake with HTTP 401.

Wallet events (predictWalletEvents) are user-scoped and additionally require a valid wallet JWT in the topic string.

Handshake rejections are returned as HTTP status codes (for example 401 for an invalid key, 503 when the service is temporarily unavailable). Errors that occur after the connection is open are delivered as JSON response messages (see Response Format).

Data format and timing

All client and server messages are JSON text frames.

Field names and values are case-sensitive.

Heartbeat and event timestamps are epoch milliseconds (UTC).

Messages are delivered in the order events occur.

Subscriptions

Subscribe and unsubscribe at any time after connecting; one topic per request.

For most market-data topics, the latest known value is delivered immediately on subscribe as a snapshot, followed by live updates.

Connection liveness

The server sends a heartbeat every 15 seconds that the client must echo back; a missed heartbeat closes the connection. See Heartbeats. Clients should reconnect with backoff and re-subscribe to their topics on reconnect.

Connection#

Authentication#

Data format and timing#

Subscriptions#

Connection liveness#

Connection

Authentication

Data format and timing

Subscriptions

Connection liveness