Unrealized PnL

This page covers subscribing to Unrealized PnL leaderboard invalidation hints with subscribe_unrealized_pnl, and the unrealizedPnlProjectionChanged payload that subscription delivers.

Subscribing to unrealized PnL updates

Subscribe to invalidation hints for the live Unrealized PnL leaderboards by emitting subscribe_unrealized_pnl. No authentication required. Two scopes are available: one leaderboard per open market, and a global biggest-open-positions list.

This event carries only a hint, not the leaderboard payload. When it arrives, refetch the corresponding REST route — GET /leaderboard/pnl/unrealized/markets/{marketId} or GET /leaderboard/pnl/unrealized/biggest-positions — which remains the serving contract.

// Follow the leaderboard for one market
socket.emit('subscribe_unrealized_pnl', { schemaVersion: 1, scope: 'MARKET', marketId: 7348 });

// Follow the global biggest open positions
socket.emit('subscribe_unrealized_pnl', { schemaVersion: 1, scope: 'BIGGEST_POSITIONS' });

socket.on('unrealizedPnlProjectionChanged', (msg) => {
  // Refetch the matching REST route for `msg.scope` (and `msg.marketId` when scope === 'MARKET').
});

To unsubscribe, emit unsubscribe_unrealized_pnl with the same payload shape.

At most 50 MARKET scopes per connection. Additional subscribe_unrealized_pnl calls with new marketIds beyond the limit are rejected with an error frame carrying code: "UNREALIZED_PNL_SCOPE_LIMIT". The BIGGEST_POSITIONS scope does not count against the market limit.

state on the hint tracks the projection. state: "READY" means the leaderboard you refetch will be current; BUILDING, STALE, or DEGRADED mean the REST route may return an empty or stale snapshot. Retry shortly.

Event payload

`unrealizedPnlProjectionChanged`

Invalidation hint delivered to subscribe_unrealized_pnl subscribers when the underlying projection for their scope changes. It does not carry the leaderboard rows. Refetch the matching REST route to get the updated snapshot. Market scope:

{
  "schemaVersion": 1,
  "scope": "MARKET",
  "marketId": 7348,
  "state": "READY",
  "projectionVersion": "42",
  "scopeVersion": "17",
  "presentationVersion": "3",
  "asOf": "2026-04-20T10:15:40.000Z"
}

Biggest positions scope:

{
  "schemaVersion": 1,
  "scope": "BIGGEST_POSITIONS",
  "state": "READY",
  "projectionVersion": "42",
  "scopeVersion": "17",
  "presentationVersion": "3",
  "asOf": "2026-04-20T10:15:40.000Z"
}

Field	Type	Description
`schemaVersion`	`1`	Message schema version
`scope`	`'MARKET' \| 'BIGGEST_POSITIONS'`	Leaderboard scope this hint applies to
`marketId`	`number`	Market id — present on `MARKET` scope only
`state`	`'READY' \| 'STALE' \| 'BUILDING' \| 'DEGRADED'`	Readiness of the projection you’ll read on refetch
`projectionVersion`	`string`	Monotonic projection version
`scopeVersion`	`string`	Monotonic version for this scope’s ranking
`presentationVersion`	`string`	Monotonic version of the presentation layer
`asOf`	`string`	ISO-8601 timestamp of the new snapshot

WebSocket overview: connection details, handshake authentication, and the full event reference

Getting Started

Quick Start

TypeScript SDK

Python SDK

Go SDK

Rust SDK

WebSocket

Subscribing to unrealized PnL updates

Event payload

`unrealizedPnlProjectionChanged`

​Subscribing to unrealized PnL updates

​Event payload

​unrealizedPnlProjectionChanged

​Related

Subscribing to unrealized PnL updates

Event payload

`unrealizedPnlProjectionChanged`

Related