@0xmonaco/types 1.0.51 → 1.0.53

package/dist/margin-accounts/index.d.ts

@@ -161,9 +161,26 @@ export interface TransferCollateralToIsolatedRiskBucketRequest extends TransferC
      */
     applyToPositionMargin?: boolean;
 }
+/**
+ * Fund the account's cross risk bucket from the parent's unallocated
+ * collateral (the bucket is created if needed). A cross transfer names no
+ * pairs: cross scope is derived from trading — a pair joins the bucket when a
+ * cross order on it succeeds and leaves when its positions close — so funding
+ * has nothing to declare. Read the current scope from the cross bucket's row
+ * in `listMarginAccounts()` (`selectedTradingPairIds`) or from this call's
+ * response; the parent summary row carries no scope. Pairs declared before
+ * scope became derived stay recorded until they trade and their positions
+ * close.
+ */
 export interface TransferCollateralToCrossRiskBucketRequest extends TransferCollateralToParentMarginAccountRequest {
     marginMode: "CROSS";
-    selectedTradingPairIds: string[];
+    /**
+     * Removed. This used to declare — and on every top-up REPLACE — the cross
+     * bucket's scope, which let a partial list silently evict every flat pair it
+     * forgot. The server now ignores the field; the SDK no longer sends it and
+     * rejects it here so a caller learns at compile time that it does nothing.
+     */
+    selectedTradingPairIds?: never;
     tradingPairId?: never;
     strategyKey?: never;
     /** Cross risk is pooled at bucket equity — there is no per-position margin; an explicit `true` is rejected. */
@@ -252,6 +269,28 @@ export interface SimulateOrderRiskResponse {
     initialMarginRequiredAfter: string;
     maintenanceMarginRequiredAfter: string;
     freeCollateralAfter: string;
+    /**
+     * 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 are the caller's own tier-resolved rates. One figure
+     * covers an order that crosses entirely, one that rests entirely, and every
+     * split in between.
+     *
+     * Signed: NEGATIVE means a net rebate, the honest answer for a resting order
+     * on a pair whose maker fee is negative. Populated even when `accepted` is
+     * false, and for reduce-only orders — closing a position pays fees like any
+     * other fill.
+     *
+     * Assumes the resting part eventually fills, so it states what the order costs
+     * if it runs to completion: 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. Treat `undefined` as unknown, never as a free order.
+     */
     estimatedFee?: string;
     /**
      * Estimated liquidation mark-price. In ISOLATED mode, this is the

package/dist/portfolio/index.d.ts

@@ -1,4 +1,5 @@
 import type { BaseAPI } from "../api";
+import type { MarginMode } from "../margin-accounts";
 /** Closed rolling windows supported by the authoritative portfolio APIs. */
 export type PortfolioAnalyticsPeriod = "1d" | "1w" | "1m" | "all";
 export type PortfolioCoverage = "complete" | "partial" | "none";
@@ -215,6 +216,44 @@ export interface PortfolioRiskBucket {
      * (the key is omitted, never null) on persisted-fallback reads.
      */
     availableOrderCollateral?: string;
+    /**
+     * The mode this bucket is margined under.
+     *
+     * Always present — every row here IS a 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). It
+     * lets you attribute bucket margin 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, and grouping these rows by mode will not reproduce
+     * them. Those counts come from a separate query with a wider scope — every
+     * margin account for your user/application pair, while 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 `riskBuckets`.
+     */
+    marginMode: MarginMode;
+    /**
+     * The trading pair this bucket is scoped to. Present for `ISOLATED`
+     * buckets; absent (the key is omitted, never null) for `CROSS`, which spans
+     * the pairs selected into it and is scoped to none of them individually.
+     *
+     * For a cross bucket's membership read
+     * `MarginAccountSummary.selectedTradingPairIds` — it is not carried here
+     * because it 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 `(marginMode, tradingPairId)`. 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 the two surfaces attribute a legacy position
+     * carrying no risk-bucket reference to opposite buckets. Use these fields
+     * to label and group this response, not to cross-foot it against another.
+     */
+    tradingPairId?: string;
 }
 export interface PortfolioMargin {
     asOf: string;

package/dist/positions/index.d.ts

@@ -32,10 +32,16 @@ export interface Position {
     unrealizedPnl: string;
     realizedPnl: string;
     /**
-     * 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.
+     * 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 shrink the posted margin pro-rata while the
+     * realized loss stays in the bucket, so this is the unrealized-return
+     * denominator. Not a hard -100% bound: liquidation measures the bucket's
+     * whole equity, order reserves included, and a mark can gap past the
+     * backing. Open CROSS rows: 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;
     leverage?: string;

package/dist/trading/index.d.ts

@@ -55,6 +55,8 @@ export interface TradingAPI extends BaseAPI {
          * replacement re-states it and inherits nothing from the original order.
          */
         clientOrderId?: string;
+        /** The SDK generates a key once per call when omitted. Supply the same key to retry a logical order within 24 hours. */
+        idempotencyKey?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
     }): Promise<CreateOrderResponse>;
@@ -90,6 +92,8 @@ export interface TradingAPI extends BaseAPI {
          * replacement re-states it and inherits nothing from the original order.
          */
         clientOrderId?: string;
+        /** The SDK generates a key once per call when omitted. Supply the same key to retry a logical order within 24 hours. */
+        idempotencyKey?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
     }): Promise<CreateOrderResponse>;

package/dist/trading/responses.d.ts

@@ -385,6 +385,8 @@ export interface BatchCreateOrderParams {
      * execute a second time.
      */
     clientOrderId?: string;
+    /** The SDK generates a key once per item when omitted. Supply the same key for batch or single-create retries within 24 hours. */
+    idempotencyKey?: string;
 }
 /**
  * Parameters for a single order in a batch replace request

package/dist/validation/margin-accounts.d.ts

@@ -38,7 +38,13 @@ export declare const TransferCollateralToParentMarginAccountSchema: z.ZodObject<
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const TransferCollateralToRiskBucketSchema: z.ZodObject<{
-    request: z.ZodUnion<readonly [z.ZodObject<{
+    request: z.ZodPipe<z.ZodObject<{
+        marginMode: z.ZodOptional<z.ZodEnum<{
+            ISOLATED: "ISOLATED";
+            CROSS: "CROSS";
+        }>>;
+        selectedTradingPairIds: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>, z.ZodUnion<readonly [z.ZodObject<{
         asset: z.ZodString;
         amount: z.ZodString;
         tradingPairId: z.ZodUUID;
@@ -50,10 +56,10 @@ export declare const TransferCollateralToRiskBucketSchema: z.ZodObject<{
         asset: z.ZodString;
         amount: z.ZodString;
         marginMode: z.ZodLiteral<"CROSS">;
-        selectedTradingPairIds: z.ZodArray<z.ZodUUID>;
+        selectedTradingPairIds: z.ZodOptional<z.ZodNever>;
         strategyKey: z.ZodOptional<z.ZodNever>;
         tradingPairId: z.ZodOptional<z.ZodNever>;
-    }, z.core.$strict>]>;
+    }, z.core.$strict>]>>;
 }, z.core.$strip>;
 export declare const TransferCollateralFromParentMarginAccountSchema: z.ZodObject<{
     request: z.ZodObject<{

package/dist/validation/margin-accounts.js

@@ -56,12 +56,22 @@ const IsolatedRiskBucketRequestSchema = RiskBucketRequestSchema.extend({
     // stays strict-rejected (no per-position margin to commit to).
     applyToPositionMargin: z.boolean().optional(),
 });
+// Simulation still declares the scope it wants previewed: a preview of a
+// bucket that may not exist yet has nothing recorded to read from.
 const CrossRiskBucketScopeSchema = z.object({
     marginMode: z.literal("CROSS"),
     selectedTradingPairIds: SelectedCrossTradingPairIdsSchema,
     strategyKey: z.never().optional(),
 });
-const CrossRiskBucketRequestSchema = CrossRiskBucketScopeSchema.extend({
+// A cross transfer-in names no pairs. Cross scope is derived from trading, so
+// funding has nothing to declare; `selectedTradingPairIds` used to REPLACE the
+// scope on every top-up (silently evicting any flat pair a partial list
+// forgot) and is now ignored by the server. Rejected here so the caller learns
+// it does nothing rather than believing it took effect.
+const CrossRiskBucketRequestSchema = z.object({
+    marginMode: z.literal("CROSS"),
+    selectedTradingPairIds: z.never().optional(),
+    strategyKey: z.never().optional(),
     tradingPairId: z.never().optional(),
 });
 export const TransferCollateralSchema = z.object({
@@ -71,11 +81,29 @@ export const TransferCollateralSchema = z.object({
 export const TransferCollateralToParentMarginAccountSchema = z.object({
     request: ParentMarginAccountCollateralRequestSchema,
 });
+// Named ahead of the union: a union of two strict members collapses every
+// mismatch into a single "Invalid input" on `request`, which would hide the one
+// mistake this schema most needs to name.
+const CrossTransferNamesNoPairsSchema = z
+    .object({
+    marginMode: z.enum(["ISOLATED", "CROSS"]).optional(),
+    selectedTradingPairIds: z.unknown().optional(),
+})
+    .loose()
+    .superRefine((request, ctx) => {
+    if (request.marginMode === "CROSS" && request.selectedTradingPairIds !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["selectedTradingPairIds"],
+            message: "selectedTradingPairIds is not accepted on a CROSS transfer: cross scope is derived from trading, so a funding call has nothing to declare",
+        });
+    }
+});
 export const TransferCollateralToRiskBucketSchema = z.object({
-    request: z.union([
+    request: CrossTransferNamesNoPairsSchema.pipe(z.union([
         ParentMarginAccountCollateralRequestSchema.merge(IsolatedRiskBucketRequestSchema).strict(),
         ParentMarginAccountCollateralRequestSchema.merge(CrossRiskBucketRequestSchema).strict(),
-    ]),
+    ])),
 });
 export const TransferCollateralFromParentMarginAccountSchema = z.object({
     request: ParentMarginAccountCollateralRequestSchema,

package/dist/validation/trading.d.ts

@@ -88,6 +88,7 @@ export declare const ParentTpSlLegSchema: z.ZodObject<{
 /**
  * Place Limit Order validation schema
  */
+export declare const OrderIdempotencyKeySchema: z.ZodString;
 export declare const PlaceLimitOrderSchema: z.ZodObject<{
     tradingPairId: z.ZodUUID;
     side: z.ZodEnum<{
@@ -97,6 +98,7 @@ export declare const PlaceLimitOrderSchema: z.ZodObject<{
     quantity: z.ZodString;
     price: z.ZodString;
     options: z.ZodOptional<z.ZodObject<{
+        idempotencyKey: z.ZodOptional<z.ZodString>;
         tradingMode: z.ZodOptional<z.ZodEnum<{
             SPOT: "SPOT";
             MARGIN: "MARGIN";
@@ -169,6 +171,7 @@ export declare const PlaceMarketOrderSchema: z.ZodObject<{
     }>;
     quantity: z.ZodString;
     options: z.ZodOptional<z.ZodObject<{
+        idempotencyKey: z.ZodOptional<z.ZodString>;
         tradingMode: z.ZodOptional<z.ZodEnum<{
             SPOT: "SPOT";
             MARGIN: "MARGIN";
@@ -405,6 +408,7 @@ export declare const BatchCreateOrderItemSchema: z.ZodObject<{
     }>;
     price: z.ZodOptional<z.ZodString>;
     quantity: z.ZodString;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
     tradingMode: z.ZodOptional<z.ZodEnum<{
         SPOT: "SPOT";
         MARGIN: "MARGIN";
@@ -458,6 +462,7 @@ export declare const BatchCreateOrdersSchema: z.ZodObject<{
         }>;
         price: z.ZodOptional<z.ZodString>;
         quantity: z.ZodString;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
         tradingMode: z.ZodOptional<z.ZodEnum<{
             SPOT: "SPOT";
             MARGIN: "MARGIN";

package/dist/validation/trading.js

@@ -126,6 +126,11 @@ const legacyPositionSideMatchesOrderSide = (side, positionSide) => positionSide
 /**
  * Place Limit Order validation schema
  */
+export const OrderIdempotencyKeySchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9._:-]+$/, "idempotencyKey must contain only letters, digits, or . _ : -");
 export const PlaceLimitOrderSchema = z
     .object({
     tradingPairId: UUIDSchema,
@@ -134,6 +139,7 @@ export const PlaceLimitOrderSchema = z
     price: PositiveDecimalStringSchema,
     options: z
         .object({
+        idempotencyKey: OrderIdempotencyKeySchema.optional(),
         tradingMode: TradingModeSchema.optional(),
         useMasterBalance: z.boolean().optional(),
         expirationDate: ISO8601DateSchema.optional(),
@@ -214,6 +220,7 @@ export const PlaceMarketOrderSchema = z
     quantity: PositiveDecimalStringSchema,
     options: z
         .object({
+        idempotencyKey: OrderIdempotencyKeySchema.optional(),
         tradingMode: TradingModeSchema.optional(),
         slippageTolerance: SlippageToleranceSchema,
         marginAccountId: UUIDSchema.optional(),
@@ -508,6 +515,7 @@ export const BatchCreateOrderItemSchema = z
     side: OrderSideSchema,
     price: PositiveDecimalStringSchema.optional(),
     quantity: PositiveDecimalStringSchema,
+    idempotencyKey: OrderIdempotencyKeySchema.optional(),
     tradingMode: TradingModeSchema.optional(),
     slippageTolerance: SlippageToleranceSchema,
     useMasterBalance: z.boolean().optional(),

package/dist/websocket/client.d.ts

@@ -7,13 +7,53 @@
  * surface — the channel-coverage lock in
  * `tests/websocket/channel-coverage.test.ts` parses this file as the source
  * of truth for the SDK's channel surface.
+ *
+ * ## Subscribe-time snapshots
+ *
+ * Every subscription whose channel has a server-side baseline takes an
+ * optional trailing `onSnapshot`. It receives that channel's COMPLETE current
+ * state as one array, once, before the first live event — so a consumer can
+ * seed state from the socket instead of a REST read, and replace it wholesale
+ * after a reconnect.
+ *
+ * The argument is deliberately trailing and optional on every method: adding a
+ * required parameter, or inserting one ahead of an existing optional filter,
+ * would break every existing call site.
+ *
+ * Snapshot rows go to `onSnapshot` and nowhere else. They are the channel's
+ * terminal-state payload rather than its event envelope (see
+ * {@link SnapshotHandler}), so a consumer that reduced them through the event
+ * handler too would apply the same baseline twice.
+ *
+ * Snapshot frames are routed by the FULL canonical channel string, unlike live
+ * events, which are prefix-matched. That is what keeps two pair-scoped
+ * subscriptions' baselines on their own callbacks.
+ *
+ * **One baseline per wire subscription, not per call.** The client sends one
+ * `Subscribe` for a channel however many local handlers it has, and the server
+ * snapshots only genuinely new subscriptions — so on a channel this client
+ * already holds, a second subscriber's `onSnapshot` is not invoked until the
+ * next reconnect resubscribes. `instruments` is the exception: it caches its
+ * baseline locally and replays it to a late subscriber. The other channels
+ * cannot reuse that cache — `orders` snapshot rows are not the shape its live
+ * events carry, so there is nothing to keep the cache current with — and a
+ * stale replayed baseline would be worse than none. Subscribe once per channel
+ * and fan out in application code (a React hook already does this), or read the
+ * baseline over REST for the extra consumer.
+ *
+ * Where the server has no snapshot arm for a channel yet, the callback is
+ * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`,
+ * `trades` and `movements` take no `onSnapshot` at all: they stream events
+ * rather than state, and the channel-coverage lock pins that classification
+ * against the server's own snapshot dispatch.
  */
 import type { SessionCredentials } from "../auth/index";
 import type { Interval } from "../market";
 import type { TradingMode } from "../trading";
 import type { WebSocketStatus } from "./base";
 import type { OrderbookQuotationMode } from "./clients/orderbook-client";
-import type { AccountEvent, ConditionalOrderEvent, InstrumentEvent, LiquidationEvent, MarketStatsAllEvent, MarketStatsEvent, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, TradeEvent, TwapOrderEvent, UserBalanceEvent, UserMovementEvent } from "./events";
+import type { AccountEvent, AccountEventData, ConditionalOrderEvent, ConditionalOrderEventData, InstrumentEvent, InstrumentEventData, LiquidationEvent, LiquidationEventData, MarketStatsAllEvent, MarketStatsData, MarketStatsEvent, MarketStatsSummary, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, PositionEventData, TradeEvent, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
+import type { OrderSnapshotItem, SnapshotHandler } from "./snapshots";
 export type MessageHandler<T> = (data: T) => void;
 export interface MonacoWebSocket {
     /** Connect to the WebSocket server */
@@ -26,8 +66,8 @@ export interface MonacoWebSocket {
     getStatus: () => WebSocketStatus;
     /** Set (or clear) the session keypair used to authenticate the connection */
     setSessionKeypair: (credentials: SessionCredentials | undefined) => void;
-    /** Subscribe to order events (requires authentication) */
-    orders: (tradingPairId: string, tradingMode: TradingMode, handler: MessageHandler<OrderEvent>) => () => void;
+    /** Subscribe to order events (requires authentication); `onSnapshot` receives every resting order on the pair */
+    orders: (tradingPairId: string, tradingMode: TradingMode, handler: MessageHandler<OrderEvent>, onSnapshot?: SnapshotHandler<OrderSnapshotItem>) => () => void;
     /** Subscribe to orderbook events (public) */
     orderbook: (tradingPairId: string, tradingMode: TradingMode, magnitude: number, quotationMode: OrderbookQuotationMode, handler: MessageHandler<OrderbookEvent>) => () => void;
     /** Subscribe to OHLCV candlestick events (public) */
@@ -36,24 +76,33 @@ export interface MonacoWebSocket {
     trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>) => () => void;
     /** Subscribe to user movement events (requires authentication) */
     movements: (handler: MessageHandler<UserMovementEvent>) => () => void;
-    /** Subscribe to user order events for all trading pairs (requires authentication) */
-    userOrders: (handler: MessageHandler<OrderEvent>) => () => void;
-    /** Subscribe to user balance events (requires authentication) */
-    balances: (handler: MessageHandler<UserBalanceEvent>) => () => void;
-    /** Subscribe to conditional TP/SL lifecycle events (requires authentication) */
-    conditionalOrders: (handler: MessageHandler<ConditionalOrderEvent>, tradingPairId?: string) => () => void;
+    /** Subscribe to user order events for all trading pairs (requires authentication); `onSnapshot` receives every resting order */
+    userOrders: (handler: MessageHandler<OrderEvent>, onSnapshot?: SnapshotHandler<OrderSnapshotItem>) => () => void;
+    /** Subscribe to user balance events (requires authentication); `onSnapshot` receives the balance of every asset held */
+    balances: (handler: MessageHandler<UserBalanceEvent>, onSnapshot?: SnapshotHandler<UserBalanceEventData>) => () => void;
+    /** Subscribe to conditional TP/SL lifecycle events (requires authentication); `onSnapshot` receives every live conditional order */
+    conditionalOrders: (handler: MessageHandler<ConditionalOrderEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<ConditionalOrderEventData>) => () => void;
     /** Subscribe to TWAP parent-order lifecycle events (requires authentication) */
-    twapOrders: (handler: MessageHandler<TwapOrderEvent>, tradingPairId?: string) => () => void;
-    /** Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs */
-    positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string) => () => void;
+    twapOrders: (handler: MessageHandler<TwapOrderEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<TwapOrderEventData>) => () => void;
+    /** Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs. `onSnapshot` receives every open position */
+    positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<PositionEventData>) => () => void;
     /** Subscribe to liquidation alerts (requires authentication); omit `tradingPairId` for all pairs */
-    liquidations: (handler: MessageHandler<LiquidationEvent>, tradingPairId?: string) => () => void;
+    liquidations: (handler: MessageHandler<LiquidationEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<LiquidationEventData>) => () => void;
     /** Subscribe to account-level margin health updates for the authenticated user (requires authentication) */
-    account: (handler: MessageHandler<AccountEvent>) => () => void;
-    /** Subscribe to market lifecycle + config changes (public); omit `tradingPairId` for all markets */
-    instruments: (handler: MessageHandler<InstrumentEvent>, tradingPairId?: string) => () => void;
+    account: (handler: MessageHandler<AccountEvent>, onSnapshot?: SnapshotHandler<AccountEventData>) => () => void;
+    /**
+     * Subscribe to market lifecycle + config changes (public); omit
+     * `tradingPairId` for all markets. `onSnapshot` receives the full current
+     * config of every active market.
+     *
+     * Opting in also changes how the baseline is delivered: without
+     * `onSnapshot`, the snapshot is fanned out to `handler` as one synthetic
+     * per-market event (the channel's original behaviour, kept for source and
+     * behaviour compatibility). With it, the rows arrive only as the array.
+     */
+    instruments: (handler: MessageHandler<InstrumentEvent>, tradingPairId?: string, onSnapshot?: SnapshotHandler<InstrumentEventData>) => () => void;
     /** Subscribe to per-market statistics for one trading pair (public) */
-    marketStats: (tradingPairId: string, handler: MessageHandler<MarketStatsEvent>) => () => void;
+    marketStats: (tradingPairId: string, handler: MessageHandler<MarketStatsEvent>, onSnapshot?: SnapshotHandler<MarketStatsData>) => () => void;
     /** Subscribe to the all-markets statistics summary (public) */
-    marketStatsAll: (handler: MessageHandler<MarketStatsAllEvent>) => () => void;
+    marketStatsAll: (handler: MessageHandler<MarketStatsAllEvent>, onSnapshot?: SnapshotHandler<MarketStatsSummary>) => () => void;
 }

package/dist/websocket/client.js

@@ -7,4 +7,43 @@
  * surface — the channel-coverage lock in
  * `tests/websocket/channel-coverage.test.ts` parses this file as the source
  * of truth for the SDK's channel surface.
+ *
+ * ## Subscribe-time snapshots
+ *
+ * Every subscription whose channel has a server-side baseline takes an
+ * optional trailing `onSnapshot`. It receives that channel's COMPLETE current
+ * state as one array, once, before the first live event — so a consumer can
+ * seed state from the socket instead of a REST read, and replace it wholesale
+ * after a reconnect.
+ *
+ * The argument is deliberately trailing and optional on every method: adding a
+ * required parameter, or inserting one ahead of an existing optional filter,
+ * would break every existing call site.
+ *
+ * Snapshot rows go to `onSnapshot` and nowhere else. They are the channel's
+ * terminal-state payload rather than its event envelope (see
+ * {@link SnapshotHandler}), so a consumer that reduced them through the event
+ * handler too would apply the same baseline twice.
+ *
+ * Snapshot frames are routed by the FULL canonical channel string, unlike live
+ * events, which are prefix-matched. That is what keeps two pair-scoped
+ * subscriptions' baselines on their own callbacks.
+ *
+ * **One baseline per wire subscription, not per call.** The client sends one
+ * `Subscribe` for a channel however many local handlers it has, and the server
+ * snapshots only genuinely new subscriptions — so on a channel this client
+ * already holds, a second subscriber's `onSnapshot` is not invoked until the
+ * next reconnect resubscribes. `instruments` is the exception: it caches its
+ * baseline locally and replays it to a late subscriber. The other channels
+ * cannot reuse that cache — `orders` snapshot rows are not the shape its live
+ * events carry, so there is nothing to keep the cache current with — and a
+ * stale replayed baseline would be worse than none. Subscribe once per channel
+ * and fan out in application code (a React hook already does this), or read the
+ * baseline over REST for the extra consumer.
+ *
+ * Where the server has no snapshot arm for a channel yet, the callback is
+ * simply never invoked — a silent no-op, not an error. `orderbook`, `ohlcv`,
+ * `trades` and `movements` take no `onSnapshot` at all: they stream events
+ * rather than state, and the channel-coverage lock pins that classification
+ * against the server's own snapshot dispatch.
  */

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"][];
@@ -3340,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: {
             /**
@@ -4816,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;
@@ -6176,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: {
             /**
@@ -6255,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;
@@ -6909,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
@@ -7387,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.
@@ -7414,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.51",
+	"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.51",
+		"@0xmonaco/contracts": "1.0.53",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {