@0xmonaco/types 1.0.50 → 1.0.51

package/dist/trading/orders.d.ts

@@ -84,6 +84,51 @@ export interface Order {
     positionId?: string;
     /** Stable cause when status is CANCELLED */
     terminalReason?: OrderTerminalReason;
+    /**
+     * Opaque, compare-only revision counter for this order's state: a strictly
+     * higher value is strictly newer state for that order, and equal values
+     * mean identical state.
+     *
+     * Compare two REST reads of the same order with it — whether a re-poll
+     * advanced, or which of `getOrder` and a list row is fresher.
+     *
+     * The SAME counter is on every WebSocket order event and on the `orders`
+     * snapshot frame, so it is also the snapshot-versus-stream reconciliation
+     * key: after a disconnect, keep applying events as they arrive and merge a
+     * REST read per order — take the REST row when
+     * `snapshot.version >= local.version`, else keep local. No buffering, so no
+     * quote blackout on reconnect. The rule is `>=` rather than `>` because one
+     * sequencer step emits several events for one order (an `OrderPlaced` and
+     * then its fills) and a batch shares one step across every item, so equal
+     * means "same step" on the stream — and a REST row is that step's final
+     * state, so it wins the tie. Between two REST reads, equal does mean
+     * identical state.
+     *
+     * The snapshot frame alone does not close a reconnect gap: an order that
+     * filled or was cancelled while the socket was down is in neither the
+     * resting snapshot nor the stream. Recover those explicitly — `listUserTrades`
+     * for fills, and a targeted `getOrder` for anything local state believes is
+     * resting that the snapshot no longer lists.
+     *
+     * Read nothing else into it. It is not a count of updates; consecutive
+     * values are not expected (it is drawn from a global sequence shared by
+     * every order, so per-order values are sparse and gaps are normal); and it
+     * is not comparable across different orders.
+     *
+     * Absent means unknown — an order last written before this field existed.
+     * Fall back to a full field comparison for those rather than treating
+     * absent as version zero. Note that a comparison against an absent value
+     * cannot be true either way, so an order held locally without a version is
+     * never refreshed by the merge above: take the REST row unconditionally for
+     * those rather than letting them go stale.
+     *
+     * Prefer this over `updatedAt`: `version` is identical on every endpoint
+     * that serves the same order state and never advances without a state
+     * change, whereas `updatedAt` carries a different clock per endpoint (order
+     * detail reports the matching-engine event time, order lists report the
+     * database commit time) and can move without the order changing.
+     */
+    version?: number;
 }
 /** Stable terminal causes for accepted orders that end as CANCELLED. */
 export type OrderTerminalReason = "USER_REQUESTED" | "REPLACED" | "LIQUIDATION" | "INSUFFICIENT_MARGIN" | "REDUCE_ONLY_EXHAUSTED" | "POSITION_CLOSED" | "OCO_SIBLING_TRIGGERED" | "SYSTEM";
@@ -168,6 +213,11 @@ export type ConditionalOrderState = "PENDING_PARENT" | "ACTIVE" | "TRIGGERING" |
  * - ACTIVE: inside the execution window; child slices are firing
  * - COMPLETED: window ended (fully filled or hard-stopped with a shortfall)
  * - CANCELLED: cancelled by the user before the window ended
+ *
+ * These are the values the server sends today, not a runtime guarantee:
+ * `@0xmonaco/core` parses the `twap_orders` WebSocket frame leniently, so a
+ * state added server-side after this version ships is delivered as-is rather
+ * than dropping the update (0XM-2628). Match it with a default branch.
  */
 export type TwapOrderState = "PENDING" | "ACTIVE" | "COMPLETED" | "CANCELLED";
 /**

package/dist/trading/responses.d.ts

@@ -456,6 +456,28 @@ export interface ConditionalOrder {
     failureReason?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Opaque, compare-only revision counter for this conditional order's state —
+     * the sequencer step that wrote it (0XM-2440). A strictly higher value is
+     * strictly newer state for that conditional order.
+     *
+     * Present on REST reads and on the subscribe-time `conditional_orders`
+     * snapshot frame. **Absent on live conditional events**, by design: those are
+     * emitted from a model captured before the sequencer acted, so the only value
+     * available there is the one the row held *before* the change being
+     * announced — a client merging on `>=` would let a snapshot read at that
+     * version win the tie and undo the transition.
+     *
+     * So seed conditional state from the snapshot and REST, comparing with
+     * `snapshot.version >= local.version`, and apply live events as state without
+     * ranking them. `>=` rather than `>`: one sequencer step can write several
+     * conditional rows (a trigger writes the triggered row and cancels its OCO
+     * sibling), so equal means "same step", not identical state.
+     *
+     * Absent means unknown — a row last written before the field existed — never
+     * zero. Wire: `version`.
+     */
+    version?: number;
 }
 export interface ListConditionalOrdersResponse {
     orders: ConditionalOrder[];

package/dist/websocket/base.d.ts

@@ -29,6 +29,55 @@ export interface WebSocketResyncInfo {
 }
 /** Handler invoked after a reconnect resumes the live stream. */
 export type ResyncHandler = (info: WebSocketResyncInfo) => void;
+/**
+ * Machine-readable classification the server puts on every `Error` frame so a
+ * client can branch on the failure without string-matching the human message.
+ * Mirrors `ws-api`'s `WsErrorCode` enum, whose SCREAMING_SNAKE_CASE wire
+ * strings are pinned on the Rust side in `ws-api/src/websocket/protocol.rs`
+ * and cross-checked against this union by `@0xmonaco/core`'s
+ * `websocket-enum-parity` test.
+ */
+export type WebSocketErrorCode = 
+/** A user-specific channel was subscribed before authenticating. */
+"AUTH_REQUIRED"
+/** The `Authenticate` handshake was rejected; the connection is closed after this frame. */
+ | "AUTH_FAILED"
+/** The per-user concurrent-connection cap was reached; this connection is closed after the frame. */
+ | "CONNECTION_LIMIT"
+/** The per-connection subscription-cardinality cap was reached. */
+ | "SUBSCRIPTION_LIMIT"
+/** A subscription request was malformed or failed parameter validation. */
+ | "INVALID_SUBSCRIPTION"
+/** An inbound frame could not be parsed, or an unsupported frame type was sent. */
+ | "INVALID_MESSAGE"
+/**
+ * A previously-authenticated session became invalid after the handshake
+ * (revoked, expired, or the account was banned/deactivated). Re-authenticate
+ * rather than blindly reconnecting into the same rejection.
+ */
+ | "SESSION_INVALID"
+/**
+ * The subscribe-time snapshot could not be read. The subscription is still
+ * active and live diffs flow, but the baseline is missing — refetch it (e.g.
+ * from REST) rather than assuming the stream started from a coherent state.
+ */
+ | "SNAPSHOT_UNAVAILABLE";
+/**
+ * An `Error` frame the server sent on this connection.
+ *
+ * `code` is widened past {@link WebSocketErrorCode} on purpose: a code added
+ * server-side after this SDK version shipped is delivered as-is rather than
+ * dropped, so an older client still sees that something failed and can log it.
+ * Narrow with a `switch` on the known values and treat the default as unknown.
+ */
+export interface WebSocketErrorInfo {
+    /** Stable classification of the failure. */
+    code: WebSocketErrorCode | (string & {});
+    /** Human-readable description; for logging and display, never for branching. */
+    message: string;
+}
+/** Handler invoked for every `Error` frame the server sends. */
+export type ErrorHandler = (info: WebSocketErrorInfo) => void;
 /**
  * Reconnect/resync knobs and callbacks for the Monaco WebSocket client.
  *
@@ -62,6 +111,26 @@ export interface MonacoWebSocketConfig {
      * the snapshot was in flight are newer than the snapshot rows they duplicate.
      */
     onResync?: ResyncHandler;
+    /**
+     * Called for every `Error` frame the server sends on this connection.
+     *
+     * `Error` frames are connection-scoped, not channel-scoped, so they reach no
+     * subscription handler — without this callback a failed subscribe, an
+     * invalidated session, or an unreadable subscribe-time snapshot is invisible
+     * to the app. Branch on `code`:
+     *
+     * - `SNAPSHOT_UNAVAILABLE` — live diffs flow but the baseline is missing;
+     *   refetch it. The subscription itself is fine.
+     * - `SESSION_INVALID` — re-authenticate rather than reconnect into the same
+     *   rejection.
+     * - `AUTH_REQUIRED` — a rejected SUBSCRIBE, not an invalidated session: the
+     *   channel was never registered, and this client still holds your handler,
+     *   so it treats the channel as subscribed and sends no new `Subscribe`.
+     *   Re-authenticating alone leaves it dead. Release the last handler for the
+     *   channel and subscribe again after authenticating (0XM-2644 tracks doing
+     *   this automatically).
+     */
+    onError?: ErrorHandler;
 }
 /**
  * Raw event message interface

package/dist/websocket/events/balance-events.d.ts

@@ -45,7 +45,7 @@ export interface UserBalanceEventData {
     /** Total balance in raw format (wei) */
     totalRaw: string;
     /** Reason for the balance update */
-    reason: BalanceUpdateReason;
+    reason: BalanceUpdateReason | (string & {});
     /** Reference ID for related entity (e.g., order ID, deposit ID) */
     referenceId: string | null;
     /** Timestamp when the balance was updated (ISO 8601) */

package/dist/websocket/events/conditional-order-events.d.ts

@@ -13,7 +13,10 @@ export type ConditionalOrderEventReason = "created" | "activated" | "cancelled"
  * A conditional (TP/SL) order's current state.
  *
  * **The value unions below are the values the server can send today, not a
- * runtime guarantee.** `@0xmonaco/core` parses this frame leniently — an
+ * runtime guarantee** — which is why each of those fields is typed
+ * `Union | (string & {})`: autocomplete still offers the known values, but a
+ * `switch` over one needs a `default` branch because an unrecognized value
+ * really can arrive (0XM-2628). `@0xmonaco/core` parses this frame leniently — an
  * unrecognized `orderType`, `state`, `side`, `positionSide`, `conditionType`,
  * `triggerSource`, `associationType` or `timeInForce` is passed through as-is
  * rather than validated, because throwing inside the WebSocket message handler
@@ -36,13 +39,13 @@ export interface ConditionalOrderEventData {
     marginAccountId: string;
     positionId?: string;
     parentOrderId?: string;
-    associationType?: "POSITION" | "PARENT_ORDER";
+    associationType?: "POSITION" | "PARENT_ORDER" | (string & {});
     linkedGroupId?: string;
-    conditionType: ConditionalOrderConditionType;
-    triggerSource: ConditionalOrderTriggerSource;
+    conditionType: ConditionalOrderConditionType | (string & {});
+    triggerSource: ConditionalOrderTriggerSource | (string & {});
     triggerPrice: string;
-    side: OrderSide;
-    positionSide: PositionSide;
+    side: OrderSide | (string & {});
+    positionSide: PositionSide | (string & {});
     /**
      * Order shape the conditional order places when it triggers.
      *
@@ -58,7 +61,7 @@ export interface ConditionalOrderEventData {
      * the value would arrive as e.g. `STOPLOSS` rather than the canonical
      * `STOP_LOSS`. The parser passes such a value through untouched.
      */
-    orderType: OrderType;
+    orderType: OrderType | (string & {});
     limitPrice?: string;
     quantity?: string;
     slippageToleranceBps?: number;
@@ -71,8 +74,8 @@ export interface ConditionalOrderEventData {
      * the server maps exhaustively over every variant, so a value written by any
      * other path reaches the wire as-is. Narrow before relying on the subset.
      */
-    timeInForce?: TimeInForce;
-    state: ConditionalOrderState;
+    timeInForce?: TimeInForce | (string & {});
+    state: ConditionalOrderState | (string & {});
     triggeredOrderId?: string;
     triggeredAt?: string;
     activatedAt?: string;
@@ -87,6 +90,28 @@ export interface ConditionalOrderEventData {
      */
     reason: string;
     updatedAt: string;
+    /**
+     * Opaque, compare-only revision counter for this conditional order's state —
+     * the sequencer step that wrote it (0XM-2440). A strictly higher value is
+     * strictly newer state for that conditional order.
+     *
+     * Present on REST reads and on the subscribe-time `conditional_orders`
+     * snapshot frame. **Absent on live conditional events**, by design: those are
+     * emitted from a model captured before the sequencer acted, so the only value
+     * available there is the one the row held *before* the change being
+     * announced — a client merging on `>=` would let a snapshot read at that
+     * version win the tie and undo the transition.
+     *
+     * So seed conditional state from the snapshot and REST, comparing with
+     * `snapshot.version >= local.version`, and apply live events as state without
+     * ranking them. `>=` rather than `>`: one sequencer step can write several
+     * conditional rows (a trigger writes the triggered row and cancels its OCO
+     * sibling), so equal means "same step", not identical state.
+     *
+     * Absent means unknown — a row last written before the field existed — never
+     * zero. Wire: `version`.
+     */
+    version?: number;
 }
 export interface ConditionalOrderEvent {
     eventType: "conditional_order_update";

package/dist/websocket/events/instrument-events.d.ts

@@ -36,8 +36,18 @@ export type InstrumentChangeKind = "listing" | "delisting" | "halt" | "unhalt" |
  * Full current configuration for a market on the `instrument` channel.
  */
 export interface InstrumentEventData {
-    /** What changed for this market */
-    change: InstrumentChangeKind;
+    /**
+     * What changed for this market.
+     *
+     * Widened past {@link InstrumentChangeKind} on purpose: `@0xmonaco/core`
+     * parses this frame leniently, so a change kind added server-side after this
+     * SDK version ships is delivered as-is rather than dropping the frame — and
+     * with it the full market config the frame carries, which can hide a market
+     * going inactive behind an unfamiliar label (0XM-2628).
+     * `InstrumentChangeKind` names the values the server sends today — narrow
+     * with a `switch` that keeps a `default` branch.
+     */
+    change: InstrumentChangeKind | (string & {});
     /** Trading pair identifier (UUID) */
     tradingPairId: string;
     /** Market symbol, e.g. "BTC/USDC" */

package/dist/websocket/events/market-stats-events.d.ts

@@ -85,6 +85,11 @@ export interface MarketStatsEvent {
 /**
  * A single market's row in the all-markets summary frame. A lighter shape than
  * {@link MarketStatsData}: enough to render a markets table.
+ *
+ * `marketStatus` is typed `MarketStatus | (string & {})`: `@0xmonaco/core`
+ * parses this frame leniently, so an unrecognized status is passed through
+ * rather than throwing and dropping the summary row (0XM-2628). `MarketStatus`
+ * names the values the server sends today — match it with a `default` branch.
  */
 export interface MarketStatsSummary {
     /** Trading pair identifier (UUID) */
@@ -114,7 +119,7 @@ export interface MarketStatsSummary {
     /** Next funding time as a millisecond epoch. Perp-only; omitted for spot. */
     fundingTimestamp?: number;
     /** Tradability label (always present) */
-    marketStatus: MarketStatus;
+    marketStatus: MarketStatus | (string & {});
 }
 /**
  * All-markets summary event on the `market_stats` channel: one

package/dist/websocket/events/ohlcv-events.d.ts

@@ -21,15 +21,20 @@ export interface OHLCVEvent {
     /** Trading pair ID (UUID) */
     tradingPairId: string;
     /** Candlestick interval */
-    interval: Interval;
+    interval: Interval | (string & {});
     /** Trading mode */
-    tradingMode: TradingMode;
+    tradingMode: TradingMode | (string & {});
     /**
      * Price series this candle belongs to. Always a concrete series on the wire
      * (`trade` or `mark`, never the `*` selector); lets a wildcard subscriber
      * tell the two streams apart. Absent only on legacy frames that omit it.
+     *
+     * Widened past the two known values on purpose: a wildcard subscription
+     * matches any suffix, so a series added server-side after this version still
+     * arrives here, and telling the streams apart is the entire point of the
+     * field. Match it with a `default` branch.
      */
-    priceType?: "trade" | "mark";
+    priceType?: "trade" | "mark" | (string & {});
     /** OHLCV candlestick data */
     candlestick: Candlestick;
 }

package/dist/websocket/events/orderbook-events.d.ts

@@ -29,7 +29,7 @@ export interface OrderbookLevel {
  */
 export interface PriceChange {
     /** Order side (BUY or SELL) */
-    side: OrderSide;
+    side: OrderSide | (string & {});
     /** Old price before the change */
     oldPrice?: string;
     /** New price after the change */
@@ -46,7 +46,7 @@ export interface OrderbookEvent {
     /** Trading pair ID (UUID) */
     tradingPairId: string;
     /** Trading mode (SPOT, MARGIN) */
-    tradingMode: TradingMode;
+    tradingMode: TradingMode | (string & {});
     /** Bid orders (buy orders) - Full depth */
     bids: OrderbookLevel[];
     /** Ask orders (sell orders) - Full depth */

package/dist/websocket/events/orders-events.d.ts

@@ -18,7 +18,7 @@ export interface OrderEvent {
     /** Order ID (UUID) */
     orderId: string;
     /** Event type */
-    eventType: OrderEventType;
+    eventType: OrderEventType | (string & {});
     /** ISO 8601 timestamp */
     timestamp: string;
     /** Event-specific data */
@@ -46,11 +46,11 @@ export interface CommonOrderEventData {
      */
     tradingPair: string;
     /** Trading mode (e.g., "SPOT", "MARGIN") */
-    tradingMode: TradingMode;
+    tradingMode: TradingMode | (string & {});
     /** Order type - present in most events */
-    orderType?: OrderType;
+    orderType?: OrderType | (string & {});
     /** Order side - present in most events */
-    side?: OrderSide;
+    side?: OrderSide | (string & {});
     /** Order price - present in most events */
     price?: string;
     /** Order quantity - present in most events */
@@ -58,7 +58,7 @@ export interface CommonOrderEventData {
     /** Order quantity in RAW (integer, base-unit) precision. Wire: `quantity_raw`. */
     quantityRaw?: string;
     /** Time in force - present in most events */
-    timeInForce?: TimeInForce;
+    timeInForce?: TimeInForce | (string & {});
     /**
      * Client-assigned correlation handle, echoed so an event can be matched to
      * the request that placed the order without a round trip to `getOrder`.
@@ -79,6 +79,65 @@ export interface CommonOrderEventData {
      * silence. Omitted when the order carried none. Wire: `client_order_id`.
      */
     clientOrderId?: string;
+    /**
+     * Sequencer step that produced this event (0XM-2440) — the SAME counter
+     * `getOrder` and `getPaginatedOrders` return, so the two are directly
+     * comparable. Higher is strictly newer for that order.
+     *
+     * This is what makes a reconnect reconcilable without buffering: apply
+     * events as they arrive, and when the REST snapshot lands take the snapshot
+     * for an order when `snapshot.version >= local.version`, else keep local.
+     *
+     * **Equal does NOT mean identical state here.** One sequencer step emits
+     * several events for one order (an `OrderPlaced` and then its fills), and a
+     * batch place/replace shares one step across every item — so equal means
+     * "same step". A snapshot row is that step's FINAL state, which is why the
+     * rule is `>=` and not `>`: on a tie the snapshot is the authority.
+     *
+     * Values are sparse per order (it comes from a global sequence) and are not
+     * comparable between different orders. Omitted, never zero, when unknown —
+     * an order last written before the field existed. Wire: `version`.
+     */
+    version?: number;
+    /**
+     * `true` when the order was admitted post-only (maker-only), so a subscriber
+     * can confirm the flag was honoured without a round trip to `getOrder`.
+     * Carried on the `OrderPlaced` acknowledgement, the taker fill, and the
+     * resting order's lifecycle — `OrderPartiallyCancelled` (an in-place
+     * reduction, which is how an MM's own `remainingQuantityTarget` replace is
+     * announced), `OrderCancelled` and `OrderExpired`.
+     *
+     * Declared on the shared block, but two variants can never carry it, and
+     * this optional field is the only thing that says so: a **maker fill**,
+     * which is out of scope because a maker already learned the flag from its
+     * own acknowledgement; and **`OrderRejected`**, which only ever describes a
+     * MARKET order with no liquidity or an unfilled IOC/FOK — and post-only is
+     * refused on both, so no post-only order can reach it.
+     *
+     * Only ever present as `true`: on a variant that CARRIES the field, an order
+     * that is not post-only omits the key rather than sending `postOnly: false`,
+     * exactly as the REST read model's `postOnly?: boolean` does, so
+     * `event.data.postOnly ?? false` reads the same as REST *for that event*.
+     *
+     * That equivalence is per-event, and it does NOT hold on a maker fill.
+     * A post-only order rests and therefore fills as a maker, and the maker
+     * payload never declares the field — so `?? false` there would return
+     * `false` for an order REST reports as `true`. Absence on a maker fill
+     * carries NO information. Track `postOnly` as order-level state learned from
+     * the `OrderPlaced` acknowledgement (or a REST read) and carry it forward;
+     * never re-derive it from whichever event arrived last.
+     *
+     * On a carrying variant, absent is not evidence the flag was dropped — it is
+     * the ordinary shape of a non-post-only order, and also what an order placed
+     * before the flag was persisted reports.
+     *
+     * A post-only order that WOULD have crossed the book is rejected before
+     * acceptance and emits no event at all (see `clientOrderId`), so in practice
+     * the flag reaches a subscriber on a resting order's lifecycle — never on a
+     * taker fill, which an admitted post-only order cannot produce.
+     * Wire: `post_only`.
+     */
+    postOnly?: boolean;
 }
 /**
  * OrderPlaced event - emitted when a new order is placed
@@ -87,54 +146,94 @@ export interface OrderPlacedEvent extends OrderEvent {
     eventType: "OrderPlaced";
     data: CommonOrderEventData & {
         /** Order status */
-        status: OrderStatus;
+        status: OrderStatus | (string & {});
     };
 }
 /**
  * OrderMatched event - emitted when an order is matched but not necessarily filled
- * This event is only emitted for taker orders
+ * This event is only emitted for taker orders.
+ *
+ * Carries the SAME payload as `OrderFilled`/`OrderPartiallyFilled`: the
+ * matching engine builds one `TakerOrderEventData` and picks the event type
+ * from the resulting status, so every execution field below is on the wire
+ * here too.
+ *
+ * Because this event carries only that one shape, the fields below follow it
+ * exactly rather than being uniformly optional. A match that filled nothing
+ * still SENDS the keys — `tradeId`, `executionPrice` and `executedAt` arrive as
+ * `null`, not absent. Only `lastFillQuantity` and `lastFillQuantityRaw` are
+ * ever omitted, being the pair the server skips when there is no incremental
+ * fill.
  */
 export interface OrderMatchedEvent extends OrderEvent {
     eventType: "OrderMatched";
     data: CommonOrderEventData & {
-        /** Taker order ID */
-        takerOrderId?: string;
-        /** Reference price used for slippage calculation */
-        referencePrice?: string;
-        /** Best price achieved in matching */
-        bestPrice?: string;
-        /** Worst price achieved in matching */
-        worstPrice?: string;
-        /** Actual slippage in basis points */
-        actualSlippageBps?: number;
-        /** Maximum allowed slippage in basis points */
-        maxSlippageBps?: number;
-        /** Number of trades executed (taker only) */
-        tradesCount?: number;
-        /** Total quantity filled (taker only) */
-        totalFilled?: string;
-        /** Remaining quantity to be filled (taker only) */
-        remainingQuantity?: string;
-        /** Average fill price across all trades */
-        averageFillPrice?: string;
-        /** Order status */
-        status?: OrderStatus;
+        /** Fill role of this order (`taker` on this event). */
+        role: OrderRole | (string & {});
+        /** Trade ID of the first trade this event covers. `null` when it covers none. */
+        tradeId: string | null;
+        /** Execution price of the first trade this event covers. `null` when it covers none. */
+        executionPrice: string | null;
+        /** Cumulative quantity filled on the order at this event. Wire: `filled_quantity`. */
+        filledQuantity: string;
+        /** `filledQuantity` in RAW (integer, base-unit) precision. Wire: `filled_quantity_raw`. */
+        filledQuantityRaw: string;
+        /** Incremental quantity filled by THIS event. Omitted when there is no fill. Wire: `last_fill_quantity`. */
+        lastFillQuantity?: string;
+        /** `lastFillQuantity` in RAW (integer, base-unit) precision. Omitted with it. Wire: `last_fill_quantity_raw`. */
+        lastFillQuantityRaw?: string;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw: string;
+        /**
+         * Monaco fee for the fills this event covers, in normalized decimal QUOTE
+         * units (negative = maker rebate). Excludes the application taker fee, so
+         * it is smaller than the order echo's `totalTakerFees` for an application
+         * that charges one, and equal to it for one that does not. Wire: `fee`.
+         */
+        fee: string;
+        /**
+         * `fee` in RAW quote-unit precision (scaled by 10^quoteDecimals). Always a
+         * whole number -- the engine truncates every fee to an integral raw unit
+         * when it stores it -- so `fee` is exactly this value divided by
+         * 10^quoteDecimals, and `BigInt(feeRaw)` is safe. Wire: `fee_raw`.
+         */
+        feeRaw: string;
+        /** Execution timestamp of the first trade this event covers (ISO 8601). `null` when it covers none. */
+        executedAt: string | null;
+        /** Reference price used for slippage calculation. `null` when unset. */
+        referencePrice: string | null;
+        /** Best price achieved in matching. `null` when unset. */
+        bestPrice: string | null;
+        /** Worst price achieved in matching. `null` when unset. */
+        worstPrice: string | null;
+        /** Actual slippage in basis points. `null` when unset. */
+        actualSlippageBps: number | null;
+        /** Maximum allowed slippage in basis points. `null` when unset. */
+        maxSlippageBps: number | null;
+        /** Number of trades executed. */
+        tradesCount: number;
+        /** Remaining quantity to be filled. */
+        remainingQuantity: string;
+        /** Average fill price across all trades. `null` when there is none. */
+        averageFillPrice: string | null;
+        /** Order status. */
+        status: OrderStatus | (string & {});
     };
 }
 /**
  * OrderPartiallyFilled event - emitted when an order is partially filled
- * Can be emitted for both taker and maker orders with different field sets
+ * Can be emitted for both taker and maker orders with different field sets.
  *
- * Taker events include: trades_count, total_filled, slippage data
- * Maker events include: trade_id, execution_price, execution_quantity, maker_fee
+ * Taker events add `trades_count` and the slippage fields; maker events add
+ * `trade_id` and `execution_price`. Both roles report the cumulative fill as
+ * `filled_quantity` and this event's increment as `last_fill_quantity`, and
+ * both carry the fill charge as `fee` (0XM-2389). `total_filled`,
+ * `execution_quantity` and `maker_fee` were never emitted on a fill payload
+ * and are not declared here.
  */
 export interface OrderPartiallyFilledEvent extends OrderEvent {
     eventType: "OrderPartiallyFilled";
     data: CommonOrderEventData & {
-        /** Taker order ID (taker orders only) */
-        takerOrderId?: string;
-        /** Maker order ID (maker orders only) */
-        makerOrderId?: string;
         /** Reference price (taker orders only) */
         referencePrice?: string;
         /** Best price (taker orders only) */
@@ -147,14 +246,12 @@ export interface OrderPartiallyFilledEvent extends OrderEvent {
         maxSlippageBps?: number;
         /** Number of trades (taker orders only - not present for maker) */
         tradesCount?: number;
-        /** Total filled quantity (taker orders only - not present for maker) */
-        totalFilled?: string;
         /** Remaining quantity (present for both taker and maker) */
         remainingQuantity?: string;
         /** Average fill price (taker orders only) */
         averageFillPrice?: string;
         /** Order status (taker orders only) */
-        status?: OrderStatus;
+        status?: OrderStatus | (string & {});
         /** Trade ID (maker orders only) */
         tradeId?: string;
         /** Execution price (maker orders only) */
@@ -180,30 +277,43 @@ export interface OrderPartiallyFilledEvent extends OrderEvent {
         /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
         remainingQuantityRaw?: string;
         /**
-         * Fee charged for this fill (maker orders only). The wire field is `fee`
-         * (→ `fee`), not `makerFee`; taker fills carry the same `fee` field.
+         * Monaco fee for the fills this event covers, in normalized decimal QUOTE
+         * units (negative = maker rebate). The wire field is `fee`, not `makerFee`;
+         * taker and maker carry the same field. A taker event aggregates every
+         * trade it covers; a maker event is one trade.
+         *
+         * Excludes the application taker fee, so it is NOT the order echo's
+         * `totalTakerFees` (which is `fee + applicationTakerFee`). It previously
+         * held the raw integer value now exposed as `feeRaw`.
          */
         fee?: string;
+        /**
+         * `fee` in RAW quote-unit precision (scaled by 10^quoteDecimals). Always a
+         * whole number -- the engine truncates every fee to an integral raw unit
+         * when it stores it -- so `fee` is exactly this value divided by
+         * 10^quoteDecimals, and `BigInt(feeRaw)` is safe. Wire: `fee_raw`.
+         */
+        feeRaw?: string;
         /** Trade execution timestamp (maker orders only) */
         executedAt?: string;
         /** Role of the order in the trade (taker or maker) */
-        role?: OrderRole;
+        role?: OrderRole | (string & {});
     };
 }
 /**
  * OrderFilled event - emitted when an order is completely filled
- * Can be emitted for both taker and maker orders with different field sets
+ * Can be emitted for both taker and maker orders with different field sets.
  *
- * Taker events include: trades_count, total_filled, slippage data
- * Maker events include: trade_id, execution_price, execution_quantity, maker_fee
+ * Taker events add `trades_count` and the slippage fields; maker events add
+ * `trade_id` and `execution_price`. Both roles report the cumulative fill as
+ * `filled_quantity` and this event's increment as `last_fill_quantity`, and
+ * both carry the fill charge as `fee` (0XM-2389). `total_filled`,
+ * `execution_quantity` and `maker_fee` were never emitted on a fill payload
+ * and are not declared here.
  */
 export interface OrderFilledEvent extends OrderEvent {
     eventType: "OrderFilled";
     data: CommonOrderEventData & {
-        /** Taker order ID (taker orders only) */
-        takerOrderId?: string;
-        /** Maker order ID (maker orders only) */
-        makerOrderId?: string;
         /** Reference price (taker orders only) */
         referencePrice?: string;
         /** Best price (taker orders only) */
@@ -216,14 +326,12 @@ export interface OrderFilledEvent extends OrderEvent {
         maxSlippageBps?: number;
         /** Number of trades (taker orders only - not present for maker) */
         tradesCount?: number;
-        /** Total filled quantity (taker orders only - not present for maker) */
-        totalFilled?: string;
         /** Remaining quantity (present for both, should be 0 for filled orders) */
         remainingQuantity?: string;
         /** Average fill price (taker orders only) */
         averageFillPrice?: string;
         /** Order status (taker orders only) */
-        status?: OrderStatus;
+        status?: OrderStatus | (string & {});
         /** Trade ID (maker orders only) */
         tradeId?: string;
         /** Execution price (maker orders only) */
@@ -249,14 +357,27 @@ export interface OrderFilledEvent extends OrderEvent {
         /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
         remainingQuantityRaw?: string;
         /**
-         * Fee charged for this fill (maker orders only). The wire field is `fee`
-         * (→ `fee`), not `makerFee`; taker fills carry the same `fee` field.
+         * Monaco fee for the fills this event covers, in normalized decimal QUOTE
+         * units (negative = maker rebate). The wire field is `fee`, not `makerFee`;
+         * taker and maker carry the same field. A taker event aggregates every
+         * trade it covers; a maker event is one trade.
+         *
+         * Excludes the application taker fee, so it is NOT the order echo's
+         * `totalTakerFees` (which is `fee + applicationTakerFee`). It previously
+         * held the raw integer value now exposed as `feeRaw`.
          */
         fee?: string;
+        /**
+         * `fee` in RAW quote-unit precision (scaled by 10^quoteDecimals). Always a
+         * whole number -- the engine truncates every fee to an integral raw unit
+         * when it stores it -- so `fee` is exactly this value divided by
+         * 10^quoteDecimals, and `BigInt(feeRaw)` is safe. Wire: `fee_raw`.
+         */
+        feeRaw?: string;
         /** Trade execution timestamp (maker orders only) */
         executedAt?: string;
         /** Role of the order in the trade (taker or maker) */
-        role?: OrderRole;
+        role?: OrderRole | (string & {});
     };
 }
 /**
@@ -268,7 +389,7 @@ export interface OrderCancelledEvent extends OrderEvent {
         /** Reason for cancellation */
         reason?: string;
         /** Stable machine-readable cancellation cause */
-        terminalReason?: OrderTerminalReason;
+        terminalReason?: OrderTerminalReason | (string & {});
         /**
          * Cumulative order fill at cancellation, mirroring `filledQuantity` on the
          * taker/maker fill events so consumers read one field across every order
@@ -308,11 +429,15 @@ export interface OrderRejectedEvent extends OrderEvent {
         /** Reason for rejection */
         reason: string;
         /** Order status */
-        status: OrderStatus;
+        status: OrderStatus | (string & {});
         /** Total filled quantity (may-be partially filled) */
         totalFilled: string;
+        /** `totalFilled` in RAW (integer, base-unit) precision. Wire: `total_filled_raw`. */
+        totalFilledRaw: string;
         /** Remaining quantity that couldn't be filled */
         remainingQuantity: string;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw: string;
     };
 }
 /**
@@ -321,12 +446,16 @@ export interface OrderRejectedEvent extends OrderEvent {
 export interface OrderExpiredEvent extends OrderEvent {
     eventType: "OrderExpired";
     data: CommonOrderEventData & {
-        /** Filled quantity before expiration */
-        filledQuantity?: string;
-        /** Remaining quantity at expiration */
-        remainingQuantity?: string;
-        /** Average fill price (if any fills occurred) */
-        averageFillPrice?: string;
+        /** Filled quantity before expiration. `null` when the order never filled. */
+        filledQuantity: string | null;
+        /** `filledQuantity` in RAW (integer, base-unit) precision. Wire: `filled_quantity_raw`. */
+        filledQuantityRaw: string | null;
+        /** Remaining quantity at expiration. `null` when unset. */
+        remainingQuantity: string | null;
+        /** `remainingQuantity` in RAW (integer, base-unit) precision. Wire: `remaining_quantity_raw`. */
+        remainingQuantityRaw: string | null;
+        /** Average fill price. `null` when no fills occurred. */
+        averageFillPrice: string | null;
         /** Reason for expiration */
         reason: string;
     };
@@ -342,7 +471,7 @@ export interface OrderPartiallyCancelledEvent extends OrderEvent {
     eventType: "OrderPartiallyCancelled";
     data: CommonOrderEventData & {
         /** Order status — non-terminal (the order still rests) */
-        status: OrderStatus;
+        status: OrderStatus | (string & {});
         /** Cumulative filled quantity, unchanged by the reduction */
         filledQuantity: string;
         /** Cumulative filled quantity in RAW precision. Wire: `filled_quantity_raw`. */

package/dist/websocket/events/position-events.d.ts

@@ -23,6 +23,12 @@ export type PositionEventSide = "LONG" | "SHORT";
 export type PositionEventStatus = "OPEN" | "LIQUIDATING" | "CLOSED" | "LIQUIDATED" | "EXPIRED";
 /**
  * Position event data containing the current state of a single position.
+ *
+ * `side` and `status` are typed `Union | (string & {})`: `@0xmonaco/core`
+ * parses this frame leniently, so an unrecognized value is passed through
+ * rather than throwing inside the WebSocket message handler and dropping a
+ * risk-critical update entirely (0XM-2627/0XM-2628). The unions name the values
+ * the server sends today — `switch` over them with a `default` branch.
  */
 export interface PositionEventData {
     /** Position identifier (UUID) */
@@ -32,9 +38,9 @@ export interface PositionEventData {
     /** Trading pair identifier (UUID) */
     tradingPairId: string;
     /** Position side */
-    side: PositionEventSide;
+    side: PositionEventSide | (string & {});
     /** Position lifecycle status (SCREAMING_SNAKE_CASE on the wire, e.g. "OPEN") */
-    status: PositionEventStatus;
+    status: PositionEventStatus | (string & {});
     /** Absolute position size (decimal string) */
     size: string;
     /** Average entry price (decimal string) */

package/dist/websocket/events/trade-events.d.ts

@@ -15,7 +15,7 @@ export interface TradeEventData {
     /** Executed quantity */
     quantity: string;
     /** Side of the maker order (BUY or SELL) */
-    makerSide: OrderSide;
+    makerSide: OrderSide | (string & {});
     /** Timestamp when the trade was executed (ISO 8601) */
     executedAt: string;
 }
@@ -28,7 +28,7 @@ export interface TradeEvent {
     /** Trading pair ID (UUID) */
     tradingPairId: string;
     /** Trading mode (SPOT or MARGIN) */
-    tradingMode: TradingMode;
+    tradingMode: TradingMode | (string & {});
     /** Trade execution data */
     data: TradeEventData;
 }

package/dist/websocket/events/twap-order-events.d.ts

@@ -18,12 +18,20 @@ export type TwapOrderEventReason = "created" | "slice_placed" | "slice_skipped"
  * Field names mirror the backend `TwapOrderEventData` payload (snake_case on
  * the wire, camelCased by the client); the SDK parser normalizes explicit
  * `null` values to absent, so nullable wire fields are optional here.
+ *
+ * **The value unions below are the values the server sends today, not a
+ * runtime guarantee**, which is why each is typed `Union | (string & {})`:
+ * `@0xmonaco/core` hands this whole payload through with a single cast and
+ * validates no value field, so an unrecognized `side`, `tradingMode`,
+ * `executionStyle`, `state`, `triggerDirection` or `reason` arrives as-is
+ * rather than dropping the update (0XM-2628). Autocomplete still offers the
+ * known values; `switch` over one with a `default` branch.
  */
 export interface TwapOrderEventData {
     twapOrderId: string;
     tradingPairId: string;
-    side: OrderSide;
-    tradingMode: TradingMode;
+    side: OrderSide | (string & {});
+    tradingMode: TradingMode | (string & {});
     totalQuantity: string;
     executedQuantity: string;
     executedNotional: string;
@@ -41,7 +49,7 @@ export interface TwapOrderEventData {
     clientTwapId?: string;
     randomize: boolean;
     /** Child execution style: "TAKER" (banded MARKET slices) or "PASSIVE" (post-only children at the touch, taker sweep at each slice deadline) */
-    executionStyle: TwapExecutionStyle;
+    executionStyle: TwapExecutionStyle | (string & {});
     /** Window start (ISO 8601) */
     startAt: string;
     /** Window end (ISO 8601). Execution stops hard at this time. */
@@ -55,13 +63,23 @@ export interface TwapOrderEventData {
     nextSliceAt?: string;
     slicesPlaced: number;
     slicesSkipped: number;
-    state: TwapOrderState;
+    /**
+     * Lifecycle state of the parent order.
+     *
+     * Widened past {@link TwapOrderState} on purpose: `@0xmonaco/core` parses
+     * this frame leniently, so a state added server-side after this SDK version
+     * ships is delivered as-is rather than dropping the whole update (0XM-2628).
+     * `TwapOrderState` names the values the server sends today — narrow with a
+     * `switch` that keeps a `default` branch rather than relying on
+     * exhaustiveness.
+     */
+    state: TwapOrderState | (string & {});
     /** Terminal annotation, e.g. "ended with shortfall 1.5"; absent for non-terminal parents */
     terminalReason?: string;
     /** Conditional configuration + activation stamp (parity with the REST read
      * model). All absent on unconditional parents. */
     triggerPrice?: string;
-    triggerDirection?: "ABOVE" | "BELOW";
+    triggerDirection?: "ABOVE" | "BELOW" | (string & {});
     conditionalExpiry?: string;
     triggeredAt?: string;
     createdAt: string;
@@ -69,7 +87,7 @@ export interface TwapOrderEventData {
     cancelledAt?: string;
     completedAt?: string;
     /** Mutation that produced this snapshot */
-    reason: TwapOrderEventReason;
+    reason: TwapOrderEventReason | (string & {});
 }
 export interface TwapOrderEvent {
     eventType: "twap_order_update";

package/dist/wire/schema.d.ts

@@ -3167,6 +3167,12 @@ export interface components {
             parentOrderId?: string | null;
             associationType?: string | null;
             activatedAt?: string | null;
+            /**
+             * Format: int64
+             * @description Opaque, compare-only revision counter for this conditional order's state: the sequencer step that wrote it. A strictly higher value is strictly newer state for that conditional order. The SAME counter is carried on the `conditional_orders` WebSocket SNAPSHOT frame — but deliberately NOT on the live `conditional_orders` events, which build from the row as it stood before the sequencer acted and so could only report the version the row held BEFORE the change they announce. So seed conditional state from the snapshot frame and REST, reconciling on `(conditionalOrderId, version)` — take the REST row when `snapshot.version >= local.version`, else keep local state — and apply the live events as state without ranking them. Note `>=`, not `>`: equal versions mean the SAME STEP rather than identical state, because one step can write several conditional rows (a trigger writes the triggered row and cancels its OCO sibling under one step). A REST row is that step's FINAL state, so it wins a tie. One consequence to plan for: the snapshot is read from the database, which lags the matching engine, so a transition that fires during the read is in neither the snapshot nor the delivered stream and cannot be ranked — re-read the affected rows if a conditional order's state matters at reconnect. Do not read anything else into the number: it is drawn from the same global sequence plain orders use, so values are sparse, gaps are normal, and it is not comparable across different conditional orders — nor against a plain order's version. Absent means unknown: a row last written before this field existed. Fall back to a full field comparison for those rather than treating absent as version zero.
+             * @example 918342
+             */
+            version?: number | null;
         };
         CreateDelegatedSessionRequest: {
             /**
@@ -4527,6 +4533,12 @@ export interface components {
              * @example false
              */
             postOnly?: boolean | null;
+            /**
+             * Format: int64
+             * @description Opaque, compare-only revision counter for this order's state: the sequencer step that wrote it. A strictly higher value is strictly newer state for that order. The SAME counter is carried on every order WebSocket event and on the `orders` snapshot frame, so a reconnecting client reconciles on `(id, version)` — take the REST row when `snapshot.version >= local.version`, else keep local state. Note `>=`, not `>`: on the stream, equal versions mean the SAME STEP rather than identical state, because one step emits several events for one order (an `OrderPlaced` and then its fills) and a batch shares one step across every item. A REST row is that step's FINAL state, so it wins a tie. Between two REST reads the comparison is simpler — equal there does mean identical state. Do not read anything else into the number: it is not a count of updates, consecutive values are not expected (it is drawn from a global sequence shared by every order, so per-order values are sparse and gaps are normal), and it is not comparable across different orders. Absent means unknown: an order last written before this field existed. Fall back to a full field comparison for those rather than treating absent as version zero — and note that a comparison against an absent value is false in both directions, so an order held locally without one is never refreshed by the merge above; take the REST row unconditionally for those. Reconciling on this counter does NOT on its own close a reconnect gap: an order that filled or was cancelled while the socket was down appears in neither the resting snapshot nor the stream, so recover fills from `listUserTrades` (ordered by execution time) and resolve anything your local state believes is resting that the snapshot no longer lists with a targeted `getOrder`. Unlike `updatedAt`, this value is identical on every REST endpoint that serves the same order state, and never advances without a state change.
+             * @example 918342
+             */
+            version?: number | null;
         };
         /** @description Orderbook snapshot with token metadata and sequence number. */
         GetOrderbookResponse: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.50",
+	"version": "1.0.51",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,7 +16,7 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.50",
+		"@0xmonaco/contracts": "1.0.51",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {