@0xmonaco/types 1.0.51 → 1.0.54

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

@@ -11,9 +11,10 @@ export type WebSocketStatus = "connected" | "connecting" | "disconnected" | "rec
 export type StatusHandler = (status: WebSocketStatus) => void;
 /**
  * Why the connection was re-established. Delivered by
- * {@link MonacoWebSocketConfig.onResync} after the client has reconnected,
- * re-authenticated, and re-subscribed — the point where the app should refetch
- * REST snapshots and reconcile by `(id, updatedAt)`.
+ * {@link MonacoWebSocketConfig.onResync} after the socket reopens and sends its
+ * authentication/subscription requests. It does not wait for server acks or
+ * snapshots. The application owns channel-specific recovery; the SDK does not
+ * automatically refetch REST state.
  */
 export interface WebSocketResyncInfo {
     /** WebSocket close code of the connection that was lost. */
@@ -105,10 +106,10 @@ export interface MonacoWebSocketConfig {
     /** Callback for connection status changes */
     onStatusChange?: StatusHandler;
     /**
-     * Called after every automatic reconnect once the live stream is resumed
-     * (re-authenticated and re-subscribed). Refetch REST snapshots here and
-     * reconcile by `(id, updatedAt)`, last-writer-wins; events that arrived while
-     * the snapshot was in flight are newer than the snapshot rows they duplicate.
+     * Called after every automatic reconnect sends authentication/subscription
+     * requests, without waiting for acknowledgements or subscribe snapshots.
+     * Refetch and reconcile channel-specific state in this application callback;
+     * automatic reconnect does not itself perform REST recovery.
      */
     onResync?: ResyncHandler;
     /**

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/events/account-events.d.ts

@@ -5,8 +5,8 @@
  * collateral, margin ratio, and maintenance requirement for a margin account.
  *
  * This is an authenticated channel - requires the signed session-key handshake.
- * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
- * state rather than disconnected, so there is no gap signal to reconcile. Each
+ * Detected broadcast lag closes the connection with 1013 and requires resync.
+ * A lost key or terminal update need not have a later replacement. Each
  * frame carries the account's full current health, so consume it as a
  * terminal-state snapshot per margin account, never as an additive delta.
  */
@@ -18,7 +18,7 @@ export interface AccountEventData {
     marginAccountId: string;
     /**
      * Monotonic per-account counter within one producer run. It advances only on
-     * published frames, may SKIP values (at-most-once delivery, conflation), and
+     * published frames, may SKIP values (at-most-once publishing/delivery), and
      * resets to zero when the producer restarts — which can happen while your
      * WebSocket stays connected, because the socket is owned by a different
      * service. It is therefore never a gap detector and never a cross-restart

package/dist/websocket/events/account-events.js

@@ -5,8 +5,8 @@
  * collateral, margin ratio, and maintenance requirement for a margin account.
  *
  * This is an authenticated channel - requires the signed session-key handshake.
- * Lag policy is Conflate: a lagging subscriber is fast-forwarded to the latest
- * state rather than disconnected, so there is no gap signal to reconcile. Each
+ * Detected broadcast lag closes the connection with 1013 and requires resync.
+ * A lost key or terminal update need not have a later replacement. Each
  * frame carries the account's full current health, so consume it as a
  * terminal-state snapshot per margin account, never as an additive delta.
  */

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

@@ -6,9 +6,8 @@
  * tick size, quantity step, order-size bounds, or (for perp markets) leverage
  * and margin-rate bounds.
  *
- * This is a public channel (no authentication). Lag policy is Conflate: a
- * lagging subscriber is fast-forwarded to the latest frame rather than
- * disconnected. Every frame carries the market's FULL current configuration
+ * This is a public channel (no authentication). Detected broadcast lag closes the
+ * connection with 1013 and requires resync. Every frame carries the market's FULL current configuration
  * (not just the changed fields), so consume it as a terminal-state snapshot per
  * market and never as an additive delta; `changedFields` names which fields the
  * mutation touched, for callers that want to react selectively.

package/dist/websocket/events/instrument-events.js

@@ -6,9 +6,8 @@
  * tick size, quantity step, order-size bounds, or (for perp markets) leverage
  * and margin-rate bounds.
  *
- * This is a public channel (no authentication). Lag policy is Conflate: a
- * lagging subscriber is fast-forwarded to the latest frame rather than
- * disconnected. Every frame carries the market's FULL current configuration
+ * This is a public channel (no authentication). Detected broadcast lag closes the
+ * connection with 1013 and requires resync. Every frame carries the market's FULL current configuration
  * (not just the changed fields), so consume it as a terminal-state snapshot per
  * market and never as an additive delta; `changedFields` names which fields the
  * mutation touched, for callers that want to react selectively.

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

@@ -7,9 +7,8 @@
  * - all-markets (`market_stats`): one summary row per market in a single frame,
  *   carried by `MarketStatsAllEvent`.
  *
- * Both are public channels (no authentication). Lag policy is Conflate: a
- * lagging subscriber is fast-forwarded to the latest frame rather than
- * disconnected. Each frame carries the market's full current stats, so consume
+ * Both are public channels (no authentication). Detected broadcast lag closes the
+ * connection with 1013 and requires resync. Each frame carries the market's full current stats, so consume
  * it as a terminal-state snapshot, never as an additive delta.
  *
  * Perp-only fields (index/mark price, open interest, funding) are optional and

package/dist/websocket/events/market-stats-events.js

@@ -7,9 +7,8 @@
  * - all-markets (`market_stats`): one summary row per market in a single frame,
  *   carried by `MarketStatsAllEvent`.
  *
- * Both are public channels (no authentication). Lag policy is Conflate: a
- * lagging subscriber is fast-forwarded to the latest frame rather than
- * disconnected. Each frame carries the market's full current stats, so consume
+ * Both are public channels (no authentication). Detected broadcast lag closes the
+ * connection with 1013 and requires resync. Each frame carries the market's full current stats, so consume
  * it as a terminal-state snapshot, never as an additive delta.
  *
  * Perp-only fields (index/mark price, open interest, funding) are optional and