@0xmonaco/types 1.0.50 → 1.0.53

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/websocket/index.d.ts

@@ -7,3 +7,4 @@ export * from "./base";
 export * from "./client";
 export * from "./clients/orderbook-client";
 export * from "./events";
+export * from "./snapshots";

package/dist/websocket/index.js

@@ -7,3 +7,4 @@ export * from "./base";
 export * from "./client";
 export * from "./clients/orderbook-client";
 export * from "./events";
+export * from "./snapshots";

package/dist/websocket/snapshots.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Subscribe-time WebSocket snapshot types.
+ *
+ * The server injects one `Snapshot` frame per subscription, after the
+ * `Subscribed` ack and before that subscription's first live diff. Its `data`
+ * is the channel's COMPLETE current state as a flat array — a consumer that
+ * applies it wholesale needs no REST baseline read for that channel.
+ *
+ * Two rules hold across every channel:
+ *
+ * - **A snapshot row is the channel's terminal-state payload, not its event
+ *   envelope.** The live frame wraps its payload (`{ event_type, user_id, data }`
+ *   for the authenticated channels); a snapshot row IS the payload, with no
+ *   wrapper and no change metadata. That is why the rows are delivered to their
+ *   own callback instead of the event handler: reducing both would apply the
+ *   same state twice, in two different shapes.
+ * - **The row type is the channel's own `…EventData`**, so the baseline and the
+ *   diffs that follow it describe state identically. `orders` is the one
+ *   exception and has its own {@link OrderSnapshotItem}: a resting order carries
+ *   fields no single order event does (`status` alongside the fill totals) and
+ *   carries none of the change-only fill metadata.
+ *
+ * A channel whose server arm is not implemented yet simply never sends the
+ * frame, so its callback is never invoked. That is a silent no-op, never an
+ * error.
+ */
+import type { OrderSide, OrderType, TimeInForce, TradingMode } from "../trading";
+/**
+ * Receives one channel's complete subscribe-time state.
+ *
+ * Invoked at most once per `Snapshot` frame, always with an array — an empty
+ * baseline arrives as `[]` rather than being skipped, so a consumer can tell
+ * "nothing is open" apart from "no baseline yet".
+ *
+ * Delivery is all-or-nothing: a frame with any unreadable row is withheld
+ * entirely rather than delivered short, because the array is contractually
+ * COMPLETE and a consumer that replaced state from a truncated one would delete
+ * whatever the unreadable row described.
+ *
+ * A frame is produced per WIRE subscription, so on a channel this client
+ * already holds a second subscriber's callback waits for the next reconnect;
+ * see `MonacoWebSocket` for the full rule.
+ */
+export type SnapshotHandler<T> = (items: T[]) => void;
+/**
+ * One resting order in an `orders` channel snapshot.
+ *
+ * The server builds this to be field-compatible with the live order event's
+ * `data` — same names, same casing, decimals as strings — and injects the three
+ * identity fields the read model does not itself carry (`userId`,
+ * `applicationId`, and the resolved `tradingPair` symbol).
+ *
+ * The change-only fill metadata of an order EVENT is deliberately absent: a
+ * snapshot describes resting state, not a fill, so there is no `eventType`,
+ * `tradeId`, `executionPrice`, `lastFillQuantity`, `role`, `fee`, `feeRaw`,
+ * `tradesCount` or slippage. The cumulative `filledQuantity` /
+ * `averageFillPrice` totals are present, because those are state.
+ *
+ * Nullability mirrors the wire exactly. Every optional field below is a Rust
+ * `Option` serialized WITHOUT `skip_serializing_if`, so the key is always
+ * present and carries `null` when unset — hence `| null` rather than `?`.
+ * `clientOrderId` is the sole field the server omits outright, so it is the
+ * sole `?`.
+ *
+ * The value unions are widened (`Union | (string & {})`) for the same reason
+ * the order event's are: the parser hands an unrecognized value through rather
+ * than dropping the row, so a closed type would promise something the runtime
+ * does not honour.
+ */
+export interface OrderSnapshotItem {
+    /** Order identifier (UUID) */
+    orderId: string;
+    /** Owning user (UUID), taken from the authenticated session */
+    userId: string;
+    /** Owning application (UUID), taken from the authenticated session */
+    applicationId: string;
+    /** Trading pair identifier (UUID) */
+    tradingPairId: string;
+    /** Trading pair symbol, e.g. "BTC/USDC" */
+    tradingPair: string;
+    /** Trading mode (e.g. "SPOT", "MARGIN") */
+    tradingMode: TradingMode | (string & {});
+    /** Order side */
+    side: OrderSide | (string & {});
+    /** Order type */
+    orderType: OrderType | (string & {});
+    /** Limit price (decimal string); `null` for a market order */
+    price: string | null;
+    /** Order quantity (decimal string) */
+    quantity: string;
+    /** `quantity` in RAW (integer, base-unit) precision */
+    quantityRaw: string;
+    /** Cumulative quantity filled (decimal string) */
+    filledQuantity: string;
+    /** `filledQuantity` in RAW (integer, base-unit) precision */
+    filledQuantityRaw: string;
+    /** Quantity still resting (decimal string) */
+    remainingQuantity: string | null;
+    /** `remainingQuantity` in RAW (integer, base-unit) precision */
+    remainingQuantityRaw: string | null;
+    /** Order status; the snapshot carries only resting statuses */
+    status: string;
+    /** Time in force */
+    timeInForce: TimeInForce | (string & {}) | null;
+    /** Average fill price (decimal string); `null` before the first fill */
+    averageFillPrice: string | null;
+    /** Order creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last update timestamp (ISO 8601) */
+    updatedAt: string | null;
+    /** Margin account backing a margin/perp order (UUID) */
+    marginAccountId: string | null;
+    /** Position the order is linked to (UUID) */
+    positionId: string | null;
+    /** Leverage for a margin/perp order (decimal string) */
+    leverage: string | null;
+    /** Whether the order can only reduce existing exposure */
+    reduceOnly: boolean;
+    /**
+     * Client-assigned correlation handle, carried so the baseline and the live
+     * events that follow it identify orders the same way. Omitted — not `null` —
+     * when the order carried none, matching the live event payload.
+     */
+    clientOrderId?: string;
+    /**
+     * Sequencer step this order's state was last written by — the SAME counter
+     * the live order events and the REST endpoints carry (0XM-2440).
+     *
+     * The one field here that is not resting state. It is carried because a
+     * reconnecting client ranks this frame against the events it has already
+     * applied by comparing exactly this value, so the frame would be unusable
+     * for its own purpose without it. Compare with `>=`, not `>`: on the stream
+     * equal versions mean the same sequencer step rather than identical state,
+     * and the snapshot row is that step's final state.
+     *
+     * Omitted — not `null` — when unknown, which is what an order last written
+     * before the field existed reports. Absent means unknown, never zero.
+     */
+    version?: number;
+}

package/dist/websocket/snapshots.js

@@ -0,0 +1,26 @@
+/**
+ * Subscribe-time WebSocket snapshot types.
+ *
+ * The server injects one `Snapshot` frame per subscription, after the
+ * `Subscribed` ack and before that subscription's first live diff. Its `data`
+ * is the channel's COMPLETE current state as a flat array — a consumer that
+ * applies it wholesale needs no REST baseline read for that channel.
+ *
+ * Two rules hold across every channel:
+ *
+ * - **A snapshot row is the channel's terminal-state payload, not its event
+ *   envelope.** The live frame wraps its payload (`{ event_type, user_id, data }`
+ *   for the authenticated channels); a snapshot row IS the payload, with no
+ *   wrapper and no change metadata. That is why the rows are delivered to their
+ *   own callback instead of the event handler: reducing both would apply the
+ *   same state twice, in two different shapes.
+ * - **The row type is the channel's own `…EventData`**, so the baseline and the
+ *   diffs that follow it describe state identically. `orders` is the one
+ *   exception and has its own {@link OrderSnapshotItem}: a resting order carries
+ *   fields no single order event does (`status` alongside the fill totals) and
+ *   carries none of the change-only fill metadata.
+ *
+ * A channel whose server arm is not implemented yet simply never sends the
+ * frame, so its callback is never invoked. That is a silent no-op, never an
+ * error.
+ */

package/dist/wire/schema.d.ts

@@ -2828,6 +2828,8 @@ export interface components {
              * @example quote-btc-1130-a
              */
             clientOrderId?: string | null;
+            /** @description Optional submission identity, distinct from clientOrderId. Use 1-64 characters from [A-Za-z0-9._:-], without whitespace. Scoped to your authenticated user/subaccount and application, shared by create and batch-create items. Retrying the same key and normalized order payload within 24 hours of the original acceptance returns the original committed submission result, even after a fill or cancellation, without executing again. Different payload returns IDEMPOTENCY_KEY_CONFLICT (HTTP 409 / gRPC ALREADY_EXISTS; per-item error in batches). Validation failures before acceptance do not reserve the key. The window does not extend on retries; after it expires the key may execute a new order, so never retry an unresolved submission after 24 hours. Generate a fresh key for each intended new order and retain it across transport retries. Without a key, a timeout or 5xx leaves the outcome unknown and must not be blindly retried. */
+            idempotencyKey?: string | null;
         };
         BatchCreateOrdersRequest: {
             orders: components["schemas"]["BatchCreateOrderItem"][];
@@ -3167,6 +3169,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: {
             /**
@@ -3334,6 +3342,8 @@ export interface components {
              * @example quote-btc-1130-a
              */
             clientOrderId?: string | null;
+            /** @description Optional submission identity, distinct from clientOrderId. Use 1-64 characters from [A-Za-z0-9._:-], without whitespace. Scoped to your authenticated user/subaccount and application, shared by create and batch-create items. Retrying the same key and normalized order payload within 24 hours of the original acceptance returns the original committed submission result, even after a fill or cancellation, without executing again. Different payload returns IDEMPOTENCY_KEY_CONFLICT (HTTP 409 / gRPC ALREADY_EXISTS; per-item error in batches). Validation failures before acceptance do not reserve the key. The window does not extend on retries; after it expires the key may execute a new order, so never retry an unresolved submission after 24 hours. Generate a fresh key for each intended new order and retain it across transport retries. Without a key, a timeout or 5xx leaves the outcome unknown and must not be blindly retried. */
+            idempotencyKey?: string | null;
         };
         CreateOrderResponse: {
             /**
@@ -4527,6 +4537,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: {
@@ -4804,10 +4820,22 @@ export interface components {
             unrealizedPnl?: string | null;
             realizedPnl?: string | null;
             /**
-             * @description Open rows: current isolated collateral for this position's risk bucket.
-             *      Terminal rows: total initial margin allocated across the position's
-             *      reducing executions when available — the margin basis for lifetime
-             *      realized return.
+             * @description Open ISOLATED rows: the position's current backing — its risk bucket's
+             *      allocated collateral adjusted by settled realized PnL and funding paid,
+             *      net of collateral reserved for the bucket's open orders, clamped at zero
+             *      (0XM-2558). Partial closes and partial liquidations shrink the posted
+             *      margin pro-rata while the realized loss stays in the bucket, so this,
+             *      not the posted margin, is the unrealized-return denominator. Not a hard
+             *      -100% bound: the liquidation trigger and liquidation_price measure the
+             *      bucket's whole equity, order reserves included, so with a resting order
+             *      the return can pass -100% by that order's earmark before liquidation
+             *      lands; a mark can gap past the backing before the asynchronous
+             *      liquidation; a fully drained bucket serves "0". Served from the live risk
+             *      engine; when only persisted state is reachable the value is gross of
+             *      order reserves. Open CROSS rows fall back to the position's posted
+             *      margin. Terminal rows: total initial margin allocated across the
+             *      position's reducing executions when available — the margin basis for
+             *      lifetime realized return.
              */
             isolatedMargin?: string | null;
             leverage?: string | null;
@@ -6164,6 +6192,33 @@ export interface components {
              *      reconstructable.
              */
             availableOrderCollateral?: string | null;
+            /**
+             * @description The mode this risk bucket is margined under. Always present: every row here is a risk bucket and its mode is a non-null column, unlike MarginAccountSummary.marginMode which is optional because that shape also models a parent row belonging to no bucket. Labels each row so bucket margin can be attributed to cross or isolated from this response alone, instead of resolving the opaque riskBucketId against the margin-accounts surface. It does NOT reconcile with the positions.cross / positions.isolated counts beside it: those are counted by a separate query over every margin account for the caller's user/application pair (these rows come from the single oldest, parent account), and they attribute a legacy position carrying no risk-bucket reference to CROSS whether or not a cross bucket row exists. Treat the counts as account-wide totals, not as a checksum over these rows.
+             * @example CROSS
+             * @enum {string}
+             */
+            marginMode: "ISOLATED" | "CROSS";
+            /**
+             * Format: uuid
+             * @description Trading pair UUID this bucket is scoped to. Present for ISOLATED buckets;
+             *      absent for CROSS, which spans the pairs selected into it and is scoped to
+             *      none of them individually — the same invariant the transfer-in endpoint
+             *      enforces by rejecting a `trading_pair_id` in CROSS mode. Read the cross
+             *      bucket's membership from `MarginAccountSummary.selected_trading_pair_ids`;
+             *      it is not carried here because it lives in a separate table and would cost
+             *      this endpoint an extra query per request.
+             *
+             *      These labels do NOT make this response row-for-row joinable with the
+             *      margin-accounts surface on (mode, pair). That surface emits rows this one
+             *      has no counterpart for — a provisioned-but-unfunded auto bucket, and a
+             *      parent row with no mode at all — and on a persisted-fallback read (no live
+             *      risk engine snapshot) the two surfaces attribute a legacy position
+             *      carrying no risk-bucket reference to OPPOSITE buckets: this endpoint reads
+             *      it as cross, the margin-accounts summary as isolated on pair match. Use
+             *      these fields to label and group this response, not to cross-foot it
+             *      against another.
+             */
+            tradingPairId?: string | null;
         };
         PortfolioSeriesWindow: {
             /**
@@ -6243,10 +6298,22 @@ export interface components {
             unrealizedPnl?: string | null;
             realizedPnl?: string | null;
             /**
-             * @description Open rows: current isolated collateral for this position's risk bucket.
-             *      Terminal rows: total initial margin allocated across the position's
-             *      reducing executions when available — the margin basis for lifetime
-             *      realized return.
+             * @description Open ISOLATED rows: the position's current backing — its risk bucket's
+             *      allocated collateral adjusted by settled realized PnL and funding paid,
+             *      net of collateral reserved for the bucket's open orders, clamped at zero
+             *      (0XM-2558). Partial closes and partial liquidations shrink the posted
+             *      margin pro-rata while the realized loss stays in the bucket, so this,
+             *      not the posted margin, is the unrealized-return denominator. Not a hard
+             *      -100% bound: the liquidation trigger and liquidation_price measure the
+             *      bucket's whole equity, order reserves included, so with a resting order
+             *      the return can pass -100% by that order's earmark before liquidation
+             *      lands; a mark can gap past the backing before the asynchronous
+             *      liquidation; a fully drained bucket serves "0". Served from the live risk
+             *      engine; when only persisted state is reachable the value is gross of
+             *      order reserves. Open CROSS rows fall back to the position's posted
+             *      margin. Terminal rows: total initial margin allocated across the
+             *      position's reducing executions when available — the margin basis for
+             *      lifetime realized return.
              */
             isolatedMargin?: string | null;
             leverage?: string | null;
@@ -6897,6 +6964,28 @@ export interface components {
             initialMarginRequiredAfter?: string | null;
             maintenanceMarginRequiredAfter?: string | null;
             freeCollateralAfter?: string | null;
+            /**
+             * @description What this order pays in fees once its WHOLE size has executed, priced by
+             *      the role each part of it plays against the book right now: the taker rate
+             *      (plus the application's additional taker fee) on the quantity that would
+             *      cross immediately, and the maker rate on the quantity that would rest and
+             *      be filled later. Both rates are the caller's own tier-resolved rates. One
+             *      figure covers both cases — an order that crosses entirely, one that rests
+             *      entirely, and every split in between.
+             *
+             *      Signed: NEGATIVE means a net rebate, which is the honest answer for a
+             *      resting order on a pair whose maker fee is negative. Populated even when
+             *      `accepted` is false, and populated for reduce-only orders — closing a
+             *      position pays fees like any other fill.
+             *
+             *      It assumes the resting part eventually fills, so it states what the order
+             *      costs if it runs to completion, not a probability-weighted figure: cancel
+             *      before the remainder fills and only the crossing part was ever charged.
+             *
+             *      ABSENT — never zero — when the engine could not price the order: it was
+             *      refused before it could be matched, or its resolved maker tier exceeds the
+             *      pair's cap. Absence means unknown, so do not render it as a free order.
+             */
             estimatedFee?: string | null;
             /**
              * @description Estimated liquidation mark-price. In ISOLATED mode, this is the
@@ -7375,7 +7464,13 @@ export interface components {
             riskBucketId?: string | null;
             /** @description Present when collateral was allocated to a risk bucket. Values: ISOLATED, CROSS. */
             marginMode?: string | null;
-            /** @description Present for cross risk-bucket transfers. */
+            /**
+             * @description The cross bucket's recorded pair scope: what trading has recorded (a pair
+             *      joins when a cross order on it fills and leaves when its positions close),
+             *      plus any pair declared before scope became derived, until it trades and
+             *      its positions close. Only on cross risk-bucket transfers, and omitted
+             *      while empty — i.e. until a cross order on the bucket has filled.
+             */
             selectedTradingPairIds?: string[] | null;
             /**
              * @description Whether the transfer was committed to a position's stored margin.
@@ -7402,9 +7497,17 @@ export interface components {
              */
             tradingPairId?: string | null;
             strategyKey?: string | null;
-            /** @description Risk bucket mode. Defaults to ISOLATED. Values: ISOLATED, CROSS. */
+            /**
+             * @description Risk bucket mode. Defaults to ISOLATED. Values: ISOLATED, CROSS. A CROSS
+             *      transfer names no pairs: the cross bucket's scope is derived from trading —
+             *      a pair joins when a cross order on it succeeds and leaves when its positions
+             *      close — so funding the bucket has nothing to declare.
+             */
             marginMode?: string | null;
-            /** @description Trading pair UUIDs selected into the cross risk bucket. Required when marginMode is CROSS. */
+            /**
+             * @deprecated
+             * @description Deprecated: accepted and ignored. Cross scope is derived from trading (a pair joins the cross bucket when a cross order on it succeeds and leaves when its positions close), so a cross transfer-in has nothing to declare and can no longer replace the scope. Rejected for ISOLATED, as before. Read the current scope from the cross bucket's row in the margin-accounts list or from this response's selectedTradingPairIds; the parent row carries no scope. Pairs declared before scope became derived stay recorded until they trade and their positions close.
+             */
             selectedTradingPairIds?: string[] | null;
             /**
              * @description What the transferred collateral becomes when the ISOLATED bucket holds an

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.50",
+	"version": "1.0.53",
 	"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.53",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {