> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.
# Order Events
> Subscribe to OME and settlement events for your CLOB orders and read the orderEvent payloads
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](/developers/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](/api-reference/trading/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`](/api-reference/trading/user-orders) with the `x-on-behalf-of` header, or authenticate as the sub-account itself. [Get Order Status (batch)](/api-reference/trading/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`.
```typescript theme={null}
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.
```json theme={null}
{
"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](/developers/websocket/order-events#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:`) and the frame carries a `status` label.
```json theme={null}
{
"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:` — 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](/developers/websocket/order-events#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 `type`s 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.
```json theme={null}
{
"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::` — 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](/developers/websocket/order-events#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.
```json theme={null}
{
"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` | `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](/developers/websocket/order-events#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.
## Related
* [WebSocket overview](/developers/websocket/overview): connection details, handshake authentication, and the full event reference