Order Events

This page covers subscribing to the lifecycle of your CLOB orders with subscribe_order_events, and the orderEvent payload shapes that subscription delivers.

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 scoped to the profile that signed the handshake: it delivers events for orders owned by that profile, whether you were the maker or the taker.

Sub-account orders are not included. An order you place for a sub-account is owned by that sub-account, so its events go to the sub-account’s channel, not yours. That applies however you delegated it: the onBehalfOf field on Create Order, the onBehalfOf query parameter on cancel, or the x-on-behalf-of header on read endpoints.Delegation is REST-only. There is no WebSocket equivalent, and the handshake cannot be widened to cover sub-accounts.To follow a sub-account’s order state, use a REST read that accepts delegation, such as GET /markets/{slug}/user-orders with the x-on-behalf-of header, or authenticate as the sub-account itself. Get Order Status (batch) does not accept delegation: it is scoped to the profile that authenticated, and a sub-account’s order ids come back not_found from it.

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.

Event payload

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

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 order events

Event payload

`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"`)

​Subscribing to order events

​Event payload

​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")

​Related

Subscribing to order events

Event payload

`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"`)

Related