@0xmonaco/types 1.0.50 → 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/orders.d.ts

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

package/dist/trading/responses.d.ts

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

package/dist/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

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

package/dist/websocket/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;
 }