WebSocket Events

Connection

URL: wss://ws.limitless.exchange Namespace: /markets Transport: WebSocket only (no polling fallback)

No client PING required. The server runs the Socket.IO heartbeat (server-initiated ping / client pong) automatically. Every official Socket.IO client (JavaScript, Python python-socketio, Go, Rust) responds to it out of the box. Do not send your own PING frames. Keep the connection open and rely on the built-in heartbeat and the auto-reconnect flow in WebSocket Quickstart.

Authenticated channels (positions, order events) require an HMAC-signed handshake. Sign a fixed canonical message — {ISO-8601 timestamp}\nGET\n/socket.io/?EIO=4&transport=websocket\n — with the base64-decoded secret and pass three headers as extraHeaders:

import { createHmac } from 'crypto';
import { io } from 'socket.io-client';

function wsAuthHeaders(tokenId: string, secret: string) {
  const timestamp = new Date().toISOString();
  const message = `${timestamp}\nGET\n/socket.io/?EIO=4&transport=websocket\n`;
  const signature = createHmac('sha256', Buffer.from(secret, 'base64'))
    .update(message)
    .digest('base64');
  return { 'lmts-api-key': tokenId, 'lmts-timestamp': timestamp, 'lmts-signature': signature };
}

const socket = io('wss://ws.limitless.exchange/markets', {
  transports: ['websocket'],
  extraHeaders: wsAuthHeaders(TOKEN_ID, SECRET),
});

See Authentication for how to generate TOKEN_ID and SECRET. If you use an official SDK, prefer its WebSocket client, which signs the handshake automatically from hmacCredentials (TypeScript) / hmac_credentials (Python) / WithHMACCredentials (Go).

Subscribing to market data

Subscribe to price and orderbook updates by emitting subscribe_market_prices:

// AMM price updates
socket.emit('subscribe_market_prices', {
  marketAddresses: ['0x1234...']
});

// CLOB orderbook updates
socket.emit('subscribe_market_prices', {
  marketSlugs: ['btc-100k-weekly']
});

// Both at once (recommended to avoid overwriting subscriptions)
socket.emit('subscribe_market_prices', {
  marketAddresses: ['0x1234...'],
  marketSlugs: ['btc-100k-weekly']
});

Subscriptions replace previous ones. If you want both AMM prices and CLOB orderbook, send both marketAddresses and marketSlugs together in a single call.

Subscribing to position updates

Subscribe to real-time position changes by emitting subscribe_positions. This requires an HMAC-signed handshake. See Authentication. subscribe_positions accepts the same payload as subscribe_market_prices:

Field	Type	Description
`marketAddresses`	`string[]`	Contract addresses for AMM markets
`marketSlugs`	`string[]`	Slugs for CLOB markets

import { io } from 'socket.io-client';

const socket = io('wss://ws.limitless.exchange/markets', {
  transports: ['websocket'],
  extraHeaders: wsAuthHeaders(TOKEN_ID, SECRET),
});

socket.on('connect', () => {
  // Subscribe to position updates for specific markets
  socket.emit('subscribe_positions', {
    marketAddresses: ['0x1234...'],   // AMM markets
    marketSlugs: ['btc-100k-weekly'], // CLOB markets
  });
});

// Confirmation
socket.on('system', (data) => {
  console.log(data);
  // { message: 'Successfully subscribed to position updates', markets: { addresses: [...], slugs: [...] } }
});

// Position updates
socket.on('positions', (data) => {
  console.log('Position update:', data);
});

Like subscribe_market_prices, calling subscribe_positions again replaces the previous subscription. Include all markets in a single call.

Position updates are pushed automatically when your balances change (e.g. after a trade is mined). You do not need to poll.

Subscribing to order events

Subscribe to the full lifecycle of your CLOB orders by emitting subscribe_order_events. Requires an HMAC-signed handshake. See Authentication. The subscription takes no payload. It is a per-user channel that delivers events for every order you are party to. Several event shapes arrive on the same Socket.IO event name orderEvent. Distinguish first by source, then by type:

OME — off-chain matching engine updates: resting-order state changes (PLACEMENT, UPDATE, CANCELLATION) and the terminal result of an immediate-or-cancel order (EXECUTION).
SETTLEMENT — settlement lifecycle for CLOB trades: a provisional MATCHED the moment the engine fills your order (before the on-chain transaction), then a terminal MINED or FAILED.

import { io } from 'socket.io-client';

const socket = io('wss://ws.limitless.exchange/markets', {
  transports: ['websocket'],
  extraHeaders: wsAuthHeaders(TOKEN_ID, SECRET),
});

socket.on('connect', () => {
  socket.emit('subscribe_order_events');
});

socket.on('system', (msg) => {
  // { message: 'Successfully subscribed to order event updates' }
  console.log(msg);
});

socket.on('orderEvent', (data) => {
  if (data.source === 'OME' && data.type === 'EXECUTION') {
    console.log(`[EXECUTION ${data.status}] order=${data.orderId} remaining=${data.remainingSize}`);
  } else if (data.source === 'OME') {
    console.log(`[OME ${data.type}] order=${data.orderId} clientOrder=${data.clientOrderId ?? '(none)'}`);
  } else {
    console.log(
      `[SETTLEMENT ${data.type}] order=${data.orderId} clientOrder=${data.clientOrderId ?? '(none)'} tx=${data.txHash ?? '(none)'}`,
    );
  }
});

One subscription per connection. Sending subscribe_order_events a second time re-binds; the previous subscription is cancelled. There is no payload.

Channel is per-user, not per-market. You receive events for every order you are party to (as taker or maker). The subscription cannot be narrowed by market. Filter client-side on marketId / marketSlug if needed.

Ordering is not guaranteed across sources. OME and SETTLEMENT events for the same order can arrive in either order within a few seconds. Settlement can land before the corresponding UPDATE, or vice versa. Treat them as independent streams that both reference orderId / takerOrderId.

Resubscribe on reconnect. Subscriptions are not persisted server-side across disconnects. Your connect handler must re-emit subscribe_order_events.

Server-side deduplication. Repeated emissions within a 60-second sliding window are dropped, so retries and replays will not double-deliver. Client-side dedup is only required if you persist events across reconnects yourself.

Auth failures surface on the exception channel. If the HMAC auth headers are missing, invalid, or revoked, the guard emits a WsException to the client’s exception event and no orderEvent frames arrive. Subscribe to socket.on('exception', ...) if you want to detect auth failures rather than silently miss the stream.

Taker delay: order submission can be asynchronous. Some markets apply a short hold to marketable (taker) orders before the matching engine fills them. On such a market, POST /orders returns right away with execution.settlementStatus: "DELAYED" and an eligibleAt timestamp instead of blocking until settlement. This stream is how you observe the fill. Wait for the provisional MATCHED frame, then the terminal MINED / FAILED, correlating by clientOrderId / tradeEventId. Maintenance mode can postpone delayed fills beyond eligibleAt; keep the order open in your integration until a terminal event arrives. postOnly (maker) orders are never delayed. A market’s current delay is readable as settings.takerDelayMs (milliseconds; 0 = none) on the market response.

Subscribing to market lifecycle events

Subscribe to market creation and resolution events by emitting subscribe_market_lifecycle. No authentication required.

socket.on('connect', () => {
  socket.emit('subscribe_market_lifecycle');
});

socket.on('marketCreated', (data) => {
  console.log('New market:', data.slug, data.title);
});

socket.on('marketResolved', (data) => {
  console.log('Market resolved:', data.slug, data.winningOutcome);
});

marketResolved is also emitted to existing per-market room subscribers automatically (CLOB: market:{slug}, AMM: market:{address}). You don’t need a separate lifecycle subscription to receive resolution events for markets you’re already watching.

To unsubscribe:

socket.emit('unsubscribe_market_lifecycle');

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 reference

Event	Direction	Auth required	Description
`connect`	Server → Client	No	Connection established
`disconnect`	Server → Client	No	Connection lost
`subscribe_market_prices`	Client → Server	No	Subscribe to price/orderbook updates
`subscribe_positions`	Client → Server	Yes	Subscribe to position updates
`subscribe_order_events`	Client → Server	Yes	Subscribe to OME and settlement events for your CLOB orders
`subscribe_market_lifecycle`	Client → Server	No	Subscribe to market creation/resolution events
`unsubscribe_market_lifecycle`	Client → Server	No	Unsubscribe from market lifecycle events
`subscribe_unrealized_pnl`	Client → Server	No	Subscribe to Unrealized PnL leaderboard invalidation hints
`unsubscribe_unrealized_pnl`	Client → Server	No	Unsubscribe from Unrealized PnL invalidation hints
`unrealizedPnlProjectionChanged`	Server → Client	No	Hint that a subscribed Unrealized PnL leaderboard changed; refetch the REST route
`newPriceData`	Server → Client	No	AMM market price update
`orderbookUpdate`	Server → Client	No	CLOB orderbook update
`marketCreated`	Server → Client	No	New market created and visible
`marketResolved`	Server → Client	No	Market resolved with winning outcome
`positions`	Server → Client	Yes	Position balance update
`orderEvent`	Server → Client	Yes	OME lifecycle, FAK/FOK execution, and settlement updates for your CLOB orders
`system`	Server → Client	No	System notifications
`authenticated`	Server → Client	Yes	Authentication confirmation
`exception`	Server → Client	No	Error notifications

Event payloads

`newPriceData`

{
  "marketAddress": "0x1234...",
  "updatedPrices": {
    "yes": "0.65",
    "no": "0.35"
  },
  "blockNumber": 12345678,
  "timestamp": "2024-01-01T00:00:00.000Z"
}

`orderbookUpdate`

Emitted for CLOB markets when the book changes (new bids/asks, removals, or fills). orderbook carries the full updated book. Each side is a sorted array of price levels.

{
  "marketSlug": "btc-100k-weekly",
  "orderbook": {
    "bids": [
      { "price": 0.53, "size": 100 },
      { "price": 0.52, "size": 250 }
    ],
    "asks": [
      { "price": 0.55, "size": 80 },
      { "price": 0.56, "size": 300 }
    ]
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Field	Type	Description
`marketSlug`	`string`	CLOB market slug
`orderbook.bids`	`{ price: number, size: number }[]`	Bid levels, highest price first
`orderbook.asks`	`{ price: number, size: number }[]`	Ask levels, lowest price first
`timestamp`	`string`	ISO-8601 event timestamp

price and size are JSON numbers; coerce defensively to preserve decimal precision. For a one-shot snapshot, use GET /markets/{slug}/orderbook, which returns the same shape.

`positions`

Position updates have different shapes depending on market type. AMM markets:

{
  "account": "0xabcd...",
  "marketAddress": "0x1234...",
  "positions": [
    {
      "tokenId": "123456",
      "balance": "1000000",
      "outcomeIndex": 0,
      "collateralOutOnSell": "950000"
    }
  ],
  "type": "AMM"
}

CLOB markets:

{
  "account": "0xabcd...",
  "marketSlug": "btc-100k-weekly",
  "positions": [
    {
      "tokenId": "19633204485790...",
      "ctfBalance": "10000000",
      "averageFillPrice": "0.65",
      "costBasis": "6500000",
      "marketValue": "7000000",
      "marketId": 7348
    }
  ],
  "tokenIds": ["19633204485790..."],
  "timestamp": 1783728000000,
  "type": "CLOB"
}

Field	Type	Description
`timestamp`	`number`	Optional. Epoch milliseconds of the on-chain balance change that triggered this update. Only present on balance-change updates; the initial snapshot after `subscribe_positions` omits it. Use it to order snapshots against trade confirmations.

`marketCreated`

Emitted when a new market is funded and visible. Hidden markets are excluded.

{
  "slug": "btc-above-110k-apr-2026",
  "title": "$BTC above $110,000 on Apr 5, 2026?",
  "type": "CLOB",
  "groupSlug": "btc-price-markets",
  "categoryIds": [1, 5],
  "createdAt": "2026-04-02T12:00:00.000Z"
}

Field	Type	Description
`slug`	`string`	Market slug identifier
`title`	`string`	Market title
`type`	`'AMM' \| 'CLOB'`	Market type
`groupSlug`	`string?`	Parent group slug (for NegRisk submarkets)
`categoryIds`	`number[]?`	Category IDs the market belongs to
`createdAt`	`string`	ISO-8601 creation timestamp

`marketResolved`

Emitted when a market resolves. Sent to both market_lifecycle subscribers and existing market:{slug} room subscribers.

{
  "slug": "btc-above-110k-apr-2026",
  "type": "CLOB",
  "winningOutcome": "YES",
  "winningIndex": 0,
  "resolutionDate": "2026-04-05T14:00:00.000Z"
}

Field	Type	Description
`slug`	`string`	Market slug identifier
`type`	`'AMM' \| 'CLOB'`	Market type
`winningOutcome`	`'YES' \| 'NO'`	The winning outcome
`winningIndex`	`0 \| 1`	Index of the winning outcome (0 = YES, 1 = NO)
`resolutionDate`	`string`	ISO-8601 resolution timestamp

`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

`orderEvent`

Emitted for both OME state changes and on-chain settlement results. Distinguish the two shapes by the source field.

Timestamp fields

Every orderEvent frame carries a timestamp plus additive semantic timestamps. Read occurredAt, matchedAt, and publishedAt directly. Do not substitute one for another. All timestamps are ISO-8601 UTC strings, and any missing semantic timestamp arrives as null rather than a value copied from another field.

Field	Availability	Meaning
`timestamp`	Always present. Deprecated — kept for backward compatibility.	Source-dependent legacy time. On OME frames, the source transition time. On settlement frames (`MATCHED`, `MINED`, `FAILED`), always the original match time.
`occurredAt`	All frames; `string \| null`.	Lifecycle fact time. On OME frames, the source transition time. On `MATCHED`, the match time. On `MINED` / `FAILED`, the terminal decision time.
`matchedAt`	Settlement frames only; `string \| null`.	Persisted match time from the trade record. Present on `MATCHED`, `MINED`, and `FAILED`.
`publishedAt`	All frames; optional.	Per-client gateway queue time, captured immediately before the Socket.IO frame is written to your connection. Useful for isolating delivery latency from upstream lifecycle latency.

Prefer semantic timestamps. Use occurredAt for lifecycle time, matchedAt for the persisted match time on settlement frames, and publishedAt for gateway queue time. Treat timestamp as a legacy field only.

OME event (`source: "OME"`)

The OME source carries two shapes: ongoing lifecycle state changes (PLACEMENT / UPDATE / CANCELLATION) and a one-shot terminal result for immediate-or-cancel orders (EXECUTION). Tell them apart by type.

Lifecycle (`type: "PLACEMENT" | "UPDATE" | "CANCELLATION"`)

Emitted for every resting-order state change recorded by the matching engine. price and remainingSize are sent unquoted as JSON numbers. Coerce defensively to preserve decimal precision.

{
  "source": "OME",
  "type": "PLACEMENT",
  "eventId": 1234567,
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "clientOrderId": "client-order-001",
  "userId": 42,
  "marketId": "17",
  "token": "87893014956437093847...",
  "side": "BUY",
  "price": 0.53,
  "remainingSize": 100,
  "timestamp": "2026-04-20T10:15:30.000Z",
  "occurredAt": "2026-04-20T10:15:30.000Z",
  "publishedAt": "2026-04-20T10:15:30.042Z"
}

Field	Type	Description
`source`	`'OME'`	Discriminator for the OME shape
`type`	`'PLACEMENT' \| 'UPDATE' \| 'CANCELLATION'`	OME state transition
`eventId`	`number`	Monotonic OME event id
`orderId`	`string`	UUID of the order
`clientOrderId`	`string?`	Client-supplied id from `POST /orders`, when the order was placed with one. Field is omitted (not `null`) when the originating order had no client id.
`userId`	`number`	Internal user id of the order owner
`marketId`	`string`	Numeric market id (CLOB)
`token`	`string`	CTF token id (decimal string)
`side`	`'BUY' \| 'SELL'`	Order side
`price`	`number`	Limit price (unquoted JSON number)
`remainingSize`	`number`	Size remaining on the book (unquoted JSON number)
`reason`	`string?`	Engine cancellation reason. `STP_MAKER_CANCELLED` on a `CANCELLATION` event when self-trade prevention cancelled your resting maker order. Omitted otherwise.
`timestamp`	`string`	Deprecated legacy timestamp. See Timestamp fields.
`occurredAt`	`string \| null`	Source transition time for this OME event.
`publishedAt`	`string?`	Per-client gateway queue time, immediately before the frame is written to your connection.

type transitions:

PLACEMENT — order accepted by the OME.
UPDATE — remaining size changed (partial fill or amend).
CANCELLATION — removed from the book. Carries reason: "STP_MAKER_CANCELLED" when self-trade prevention cancelled your resting maker order against your own incoming order.

FAK/FOK terminal (`type: "EXECUTION"`)

Emitted once when an immediate-or-cancel order reaches a recorded terminal state — a FAK (fill-and-kill), which always terminates, or a FOK (fill-or-kill) that filled. Delivered only to the order owner. Unlike the lifecycle frames, eventId is a string (terminal:<orderId>) and the frame carries a status label.

{
  "source": "OME",
  "type": "EXECUTION",
  "status": "FILLED",
  "eventId": "terminal:550e8400-e29b-41d4-a716-446655440000",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": 42,
  "marketId": "17",
  "token": "87893014956437093847...",
  "side": "BUY",
  "price": 0.53,
  "remainingSize": 0,
  "timestamp": "2026-04-20T10:15:40.000Z",
  "occurredAt": "2026-04-20T10:15:40.000Z",
  "publishedAt": "2026-04-20T10:15:40.031Z"
}

Field	Type	Description
`source`	`'OME'`	Discriminator for the OME shape
`type`	`'EXECUTION'`	Terminal result of a FAK/FOK order
`status`	`'FILLED' \| 'PARTIALLY_FILLED' \| 'KILLED'`	Final outcome (see below)
`eventId`	`string`	`terminal:<orderId>` — string form, unlike the numeric lifecycle `eventId`
`orderId`	`string`	UUID of the order
`userId`	`number`	Internal user id of the order owner
`marketId`	`string`	Numeric market id (CLOB)
`token`	`string`	CTF token id (decimal string) — the raw token, not `YES` / `NO`
`side`	`'BUY' \| 'SELL'`	Order side
`price`	`number`	Order price
`remainingSize`	`number`	Unfilled size at termination (`0` on `FILLED`, the original size on `KILLED`)
`timestamp`	`string`	Deprecated legacy timestamp. See Timestamp fields.
`occurredAt`	`string \| null`	Terminal decision time recorded by the matching engine.
`publishedAt`	`string?`	Per-client gateway queue time, immediately before the frame is written to your connection.

status outcomes:

FILLED — the order matched in full (a FAK that matched completely, or a FOK).
PARTIALLY_FILLED — a FAK matched part of its size; the unfilled remainder was cancelled. remainingSize is that cancelled remainder.
KILLED — a FAK matched nothing and was cancelled in full. remainingSize equals the original size. A taker rejected by self-trade prevention (stpPolicy: "cancel_taker" or "cancel_both") also surfaces here as status: "KILLED". This frame carries no STP reason. The STP_TAKER_REJECTED reason is returned only on the synchronous POST /orders response.

price and remainingSize are JSON numbers (as on the lifecycle frames). Coerce defensively to preserve decimal precision.

No fee or clientOrderId on the terminal frame. It reports only the lifecycle outcome. For the realized fee, read the POST /orders response or the MINED settlement frame. token is the raw CTF token id, not the YES / NO outcome.

A FOK is all-or-nothing. A fill-or-kill order either fills completely (status: "FILLED") or is rejected with HTTP 400 and produces no event. It never emits PARTIALLY_FILLED or KILLED. Only a FAK reports a partial (PARTIALLY_FILLED) or zero (KILLED) fill.

Settlement event (`source: "SETTLEMENT"`)

The SETTLEMENT source carries the settlement lifecycle of a CLOB trade. Each participant receives its own events, keyed by userId: one for the taker order and one for each matched maker order. Two types arrive in sequence:

MATCHED — provisional. Emitted the instant the matching engine fills your order, before the on-chain settlement transaction. This is the early “your order will be matched for N” signal. Fee fields are estimates (isEstimate: true), there is no txHash yet, and the fill can still be rolled back by a later FAILED.
MINED / FAILED — terminal. Emitted after the settlement transaction resolves on-chain. MINED carries txHash and the taker’s realized fee; FAILED means the trade did not execute and no funds moved.

A MATCHED and its terminal MINED / FAILED share the same tradeEventId and orderId but use different eventId namespaces (matched:… vs settlement:…), so they never dedup-collide. Correlate provisional → terminal by tradeEventId + orderId (MATCHED does not carry clientOrderId). takerAccount and makerMatches[].account are on-chain addresses. For smart-wallet users this is the smart-wallet proxy; for EOA users it is the EOA.

Provisional match (`type: "MATCHED"`)

Emitted pre-chain, the moment the engine fills the order. Per-profile: the taker and each maker receive their own frame carrying their own side, token, size, price, and fee estimate (in a cross-outcome match the taker and maker hold opposite tokens). The taker frame aggregates the whole fill; each maker frame describes only that maker’s leg.

{
  "source": "SETTLEMENT",
  "type": "MATCHED",
  "eventId": "matched:77985c10…:d45b884d…",
  "tradeEventId": "77985c10…",
  "orderId": "d45b884d…",
  "takerOrderId": "d45b884d…",
  "marketSlug": "will-abc-happen-by-2026",
  "tokenId": "27102822276156300166...",
  "token": "NO",
  "side": "BUY",
  "price": "0.53",
  "amountContracts": "25",
  "amountCollateral": "13.25",
  "configuredFeeRateBps": 30,
  "effectiveFeeBps": 27,
  "feeAmountContracts": "0.0675",
  "isEstimate": true,
  "timestamp": "2026-04-20T10:15:40.000Z",
  "matchedAt": "2026-04-20T10:15:40.000Z",
  "occurredAt": "2026-04-20T10:15:40.000Z",
  "publishedAt": "2026-04-20T10:15:40.050Z"
}

Field	Type	Description
`source`	`'SETTLEMENT'`	Discriminator for the settlement shape
`type`	`'MATCHED'`	Provisional, pre-chain match
`eventId`	`string`	`matched:<tradeEventId>:<orderId>` — distinct namespace from the terminal `settlement:…` id
`tradeEventId`	`string`	Trade id shared with the terminal `MINED` / `FAILED` for this fill
`orderId`	`string`	UUID of the recipient’s own order in this fill
`takerOrderId`	`string`	UUID of the taker order in the trade
`marketSlug`	`string`	CLOB market slug
`tokenId`	`string`	CTF token id of the recipient’s own side (decimal string)
`token`	`'YES' \| 'NO'`	Outcome the recipient filled — its own side, not necessarily the taker’s
`side`	`'BUY' \| 'SELL'`	Recipient order side
`price`	`string`	Recipient’s fill price (decimal string) — the weighted-average across the fill on the taker frame, the maker’s own resting price on a maker frame
`amountContracts`	`string`	Filled contract amount for the recipient order
`amountCollateral`	`string`	Filled collateral amount for the recipient order
`configuredFeeRateBps`	`number`	Fee rate configured for the order
`effectiveFeeBps`	`number`	Effective fee rate used for the estimate
`feeAmountContracts`	`string?`	Fee estimate in contracts — present on BUY fills
`feeAmountCollateral`	`string?`	Fee estimate in collateral — present on SELL fills
`isEstimate`	`true`	Always `true` on `MATCHED`: fee fields are estimates, not realized on-chain charges
`timestamp`	`string`	Deprecated legacy timestamp — always the match time on settlement frames. See Timestamp fields.
`matchedAt`	`string \| null`	Persisted match time from the trade record.
`occurredAt`	`string \| null`	Match time for `MATCHED`.
`publishedAt`	`string?`	Per-client gateway queue time, immediately before the frame is written to your connection.

MATCHED is provisional. Do not settle books on it. Use it as an early acknowledgement / UI signal only. Its fee fields are estimates (isEstimate: true), not realized charges, and the fill can still end in FAILED. Reconcile on the terminal MINED frame, which carries txHash and the taker’s realized fee.

Fee currency follows side. A BUY fill reports the fee estimate in feeAmountContracts (feeAmountCollateral absent); a SELL fill reports it in feeAmountCollateral. The same convention applies on MINED.

Makers are not charged a fee. Only the taker pays. On a maker’s frame, the fee estimate fields (configuredFeeRateBps, effectiveFeeBps, feeAmountContracts / feeAmountCollateral) mirror the maker order’s configured rate and can be non-zero. A maker is not charged a fee on a matched CLOB trade; the realized maker fee is 0. Treat the taker-side estimate as a real pre-settlement charge to reconcile on MINED, and treat the maker-side estimate as informational only.

Terminal settlement (`type: "MINED" | "FAILED"`)

Emitted when a CLOB trade settles on-chain. Each participant receives a settlement event for their own order: one for the taker order and one for each matched maker order.

{
  "source": "SETTLEMENT",
  "type": "MINED",
  "eventId": "settlement:1b3a…:550e8400-e29b-41d4-a716-446655440000",
  "tradeEventId": "1b3a…",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "clientOrderId": "client-order-001",
  "takerOrderId": "e4c3…",
  "takerAccount": "0xAbC…123",
  "makerMatches": [
    {
      "account": "0xDeF…456",
      "orderId": "cb12…",
      "matchedSize": "25",
      "price": "0.53"
    }
  ],
  "marketSlug": "will-abc-happen-by-2026",
  "tokenId": "87893014956437093847...",
  "side": "BUY",
  "price": "0.53",
  "amountContracts": "25",
  "amountCollateral": "13.25",
  "configuredFeeRateBps": 0,
  "effectiveFeeBps": 0,
  "feeAmountContracts": "0",
  "txHash": "0xabc…",
  "timestamp": "2026-04-20T10:15:40.000Z",
  "matchedAt": "2026-04-20T10:15:40.000Z",
  "occurredAt": "2026-04-20T10:15:41.180Z",
  "publishedAt": "2026-04-20T10:15:41.205Z"
}

Field	Type	Description
`source`	`'SETTLEMENT'`	Discriminator for the settlement shape
`type`	`'MINED' \| 'FAILED'`	Settlement outcome
`eventId`	`string`	Stable id in the form `settlement:<tradeEventId>:<orderId>`
`tradeEventId`	`string`	Settlement trade id shared by all participant events for the same match
`orderId`	`string?`	UUID of the recipient’s own order for this event
`clientOrderId`	`string?`	Client-supplied id of the recipient’s own order (`orderId`), when the order was placed with one. Field is omitted (not `null`) when the originating order had no client id. Counterparty (`takerOrderId`, `makerMatches[].orderId`) ids are never resolved to client ids.
`takerOrderId`	`string?`	UUID of the taker order in the trade
`takerAccount`	`string?`	On-chain address of the taker (smart-wallet proxy or EOA)
`makerMatches`	`array?`	One entry per matched maker (account, orderId, matchedSize, price). A taker event can include multiple maker matches; each maker also receives a separate event for its own order.
`marketSlug`	`string?`	CLOB market slug
`tokenId`	`string?`	CTF token id for the recipient side
`side`	`'BUY' \| 'SELL'?`	Recipient order side
`price`	`string?`	Execution price as a decimal string
`amountContracts`	`string?`	Filled contract amount for the recipient order
`amountCollateral`	`string?`	Collateral amount for the recipient order
`configuredFeeRateBps`	`number?`	Fee rate configured for the order
`effectiveFeeBps`	`number?`	Effective fee rate applied to this trade
`feeAmountContracts`	`string?`	Fee amount in contracts
`txHash`	`string?`	Settlement transaction hash, when known
`timestamp`	`string`	Deprecated legacy timestamp — always the match time on settlement frames, including `MINED` and `FAILED`. See Timestamp fields.
`matchedAt`	`string \| null`	Persisted match time from the trade record.
`occurredAt`	`string \| null`	Terminal decision time for `MINED` / `FAILED`.
`publishedAt`	`string?`	Per-client gateway queue time, immediately before the frame is written to your connection.

Reconciling WS events with POST /orders. Submit an order with a clientOrderId and every orderEvent for that order — PLACEMENT, UPDATE, CANCELLATION, and the MINED / FAILED settlement frame — echoes the same clientOrderId. Match WS events to the originating request by clientOrderId rather than waiting for the POST /orders HTTP response, which only returns once settlement is MINED. If only one side supplied a clientOrderId, only that side’s event includes it.

Maker fee on MINED is informational too. Like the MATCHED estimate, a maker’s MINED fee fields are computed from the maker order’s configured rate, not a realized charge. Makers are not charged, so the realized maker fee is 0. Only the taker’s MINED fee is a realized charge.

type: "MINED" — on-chain settlement confirmed.
type: "FAILED" — settlement failed on-chain; the taker order did not execute and funds were not moved.

Getting Started

Quick Start

TypeScript SDK

Python SDK

Go SDK

Rust SDK

WebSocket

Connection

Subscribing to market data

Subscribing to position updates

Subscribing to order events

Subscribing to market lifecycle events

Subscribing to unrealized PnL updates

Event reference

Event payloads

`newPriceData`

`orderbookUpdate`

`positions`

`marketCreated`

`marketResolved`

`unrealizedPnlProjectionChanged`

`orderEvent`

Timestamp fields

OME event (`source: "OME"`)

Lifecycle (`type: "PLACEMENT" | "UPDATE" | "CANCELLATION"`)

FAK/FOK terminal (`type: "EXECUTION"`)

Settlement event (`source: "SETTLEMENT"`)

Provisional match (`type: "MATCHED"`)

Terminal settlement (`type: "MINED" | "FAILED"`)

​Connection

​Subscribing to market data

​Subscribing to position updates

​Subscribing to order events

​Subscribing to market lifecycle events

​Subscribing to unrealized PnL updates

​Event reference

​Event payloads

​newPriceData

​orderbookUpdate

​positions

​marketCreated

​marketResolved

​unrealizedPnlProjectionChanged

​orderEvent

​Timestamp fields

​OME event (source: "OME")

Lifecycle (type: "PLACEMENT" | "UPDATE" | "CANCELLATION")

FAK/FOK terminal (type: "EXECUTION")

​Settlement event (source: "SETTLEMENT")

Provisional match (type: "MATCHED")

Terminal settlement (type: "MINED" | "FAILED")

Connection

Subscribing to market data

Subscribing to position updates

Subscribing to order events

Subscribing to market lifecycle events

Subscribing to unrealized PnL updates

Event reference

Event payloads

`newPriceData`

`orderbookUpdate`

`positions`

`marketCreated`

`marketResolved`

`unrealizedPnlProjectionChanged`

`orderEvent`

Timestamp fields

OME event (`source: "OME"`)

Lifecycle (`type: "PLACEMENT" | "UPDATE" | "CANCELLATION"`)

FAK/FOK terminal (`type: "EXECUTION"`)

Settlement event (`source: "SETTLEMENT"`)

Provisional match (`type: "MATCHED"`)

Terminal settlement (`type: "MINED" | "FAILED"`)