General WebSocket API Information

Endpoint Details

Base Endpoint: wss://ws.predict.fun/ws

Protocol: Secure WebSocket (wss) over standard port 443.

Path: All connections should be directed to the /ws path.

Api Key

API Key: API keys can be provided via the x-api-key HTTP header or apiKey query parameter (e.g., wss://ws.predict.fun/ws?apiKey=your-key). API keys will be required in the near future.

Connection Management

Responses: All responses and pushed messages are in JSON format.

Timestamps: All timestamps in the JSON responses are in milliseconds (UTC).

Case Sensitivity: All field names, methods, and values (unless specified otherwise) are case-sensitive.

Connection Stability: While there is no hard limit on connection duration, clients are encouraged to implement robust reconnection logic with exponential backoff to handle network interruptions.

Heartbeat & Connectivity

Server Heartbeat: The WebSocket server sends a heartbeat message every 15 seconds.

Client Response: Upon receiving a heartbeat message (type: "M", topic: "heartbeat"), the client must respond with a heartbeat message (method: "heartbeat") containing the same timestamp provided by the server.

Disconnection: If the server does not receive a valid heartbeat response before the next heartbeat interval, the connection will be terminated to ensure resources are freed.

Authentication

Public Streams: Market data, orderbooks, and price updates do not require authentication.

Private Streams: Streams specific to a user (e.g., predictWalletEvents) require a valid JWT (JSON Web Token) passed as part of the topic string.

Credentials: We support authentication via signed JWTs. Ensure your token is valid and not expired when initiating a subscription.

Message Ordering & Handling

Chronological Order: Data is pushed in chronological order as events occur within our matching engine and data feeds.

Request IDs: Every subscribe and unsubscribe request must include a unique requestId (non-negative integer). This ID is returned in the server's response (type: "R") to help the client track the success of specific operations.

UTF-8 Encoding: All string data is encoded in UTF-8. This includes market questions and symbol names.

Rate Limits & Safety

Subscription Limits: While there is no strict limit on the number of topics per connection, it is recommended to only subscribe to necessary channels to minimize latency and bandwidth. We are likely to enforce limits in the future.

Request Timeout: Subscription requests generally have a processing timeout of 10 seconds. If no response is received, the client should assume the state is unknown and may retry or query current status.

Payload Safety: Avoid including sensitive characters or SQL keywords in your requests to prevent accidental triggering of security filters.

General Information

General WebSocket API Information#

Endpoint Details#

Api Key#

Connection Management#

Heartbeat & Connectivity#

Authentication#

Message Ordering & Handling#

Rate Limits & Safety#