WebSockets#
This document provides a comprehensive guide to the WebSocket API exposed by predict.fun.Connection Details#
Protocol: wss (or ws for local development)
Endpoint: Base URL of the service.
Heartbeat Interval: 15 seconds.
Message Protocol#
The API uses a JSON-based protocol with specific message structures for client requests and server responses.Base Message Structure (Client to Server)#
All client requests must follow this format:{
"method": "subscribe" | "unsubscribe" | "heartbeat",
"requestId": number,
"params": string[],
"data": any
}
| Field | Type | Required | Description |
|---|
method | string | Yes | The action to perform: subscribe, unsubscribe, or heartbeat. |
requestId | number | Conditional | A unique, non-negative integer to track request responses. Required for subscribe and unsubscribe. |
params | string[] | Conditional | An array containing the topic string(s). Required for subscribe and unsubscribe. |
data | any | Conditional | Payload for the method. Required for heartbeat (must be the timestamp received from server). |
Base Message Structure (Server to Client)#
The server sends two types of messages: Responses (R) to client requests and Messages (M) which are push notifications (subscriptions).Request Response (Type R)#
{
"type": "R",
"requestId": number,
"success": boolean,
"data": any,
"error": {
"code": string,
"message": string
}
}
| Field | Type | Description |
|---|
type | string | Always "R" for request responses. |
requestId | number | Matches the requestId from the client's request. |
success | boolean | Indicates if the request was successful. |
data | any | Response data (usually null for subscriptions). |
error | object | Present only if success is false. |
Push Message (Type M)#
{
"type": "M",
"topic": string,
"data": any
}
| Field | Type | Description |
|---|
type | string | Always "M" for push messages. |
topic | string | The topic the message belongs to (e.g., predictOrderbook/123). |
data | any | The payload for the specific topic. |
Heartbeat Mechanism#
To maintain an active connection, the server implements a heartbeat mechanism.1.
Server Probe: Every 15 seconds, the server sends:{ "type": "M", "topic": "heartbeat", "data": 1736696400000 }
2.
Client Response: The client must respond within the next 15 seconds with:{ "method": "heartbeat", "data": 1736696400000 }
data value must match the timestamp received from the server.
Subscription Topics#
Topics are formatted as topicName/parameter.1. Predict Orderbook#
Live updates for a specific market's orderbook.Topic: predictOrderbook/{marketId}
Payload: Orderbook data (JSON).
2. Polymarket Chance#
Percentage chance updates for a market from Polymarket.Topic: polymarketChance/{marketId}
{
"percentage": number,
"timestamp": number
}
3. Kalshi Chance#
Percentage chance updates for a market from Kalshi.Topic: kalshiChance/{marketId}
{
"percentage": number,
"timestamp": number
}
4. Asset Price Update#
Real-time price updates for a specific price feed.Topic: assetPriceUpdate/{priceFeedId}
{
"price": number,
"publishTime": number,
"timestamp": number
}
5. Predict Wallet Events (Authenticated)#
Live events specific to a user's wallet. Requires a valid JWT.Topic: predictWalletEvents/{jwt}
Payload: One of several wallet event types.
orderAccepted: Order successfully placed in orderbook.
orderNotAccepted: Order rejected (e.g., duplicate).
orderExpired: Order reached its end time.
orderCancelled: User cancelled the order.
orderTransactionSubmitted: Order matched, transaction sent to blockchain.
orderTransactionSuccess: On-chain transaction succeeded.
orderTransactionFailed: On-chain transaction failed.
Error Codes#
| Code | Description |
|---|
invalid_json | The message sent by the client is not valid JSON. |
invalid_topic | The requested topic is malformed or unknown. |
invalid_credentials | (Wallet events) The provided JWT is invalid or expired. |
internal_server_error | An unexpected error occurred on the server. |
unsupported_contract | The requested market/contract is not supported. |
Modified at 2026-01-12 15:24:00
