@0xmonaco/types 1.0.47 → 1.0.50-develop.9c1b239

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,45 @@ export interface CommonOrderEventData {
      * silence. Omitted when the order carried none. Wire: `client_order_id`.
      */
     clientOrderId?: string;
+    /**
+     * `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 +126,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 +226,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 +257,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 +306,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 +337,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 +369,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 +409,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 +426,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 +451,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";