Subscription Topics

Topics are strings of the form topicName/parameter, for example predictOrderbook/123. Subscribe to one topic per request.

Snapshots

When you subscribe to a market-data topic that caches a value, the latest value is pushed immediately as a normal type: "M" message, followed by live updates. Treat the snapshot as best-effort: it may be absent if no value has been cached yet. The change-notification and wallet-event topics do not send a snapshot.

Market data topics

`predictOrderbook/{marketId}`

Live order book for a market, as aggregated price levels. Snapshot: yes.

Payload:

{
  "version": 1,
  "marketId": 123,
  "updateTimestampMs": 1736696400000,
  "orderCount": 42,
  "asks": [[0.62, 1500.0], [0.63, 800.0]],
  "bids": [[0.61, 2000.0], [0.60, 1200.0]],
  "lastOrderSettled": {
    "id": "987654321",
    "price": "0.62",
    "kind": "LIMIT",
    "marketId": 123,
    "side": "Ask",
    "outcome": "Yes"
  },
  "settlementsPending": { "asks": [[0.62, 310.0]], "bids": [] }
}

Each entry in asks/bids is a [price, quantity] level: price is the YES price
between 0 and 1, quantity is the size in shares. asks are sorted ascending by price,
bids descending. lastOrderSettled is null until the first settlement; its kind is
the order strategy (MARKET/LIMIT). settlementsPending holds [price, value] levels
whose settlement is in flight.

`predictTradingStatus/{marketId}`

Whether a market is currently matching orders. Snapshot: yes.

Payload:

{
  "kind": "tradingStatusUpdate",
  "tsMs": 1736696400000,
  "marketId": 123,
  "tradingStatus": "OPEN"
}

tradingStatus is OPEN, MATCHING_NOT_ENABLED, CANCEL_ONLY, or CLOSED.

`predictMarketStatus/{marketId}`

Lifecycle status and outcome prices for a market. Snapshot: yes.

Payload:

{
  "kind": "marketStatusUpdate",
  "tsMs": 1736696400000,
  "marketId": 123,
  "status": "OPEN",
  "marketOutcomes": [
    { "label": "Yes", "price": "0.62", "indexSet": 1, "onChainId": "..." }
  ]
}

marketOutcomes is optional.

`predictMarketChanged/{marketId}`

Notification that a market changed, so clients can refetch or patch their cached copy.
Snapshot: no.

Payload:

{ "kind": "marketChanged", "patchKind": null, "tsMs": 1736696400000, "marketId": 123 }

patchKind is null for a generic change. When the change carries an inline patch,
patchKind names the patch type and a patch object with the changed fields is included.

`predictCategoryChanged/{categoryId}`

Notification that a category changed. Snapshot: no.

Payload:

{
  "kind": "categoryChanged",
  "patchKind": null,
  "tsMs": 1736696400000,
  "categoryId": 45,
  "slug": "politics"
}

As with market changes, patchKind names the patch type and a patch object is included
when the change carries inline data.

Account topic

`predictWalletEvents/{jwt}` (authenticated)

Live events for a user's own orders and trades. Requires a valid wallet JWT in the topic string. Snapshot: no.

A revoked, invalid, or expired JWT returns invalid_credentials.

Event payload

Every wallet event shares this base shape:

{
  "type": "orderAccepted",
  "orderId": "123456789",
  "orderHash": "0x…",
  "walletAddress": "0x…",
  "timestamp": 1736696400000,
  "details": {
    "marketId": 123,
    "outcomeIndex": 0,
    "marketQuestion": "Will X happen?",
    "outcome": "YES",
    "quoteType": "BID",
    "quantity": "100.000",
    "quantityFilled": "0.000",
    "price": "0.620",
    "value": "62.00",
    "valueFilled": "0.00",
    "strategyType": "LIMIT",
    "categorySlug": "politics"
  }
}

outcome is YES/NO; quoteType is ASK/BID; strategyType is MARKET/LIMIT.

Event types

`type`	Meaning	Extra fields
`orderAccepted`	Order placed in the book.	—
`orderNotAccepted`	Order rejected.	`reason`: `noMarketMatch`, `rejectedDuplicate`, or `rejectedPostOnly`
`orderExpired`	Order reached its end time.	—
`orderCancelled`	Order cancelled.	optional `reason`: `selfTradePrevention`
`orderTransactionSubmitted`	Order matched; settlement submitted on-chain.	`kind`: `SALE`/`PURCHASE`, `settlementId`, `fill`
`orderTransactionSuccess`	On-chain settlement succeeded.	`settlementId`, `fill`, optional `isMaker`, optional `fee`
`orderTransactionFailed`	On-chain settlement failed.	`settlementId`, `fill`

fill schema:

{ "executedPriceWei": "…", "executedSizeWei": "…", "executedValueWei": "…" }

fee schema:

{ "amountWei": "…", "type": "COLLATERAL" | "SHARES" }

Snapshots#

Market data topics#

predictOrderbook/{marketId}#

predictTradingStatus/{marketId}#

predictMarketStatus/{marketId}#

predictMarketChanged/{marketId}#

predictCategoryChanged/{categoryId}#

Account topic#

predictWalletEvents/{jwt} (authenticated)#

Event payload#

Event types#

Snapshots

Market data topics

`predictOrderbook/{marketId}`

`predictTradingStatus/{marketId}`

`predictMarketStatus/{marketId}`

`predictMarketChanged/{marketId}`

`predictCategoryChanged/{categoryId}`

Account topic

`predictWalletEvents/{jwt}` (authenticated)

Event payload

Event types