Request Format

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).

Heartbeat Mechanism

To maintain an active connection, the server implements a heartbeat mechanism.

Server Probe: Every 15 seconds, the server sends:

{ "type": "M", "topic": "heartbeat", "data": 1736696400000 }

Client Response: The client must respond within the next 15 seconds with:

{ "method": "heartbeat", "data": 1736696400000 }

Note: The data value must match the timestamp received from the server.

Failure to respond to the heartbeat will result in the server terminating the connection.

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}

Payload:

{
  "percentage": number,
  "timestamp": number
}

3. Kalshi Chance

Percentage chance updates for a market from Kalshi.

Topic: kalshiChance/{marketId}

Payload:

{
  "percentage": number,
  "timestamp": number
}

4. Asset Price Update

Real-time price updates for a specific price feed.

Topic: assetPriceUpdate/{priceFeedId}

Payload:

{
  "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.

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.

Request Format

Request Format#

Message Protocol#

Base Message Structure (Client to Server)#

Heartbeat Mechanism#

Subscription Topics#

1. Predict Orderbook#

2. Polymarket Chance#

3. Kalshi Chance#

4. Asset Price Update#

5. Predict Wallet Events (Authenticated)#

Error Codes#

Request Format

Message Protocol

Base Message Structure (Client to Server)

Heartbeat Mechanism

Subscription Topics

1. Predict Orderbook

2. Polymarket Chance

3. Kalshi Chance

4. Asset Price Update

5. Predict Wallet Events (Authenticated)

Error Codes