@0xmonaco/core 1.0.51 → 1.0.54

package/dist/api/margin-accounts/api.js

@@ -69,7 +69,9 @@ export class MarginAccountsAPIImpl extends BaseAPI {
                 tradingPairId: request.tradingPairId,
                 strategyKey: request.strategyKey,
                 marginMode: request.marginMode,
-                selectedTradingPairIds: request.selectedTradingPairIds,
+                // No selectedTradingPairIds: cross scope is derived from trading, and
+                // the server ignores the deprecated field. Not sending it keeps a
+                // pre-upgrade caller's stale list from reaching the wire at all.
                 // JSON.stringify drops it when omitted; an explicit false MUST reach
                 // the wire or the server applies its Adjust Margin default and every
                 // funding-loop top-up converts into initial margin requirement.

package/dist/api/trading/api.d.ts

@@ -89,6 +89,8 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         reduceOnly?: boolean;
         postOnly?: boolean;
         clientOrderId?: string;
+        /** Generated 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>;
@@ -149,6 +151,8 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
         clientOrderId?: string;
+        /** Generated once per call when omitted. Supply the same key to retry a logical order within 24 hours. */
+        idempotencyKey?: string;
     }): Promise<CreateOrderResponse>;
     /**
      * Cancels an existing order.

package/dist/api/trading/api.js

@@ -121,6 +121,7 @@ export class TradingAPIImpl extends BaseAPI {
             reduceOnly: options?.reduceOnly,
             postOnly: options?.postOnly,
             clientOrderId: options?.clientOrderId,
+            idempotencyKey: options?.idempotencyKey === undefined ? crypto.randomUUID() : options.idempotencyKey,
             takeProfit: parentTpSlLegToRequest(options?.takeProfit),
             stopLoss: parentTpSlLegToRequest(options?.stopLoss),
         };
@@ -199,6 +200,7 @@ export class TradingAPIImpl extends BaseAPI {
             takeProfit: parentTpSlLegToRequest(options?.takeProfit),
             stopLoss: parentTpSlLegToRequest(options?.stopLoss),
             clientOrderId: options?.clientOrderId,
+            idempotencyKey: options?.idempotencyKey === undefined ? crypto.randomUUID() : options.idempotencyKey,
         };
         return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
             method: "POST",
@@ -387,6 +389,7 @@ export class TradingAPIImpl extends BaseAPI {
                 reduceOnly: order.reduceOnly,
                 postOnly: order.postOnly,
                 clientOrderId: order.clientOrderId,
+                idempotencyKey: order.idempotencyKey === undefined ? crypto.randomUUID() : order.idempotencyKey,
             })),
         };
         return this.makeAuthenticatedRequest(perpRoutes.orders.batchCreate(), {

package/dist/api/websocket/websocket.js

@@ -26,6 +26,33 @@ function readOptionalString(source, field) {
     }
     return value;
 }
+/**
+ * Read a field the server serializes as an explicit `null` when unset.
+ *
+ * Distinct from {@link readOptionalString}, which normalizes absent to
+ * `undefined`: a Rust `Option` WITHOUT `skip_serializing_if` always puts the key
+ * on the wire, so the declared type is `string | null` and `null` has to survive
+ * the parse rather than being laundered into `undefined`.
+ *
+ * An ABSENT key is a malformed frame, not "unset", and is rejected. The
+ * distinction matters because these readers feed the snapshot parsers, whose
+ * output is an authoritative complete baseline: reading a missing key as `null`
+ * would let a truncated row through as though the server had said the field was
+ * empty, and a consumer would clear real state on it. Rejecting withholds the
+ * whole snapshot instead, which is the delivery contract's failure mode.
+ */
+function readNullableString(source, field) {
+    if (!Object.hasOwn(source, field)) {
+        throw new Error(`Invalid WebSocket event: ${field} is missing`);
+    }
+    const value = source[field];
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== "string") {
+        throw new Error(`Invalid WebSocket event: ${field} must be a string`);
+    }
+    return value;
+}
 function readBoolean(source, field) {
     const value = source[field];
     if (typeof value !== "boolean") {
@@ -84,152 +111,183 @@ function readOptionalEnumValue(source, field) {
     const value = readOptionalString(source, field);
     return value === undefined || value.length === 0 ? undefined : value;
 }
+/**
+ * Parse a conditional order's terminal-state payload.
+ *
+ * Shared by the live event and the subscribe-time snapshot: a snapshot row IS
+ * this payload with no envelope around it, so parsing both through one function
+ * is what stops the baseline and the diffs describing state differently.
+ */
+function parseConditionalOrderEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid conditional order event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
+    return {
+        conditionalOrderId: readString(data, "conditionalOrderId"),
+        tradingPairId: readString(data, "tradingPairId"),
+        marginAccountId: readString(data, "marginAccountId"),
+        positionId: readOptionalString(data, "positionId"),
+        parentOrderId: readOptionalString(data, "parentOrderId"),
+        associationType: readOptionalEnumValue(data, "associationType"),
+        linkedGroupId: readOptionalString(data, "linkedGroupId"),
+        conditionType: readString(data, "conditionType"),
+        triggerSource: readString(data, "triggerSource"),
+        triggerPrice: readString(data, "triggerPrice"),
+        side: readString(data, "side"),
+        positionSide: readString(data, "positionSide"),
+        orderType: readString(data, "orderType"),
+        limitPrice: readOptionalString(data, "limitPrice"),
+        quantity: readOptionalString(data, "quantity"),
+        slippageToleranceBps: readOptionalNumber(data, "slippageToleranceBps"),
+        reduceOnly: readBoolean(data, "reduceOnly"),
+        timeInForce: readOptionalEnumValue(data, "timeInForce"),
+        state: readString(data, "state"),
+        triggeredOrderId: readOptionalString(data, "triggeredOrderId"),
+        triggeredAt: readOptionalString(data, "triggeredAt"),
+        activatedAt: readOptionalString(data, "activatedAt"),
+        cancelledAt: readOptionalString(data, "cancelledAt"),
+        expiresAt: readOptionalString(data, "expiresAt"),
+        failureReason: readOptionalString(data, "failureReason"),
+        // Free-form on the wire (the server field is a plain string), so it is
+        // passed through untouched rather than matched against a value list.
+        reason: readString(data, "reason"),
+        updatedAt: readString(data, "updatedAt"),
+        // Populated on the subscribe-time snapshot frame and absent on live
+        // updates (0XM-2440). Reading it optionally is what keeps the snapshot's
+        // value from being silently dropped before the subscriber.
+        version: readOptionalNumber(data, "version"),
+    };
+}
 function parseConditionalOrderEvent(rawData) {
     if (!isRecord(rawData)) {
         throw new Error("Invalid conditional order event: payload must be an object");
     }
-    if (!isRecord(rawData.data)) {
-        throw new Error("Invalid conditional order event: data must be an object");
-    }
-    const data = keysToCamelCase(rawData.data);
     return {
         // event_type is the event-class discriminator, validated strictly so a
         // mis-routed frame is rejected rather than parsed as a conditional order.
-        // The value fields below stay lenient — read as strings and cast, never
-        // checked against an allow-list — so an unexpected *value* never drops the
-        // whole update (0XM-2627). The parse throw is swallowed by the
+        // The value fields in the payload stay lenient — read as strings and cast,
+        // never checked against an allow-list — so an unexpected *value* never
+        // drops the whole update (0XM-2627). The parse throw is swallowed by the
         // message-handler catch, so a strict enum here means a silently lost frame
         // with nothing surfaced to the consumer.
         eventType: readEnum(rawData, "event_type", ["conditional_order_update"]),
         userId: readString(rawData, "user_id"),
-        data: {
-            conditionalOrderId: readString(data, "conditionalOrderId"),
-            tradingPairId: readString(data, "tradingPairId"),
-            marginAccountId: readString(data, "marginAccountId"),
-            positionId: readOptionalString(data, "positionId"),
-            parentOrderId: readOptionalString(data, "parentOrderId"),
-            associationType: readOptionalEnumValue(data, "associationType"),
-            linkedGroupId: readOptionalString(data, "linkedGroupId"),
-            conditionType: readString(data, "conditionType"),
-            triggerSource: readString(data, "triggerSource"),
-            triggerPrice: readString(data, "triggerPrice"),
-            side: readString(data, "side"),
-            positionSide: readString(data, "positionSide"),
-            orderType: readString(data, "orderType"),
-            limitPrice: readOptionalString(data, "limitPrice"),
-            quantity: readOptionalString(data, "quantity"),
-            slippageToleranceBps: readOptionalNumber(data, "slippageToleranceBps"),
-            reduceOnly: readBoolean(data, "reduceOnly"),
-            timeInForce: readOptionalEnumValue(data, "timeInForce"),
-            state: readString(data, "state"),
-            triggeredOrderId: readOptionalString(data, "triggeredOrderId"),
-            triggeredAt: readOptionalString(data, "triggeredAt"),
-            activatedAt: readOptionalString(data, "activatedAt"),
-            cancelledAt: readOptionalString(data, "cancelledAt"),
-            expiresAt: readOptionalString(data, "expiresAt"),
-            failureReason: readOptionalString(data, "failureReason"),
-            // Free-form on the wire (the server field is a plain string), so it is
-            // passed through untouched rather than matched against a value list.
-            reason: readString(data, "reason"),
-            updatedAt: readString(data, "updatedAt"),
-            // Populated on the subscribe-time snapshot frame and absent on live
-            // updates (0XM-2440). Reading it optionally is what keeps the
-            // snapshot's value from being silently dropped before the subscriber.
-            version: readOptionalNumber(data, "version"),
-        },
+        data: parseConditionalOrderEventData(rawData.data),
+    };
+}
+/**
+ * Parse a position's terminal-state payload. Shared by the live event and the
+ * subscribe-time snapshot (see {@link parseConditionalOrderEventData}).
+ */
+function parsePositionEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid position event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
+    return {
+        positionId: readString(data, "positionId"),
+        marginAccountId: readString(data, "marginAccountId"),
+        tradingPairId: readString(data, "tradingPairId"),
+        side: readString(data, "side"),
+        status: readString(data, "status"),
+        size: readString(data, "size"),
+        entryPrice: readString(data, "entryPrice"),
+        markPrice: readOptionalString(data, "markPrice"),
+        unrealizedPnl: readOptionalString(data, "unrealizedPnl"),
+        liquidationPrice: readOptionalString(data, "liquidationPrice"),
+        isolatedMargin: readString(data, "isolatedMargin"),
+        leverage: readString(data, "leverage"),
+        tradeId: readOptionalString(data, "tradeId"),
+        orderId: readOptionalString(data, "orderId"),
+        reason: readString(data, "reason"),
+        updatedAt: readString(data, "updatedAt"),
     };
 }
 function parsePositionEvent(rawData) {
     if (!isRecord(rawData)) {
         throw new Error("Invalid position event: payload must be an object");
     }
-    if (!isRecord(rawData.data)) {
-        throw new Error("Invalid position event: data must be an object");
-    }
-    const data = keysToCamelCase(rawData.data);
     return {
         // event_type is the event-class discriminator, validated strictly so a
         // mis-routed frame is rejected rather than parsed as a position. The value
-        // fields below (side/status/reason) stay lenient so an unexpected *value*
-        // never drops a risk-critical update.
+        // fields in the payload (side/status/reason) stay lenient so an unexpected
+        // *value* never drops a risk-critical update.
         eventType: readEnum(rawData, "event_type", ["position_update"]),
         userId: readString(rawData, "user_id"),
-        data: {
-            positionId: readString(data, "positionId"),
-            marginAccountId: readString(data, "marginAccountId"),
-            tradingPairId: readString(data, "tradingPairId"),
-            side: readString(data, "side"),
-            status: readString(data, "status"),
-            size: readString(data, "size"),
-            entryPrice: readString(data, "entryPrice"),
-            markPrice: readOptionalString(data, "markPrice"),
-            unrealizedPnl: readOptionalString(data, "unrealizedPnl"),
-            liquidationPrice: readOptionalString(data, "liquidationPrice"),
-            isolatedMargin: readString(data, "isolatedMargin"),
-            leverage: readString(data, "leverage"),
-            tradeId: readOptionalString(data, "tradeId"),
-            orderId: readOptionalString(data, "orderId"),
-            reason: readString(data, "reason"),
-            updatedAt: readString(data, "updatedAt"),
-        },
+        data: parsePositionEventData(rawData.data),
+    };
+}
+/**
+ * Parse a liquidation alert's payload. Shared by the live event and the
+ * subscribe-time snapshot (see {@link parseConditionalOrderEventData}).
+ */
+function parseLiquidationEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid liquidation event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
+    return {
+        liquidationId: readString(data, "liquidationId"),
+        marginAccountId: readString(data, "marginAccountId"),
+        positionId: readOptionalString(data, "positionId"),
+        tradingPairId: readOptionalString(data, "tradingPairId"),
+        status: readString(data, "status"),
+        accountState: readString(data, "accountState"),
+        liquidationPrice: readOptionalString(data, "liquidationPrice"),
+        markPrice: readOptionalString(data, "markPrice"),
+        estimatedShortfall: readString(data, "estimatedShortfall"),
+        message: readString(data, "message"),
+        triggeredAt: readString(data, "triggeredAt"),
     };
 }
 function parseLiquidationEvent(rawData) {
     if (!isRecord(rawData)) {
         throw new Error("Invalid liquidation event: payload must be an object");
     }
-    if (!isRecord(rawData.data)) {
-        throw new Error("Invalid liquidation event: data must be an object");
-    }
-    const data = keysToCamelCase(rawData.data);
     return {
         // event_type is the event-class discriminator, validated strictly so a
         // mis-routed frame is rejected rather than parsed as a liquidation. The
-        // free-form value fields below (status/accountState) stay lenient so an
-        // unexpected *value* never drops a risk-critical alert.
+        // free-form value fields in the payload (status/accountState) stay lenient
+        // so an unexpected *value* never drops a risk-critical alert.
         eventType: readEnum(rawData, "event_type", ["liquidation_alert"]),
         userId: readString(rawData, "user_id"),
-        data: {
-            liquidationId: readString(data, "liquidationId"),
-            marginAccountId: readString(data, "marginAccountId"),
-            positionId: readOptionalString(data, "positionId"),
-            tradingPairId: readOptionalString(data, "tradingPairId"),
-            status: readString(data, "status"),
-            accountState: readString(data, "accountState"),
-            liquidationPrice: readOptionalString(data, "liquidationPrice"),
-            markPrice: readOptionalString(data, "markPrice"),
-            estimatedShortfall: readString(data, "estimatedShortfall"),
-            message: readString(data, "message"),
-            triggeredAt: readString(data, "triggeredAt"),
-        },
+        data: parseLiquidationEventData(rawData.data),
+    };
+}
+/**
+ * Parse an account's margin-health payload. Shared by the live event and the
+ * subscribe-time snapshot (see {@link parseConditionalOrderEventData}).
+ */
+function parseAccountEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid account event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
+    return {
+        marginAccountId: readString(data, "marginAccountId"),
+        // Monotonic per-account publish counter (0XM-2498): a plain JSON number on
+        // the wire, used to order/dedupe frames across reconnect races. Must be a
+        // non-negative safe integer — anything else is a malformed frame.
+        sequence: readSequence(data, "sequence"),
+        equity: readString(data, "equity"),
+        collateral: readString(data, "collateral"),
+        freeCollateral: readString(data, "freeCollateral"),
+        marginRatio: readString(data, "marginRatio"),
+        maintenanceRequirement: readString(data, "maintenanceRequirement"),
+        updatedAt: readString(data, "updatedAt"),
     };
 }
 function parseAccountEvent(rawData) {
     if (!isRecord(rawData)) {
         throw new Error("Invalid account event: payload must be an object");
     }
-    if (!isRecord(rawData.data)) {
-        throw new Error("Invalid account event: data must be an object");
-    }
-    const data = keysToCamelCase(rawData.data);
     return {
         // event_type is the event-class discriminator, validated strictly so a
         // mis-routed frame is rejected rather than parsed as an account update.
         eventType: readEnum(rawData, "event_type", ["account_update"]),
         userId: readString(rawData, "user_id"),
-        data: {
-            marginAccountId: readString(data, "marginAccountId"),
-            // Monotonic per-account publish counter (0XM-2498): a plain JSON number on
-            // the wire, used to order/dedupe frames across reconnect races. Must be a
-            // non-negative safe integer — anything else is a malformed frame.
-            sequence: readSequence(data, "sequence"),
-            equity: readString(data, "equity"),
-            collateral: readString(data, "collateral"),
-            freeCollateral: readString(data, "freeCollateral"),
-            marginRatio: readString(data, "marginRatio"),
-            maintenanceRequirement: readString(data, "maintenanceRequirement"),
-            updatedAt: readString(data, "updatedAt"),
-        },
+        data: parseAccountEventData(rawData.data),
     };
 }
 function parseMarketStatsData(raw) {
@@ -350,12 +408,9 @@ function parseInstrumentEvent(rawData) {
     };
 }
 /**
- * Parse a `twap_orders` channel frame into a typed event. Only the envelope
- * and the snapshot's identity/state fields are validated strictly — the rest
- * of the TwapOrder snapshot is passed through camelCased, so additive server
- * fields never break older clients. The server serializes absent optional
- * fields as explicit `null`; those are dropped so the parsed snapshot matches
- * the optional (`?:`) fields of `TwapOrderEventData`.
+ * Parse a `twap_orders` channel frame into a typed event. The envelope is
+ * validated strictly here; the payload's own leniency contract lives in
+ * {@link parseTwapOrderEventData}.
  */
 function parseTwapOrderEvent(rawData) {
     if (!isRecord(rawData)) {
@@ -372,7 +427,27 @@ function parseTwapOrderEvent(rawData) {
     if (typeof userId !== "string" || userId.length === 0) {
         throw new Error("Invalid TWAP order event: user_id must be a non-empty string");
     }
-    const data = keysToCamelCase(rawData.data);
+    return {
+        eventType: "twap_order_update",
+        userId,
+        data: parseTwapOrderEventData(rawData.data),
+    };
+}
+/**
+ * Parse a TWAP parent order's terminal-state payload. Shared by the live event
+ * and the subscribe-time snapshot (see {@link parseConditionalOrderEventData}).
+ *
+ * Only the identity and state fields are validated; the rest of the snapshot is
+ * passed through camelCased, so additive server fields never break older
+ * clients. The server serializes absent optional fields as explicit `null`;
+ * those are dropped so the parsed payload matches the optional (`?:`) fields of
+ * `TwapOrderEventData`.
+ */
+function parseTwapOrderEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid TWAP order event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
     for (const key of Object.keys(data)) {
         if (data[key] === null) {
             delete data[key];
@@ -393,10 +468,139 @@ function parseTwapOrderEvent(rawData) {
     if (typeof state !== "string" || state.length === 0) {
         throw new Error("Invalid TWAP order event: state must be a non-empty string");
     }
+    return data;
+}
+/**
+ * Parse a user balance payload. Shared by the live event and the subscribe-time
+ * snapshot (see {@link parseConditionalOrderEventData}).
+ *
+ * `tokenSymbol` and `referenceId` are read as nullable rather than optional:
+ * the server sends both keys always, carrying `null` when unset, and
+ * `UserBalanceEventData` declares them `string | null`.
+ */
+function parseUserBalanceEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid balance event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
     return {
-        eventType: "twap_order_update",
-        userId,
-        data: data,
+        tokenAddress: readString(data, "tokenAddress"),
+        tokenSymbol: readNullableString(data, "tokenSymbol"),
+        available: readString(data, "available"),
+        availableRaw: readString(data, "availableRaw"),
+        locked: readString(data, "locked"),
+        lockedRaw: readString(data, "lockedRaw"),
+        total: readString(data, "total"),
+        totalRaw: readString(data, "totalRaw"),
+        // Free-form on the wire and read leniently: a snapshot row carries the
+        // `snapshot` literal, a live frame the mutation cause, and a reason added
+        // server-side after this SDK shipped must not drop the row (0XM-2627).
+        reason: readString(data, "reason"),
+        referenceId: readNullableString(data, "referenceId"),
+        updatedAt: readString(data, "updatedAt"),
+    };
+}
+/**
+ * Parse one resting order from an `orders` channel snapshot.
+ *
+ * This is the one snapshot row that is NOT the channel's live payload: an order
+ * event describes a change, a snapshot row describes resting state, so the row
+ * carries `status` and the cumulative fill totals and carries none of the
+ * change-only fill metadata.
+ *
+ * The optional fields are read as nullable, not optional: they are Rust
+ * `Option`s serialized without `skip_serializing_if`, so the key is always
+ * present carrying `null`. `clientOrderId` is the one field the server omits
+ * outright, so it is the one read as optional.
+ */
+function parseOrderSnapshotItem(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid order snapshot: item must be an object");
+    }
+    const item = keysToCamelCase(raw);
+    // Read once: this is the only genuinely-omitted field, and it is spread in
+    // conditionally so an absent one stays absent rather than becoming
+    // `clientOrderId: undefined`, which a structural comparison would see.
+    const clientOrderId = readOptionalString(item, "clientOrderId");
+    const version = readOptionalNumber(item, "version");
+    return {
+        orderId: readString(item, "orderId"),
+        userId: readString(item, "userId"),
+        applicationId: readString(item, "applicationId"),
+        tradingPairId: readString(item, "tradingPairId"),
+        tradingPair: readString(item, "tradingPair"),
+        // Value fields are read as plain strings and cast, never matched against an
+        // allow-list: an unrecognized value must not drop the row, or a consumer
+        // seeding from the baseline would silently lose an order that is really
+        // resting on the book (0XM-2627).
+        tradingMode: readString(item, "tradingMode"),
+        side: readString(item, "side"),
+        orderType: readString(item, "orderType"),
+        price: readNullableString(item, "price"),
+        quantity: readString(item, "quantity"),
+        quantityRaw: readString(item, "quantityRaw"),
+        filledQuantity: readString(item, "filledQuantity"),
+        filledQuantityRaw: readString(item, "filledQuantityRaw"),
+        remainingQuantity: readNullableString(item, "remainingQuantity"),
+        remainingQuantityRaw: readNullableString(item, "remainingQuantityRaw"),
+        status: readString(item, "status"),
+        timeInForce: readNullableString(item, "timeInForce"),
+        averageFillPrice: readNullableString(item, "averageFillPrice"),
+        createdAt: readString(item, "createdAt"),
+        updatedAt: readNullableString(item, "updatedAt"),
+        marginAccountId: readNullableString(item, "marginAccountId"),
+        positionId: readNullableString(item, "positionId"),
+        leverage: readNullableString(item, "leverage"),
+        reduceOnly: readBoolean(item, "reduceOnly"),
+        ...(clientOrderId === undefined ? {} : { clientOrderId }),
+        // Spread in conditionally for the same reason as `clientOrderId`: the
+        // server omits the key when unknown, and absent must stay absent rather
+        // than becoming `version: undefined` — a resync compares this value, and
+        // absent means unknown, never zero (0XM-2440).
+        ...(version === undefined ? {} : { version }),
+    };
+}
+/**
+ * Wrap a caller's `onSnapshot` in the internal snapshot-frame handler.
+ *
+ * The frame's `data` is the channel's COMPLETE current state as a flat array,
+ * and that completeness is the whole contract: a consumer is expected to
+ * replace state from it, so absence from the array means the entity is gone.
+ *
+ * Delivery is therefore all-or-nothing. If the payload is not an array, or any
+ * single row fails to parse, NOTHING is delivered.
+ *
+ * Skipping just the unreadable row and delivering the rest would be worse than
+ * delivering nothing, because the array would still be presented as complete: a
+ * consumer would drop the entity that row described — zero its balance, remove
+ * its market, cancel its order in the UI — on the strength of an omission the
+ * SDK itself created. Nor is that self-correcting. A resting order or an
+ * unchanged market has no later diff to repair it, so the deletion would stand
+ * for the life of the connection.
+ *
+ * Withholding the frame instead leaves the consumer on whatever baseline it
+ * already had, and the channel keeps streaming live events over it. That is a
+ * strictly smaller loss, and it is the same all-or-nothing rule this channel's
+ * original `instrument` snapshot already applied.
+ *
+ * `[]` is a legitimate baseline, not a failure, and is always delivered:
+ * "nothing is open" is exactly the information a consumer needs to clear stale
+ * state after a reconnect.
+ */
+function snapshotFrameHandler(channel, parseItem, onSnapshot) {
+    return (rawData) => {
+        try {
+            if (!Array.isArray(rawData)) {
+                throw new Error(`Invalid ${channel} snapshot: data must be an array`);
+            }
+            // Parsed fully before anything is handed over, so a failure part-way
+            // through cannot deliver a truncated baseline.
+            const items = rawData.map(parseItem);
+            onSnapshot(items);
+        }
+        catch (err) {
+            console.error(`WebSocket: Error processing ${channel} snapshot`, err);
+        }
     };
 }
 /**
@@ -643,10 +847,9 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                     sendAuthenticate();
                     resubscribeAll();
                     options.onStatusChange?.("connected");
-                    // Resync-join order: resume the live stream first (auth +
-                    // subscribe above), then tell the app to refetch snapshots and
-                    // reconcile by (id, updatedAt) — events racing the snapshot are
-                    // newer than the rows they duplicate.
+                    // Send auth/subscribe requests before asking the application to
+                    // reconcile. This callback does not wait for acknowledgements or
+                    // snapshots, and the SDK does not perform REST recovery itself.
                     if (pendingResyncCode !== null) {
                         const code = pendingResyncCode;
                         pendingResyncCode = null;
@@ -759,7 +962,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         };
     };
     // --- Channel-specific subscription methods ---
-    const subscribeOrders = (tradingPairId, tradingMode, handler) => {
+    const subscribeOrders = (tradingPairId, tradingMode, handler, onSnapshot) => {
         const channel = `orders:${tradingPairId}:${tradingMode}`;
         return subscribe(channel, (rawData) => {
             try {
@@ -775,7 +978,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing order event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("orders", parseOrderSnapshotItem, onSnapshot));
     };
     const subscribeOrderbook = (tradingPairId, tradingMode, magnitude, quotationMode, handler) => {
         if (!tradingPairId || !tradingMode || magnitude === undefined || !quotationMode) {
@@ -957,7 +1160,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * Subscribe to authenticated user's order events (all trading pairs)
      * Requires authentication - user is identified from the signed session-key handshake
      */
-    const subscribeUserOrders = (handler) => {
+    const subscribeUserOrders = (handler, onSnapshot) => {
         // User is identified from the authenticated session, so channel is just "orders"
         const channel = "orders";
         return subscribe(channel, (rawData) => {
@@ -974,44 +1177,33 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing user order event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("orders", parseOrderSnapshotItem, onSnapshot));
     };
     /**
      * Subscribe to authenticated user's balance events
      * Requires authentication - user is identified from the signed session-key handshake
      */
-    const subscribeBalances = (handler) => {
+    const subscribeBalances = (handler, onSnapshot) => {
         // User is identified from the authenticated session, so channel is just "balances"
         const channel = "balances";
         return subscribe(channel, (rawData) => {
             try {
-                const data = rawData;
-                const balanceData = data.data;
+                if (!isRecord(rawData)) {
+                    throw new Error("Invalid balance event: payload must be an object");
+                }
                 const event = {
                     eventType: "balance_update",
-                    userId: data.user_id,
-                    data: {
-                        tokenAddress: balanceData.token_address,
-                        tokenSymbol: balanceData.token_symbol,
-                        available: balanceData.available,
-                        availableRaw: balanceData.available_raw,
-                        locked: balanceData.locked,
-                        lockedRaw: balanceData.locked_raw,
-                        total: balanceData.total,
-                        totalRaw: balanceData.total_raw,
-                        reason: balanceData.reason,
-                        referenceId: balanceData.reference_id,
-                        updatedAt: balanceData.updated_at,
-                    },
+                    userId: readString(rawData, "user_id"),
+                    data: parseUserBalanceEventData(rawData.data),
                 };
                 handler(event);
             }
             catch (err) {
                 console.error("WebSocket: Error processing balance event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("balances", parseUserBalanceEventData, onSnapshot));
     };
-    const subscribeConditionalOrders = (handler, tradingPairId) => {
+    const subscribeConditionalOrders = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
             throw new Error("conditionalOrders subscription requires a handler");
         }
@@ -1026,9 +1218,9 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing conditional order event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("conditional orders", parseConditionalOrderEventData, onSnapshot));
     };
-    const subscribeTwapOrders = (handler, tradingPairId) => {
+    const subscribeTwapOrders = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
             throw new Error("twapOrders subscription requires a handler");
         }
@@ -1043,16 +1235,16 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing TWAP order event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("TWAP orders", parseTwapOrderEventData, onSnapshot));
     };
     /**
      * Subscribe to authenticated user's position updates.
      * Requires authentication - user is identified from the signed session-key
      * handshake. Omit `tradingPairId` for all pairs, or pass one to filter.
-     * Lag policy is Conflate: a lagging subscriber is fast-forwarded, no gap
-     * signal.
+     * Detected broadcast lag closes the connection with 1013; reconcile
+     * missed keys and terminal updates on reconnect.
      */
-    const subscribePositions = (handler, tradingPairId) => {
+    const subscribePositions = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
             throw new Error("positions subscription requires a handler");
         }
@@ -1067,7 +1259,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing position event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("positions", parsePositionEventData, onSnapshot));
     };
     /**
      * Subscribe to authenticated user's liquidation alerts.
@@ -1076,7 +1268,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * Lag policy is Disconnect: a subscriber that falls behind is closed with
      * `1013`; resync by refetching a snapshot (no wire sequence number).
      */
-    const subscribeLiquidations = (handler, tradingPairId) => {
+    const subscribeLiquidations = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
             throw new Error("liquidations subscription requires a handler");
         }
@@ -1091,17 +1283,17 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing liquidation event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("liquidations", parseLiquidationEventData, onSnapshot));
     };
     /**
      * Subscribe to the authenticated user's account-level margin health updates
      * (equity, collateral, free collateral, margin ratio, maintenance
      * requirement). Requires authentication - the user is identified from the
-     * signed session-key handshake. Lag policy is Conflate: a lagging subscriber
-     * is fast-forwarded, no gap signal. Each frame is a terminal-state snapshot
+     * signed session-key handshake. Detected broadcast lag closes the connection
+     * with 1013; reconnect and reconcile missed state. Each frame is a terminal-state snapshot
      * per margin account, not an additive delta.
      */
-    const subscribeAccount = (handler) => {
+    const subscribeAccount = (handler, onSnapshot) => {
         if (!handler) {
             throw new Error("account subscription requires a handler");
         }
@@ -1112,7 +1304,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing account event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("account", parseAccountEventData, onSnapshot));
     };
     /**
      * Subscribe to market lifecycle + configuration changes (public): listings,
@@ -1124,10 +1316,10 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * of the current active-pair list arrives before the live diffs; a
      * subscriber joining a channel this client already holds is replayed the
      * current baseline from a local cache instead (the server snapshots only
-     * genuinely new wire subscriptions). Lag policy is Conflate: a lagging
-     * subscriber is fast-forwarded, no gap signal.
+     * genuinely new wire subscriptions). Detected broadcast lag closes the connection
+     * with 1013; a new wire subscription provides a fresh baseline.
      */
-    const subscribeInstruments = (handler, tradingPairId) => {
+    const subscribeInstruments = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
             throw new Error("instruments subscription requires a handler");
         }
@@ -1166,37 +1358,82 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         }, 
         // The subscribe-time baseline arrives as one Snapshot frame whose data is
         // a flat InstrumentEventData[] (a `listing` per active market, no
-        // per-item envelope). Fan it out as one event per market so the handler
-        // sees the same shape for baseline and live frames.
-        (rawData) => {
-            try {
-                if (!Array.isArray(rawData)) {
-                    throw new Error("Invalid instrument snapshot: data must be an array");
-                }
-                const events = rawData.map(parseInstrumentEventData).map((item) => ({ tradingPairId: item.tradingPairId, data: item }));
-                // A snapshot is the authoritative active-market set: replace the
-                // channel's cache wholesale rather than upserting, so markets absent
-                // from it (delisted while disconnected) don't linger.
-                instrumentBaseline.set(channel, new Map(events.map((event) => [event.tradingPairId, event])));
-                for (const event of events) {
-                    handler(event);
-                }
+        // per-item envelope).
+        //
+        // Where it goes depends on whether the caller opted in. With
+        // `onSnapshot`, the rows are handed over as one array and the event
+        // handler sees none of them — that array is the snapshot BOUNDARY a
+        // consumer needs to replace its market set wholesale after a reconnect,
+        // which per-market events cannot express. Without it, the rows are fanned
+        // out as one synthetic event per market, which is how this channel has
+        // always delivered its baseline; changing that for callers who never
+        // asked would be a silent behaviour break.
+        //
+        // Either way the local cache is replaced wholesale rather than upserted,
+        // so markets absent from the snapshot (delisted while disconnected) do
+        // not linger.
+        snapshotFrameHandler("instrument", parseInstrumentEventData, (items) => {
+            const events = items.map((item) => ({ tradingPairId: item.tradingPairId, data: item }));
+            instrumentBaseline.set(channel, new Map(events.map((event) => [event.tradingPairId, event])));
+            if (onSnapshot) {
+                onSnapshot(items);
+                return;
             }
-            catch (err) {
-                console.error("WebSocket: Error processing instrument snapshot", err);
+            for (const event of events) {
+                handler(event);
             }
-        });
+        }));
         // Replay only while the socket is open: during abnormal-close backoff the
         // handlers and cache survive but the state is pre-outage — the reconnect's
         // resubscribe clears it and a fresh authoritative snapshot follows, so a
         // backoff-time subscriber must wait for that instead.
         if (isLateSubscriber && ws?.readyState === WebSocket.OPEN) {
-            const cached = instrumentBaseline.get(channel);
-            if (cached && cached.size > 0) {
-                const replay = [...cached.values()];
+            // Presence, not size. An entry exists only once a snapshot has been
+            // received for the channel, so an EMPTY one is a genuine "no active
+            // markets" baseline rather than "nothing known yet" — and under this
+            // API empty is authoritative information a late subscriber needs in
+            // order to clear stale markets.
+            if (instrumentBaseline.has(channel)) {
                 queueMicrotask(() => {
                     if (unsubscribed)
                         return;
+                    // Read INSIDE the microtask, and re-check the socket. This
+                    // subscriber is already registered by now, so a live frame landing
+                    // first would update the cache and reach `handler` directly — a
+                    // snapshot array captured before the microtask would then arrive
+                    // afterwards carrying older state, and a consumer that replaces its
+                    // market map from it would go backwards. A `disconnect()` in the
+                    // same window drops the cache outright, and delivering a baseline
+                    // after that would be inventing one.
+                    const cached = instrumentBaseline.get(channel);
+                    if (!cached || ws?.readyState !== WebSocket.OPEN)
+                        return;
+                    const replay = [...cached.values()];
+                    // The replay IS this subscriber's baseline — it stands in for the
+                    // wire snapshot the suppressed Subscribe never triggered — so it
+                    // follows the same delivery contract: one array to `onSnapshot`
+                    // when opted in, per-market events otherwise.
+                    //
+                    // The two forms carry deliberately different sets. The ARRAY is
+                    // filtered to active markets, because that is what a real snapshot
+                    // is — the server enumerates active pairs, while this cache also
+                    // holds the delistings it has seen live — and a consumer replaces
+                    // its market set from the array, so a delisted row there would
+                    // resurrect a market that is gone. The per-market EVENTS are not
+                    // filtered: a delisting is a legitimate event, it is what tells a
+                    // legacy subscriber the market went inactive, and dropping it would
+                    // change a caller that never opted into any of this.
+                    if (onSnapshot) {
+                        try {
+                            onSnapshot(replay.filter((event) => event.data.isActive).map((event) => event.data));
+                        }
+                        catch (err) {
+                            console.error("WebSocket: Error processing instrument baseline replay", err);
+                        }
+                        return;
+                    }
+                    // Contained per event, not per replay: a handler that throws on one
+                    // market must not cost the subscriber every market after it.
                     for (const event of replay) {
                         try {
                             handler(event);
@@ -1223,7 +1460,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * frame carries the market's full current stats as a terminal-state snapshot.
      * Use {@link subscribeMarketStatsAll} for the all-markets summary instead.
      */
-    const subscribeMarketStats = (tradingPairId, handler) => {
+    const subscribeMarketStats = (tradingPairId, handler, onSnapshot) => {
         if (!tradingPairId) {
             throw new Error("marketStats subscription requires a tradingPairId");
         }
@@ -1237,13 +1474,13 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing market stats event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("market stats", parseMarketStatsData, onSnapshot));
     };
     /**
      * Subscribe to the all-markets statistics summary (public): one summary row
      * per market in a single frame per push.
      */
-    const subscribeMarketStatsAll = (handler) => {
+    const subscribeMarketStatsAll = (handler, onSnapshot) => {
         if (!handler) {
             throw new Error("marketStatsAll subscription requires a handler");
         }
@@ -1261,7 +1498,12 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing market stats all event", err);
             }
-        });
+        }, 
+        // The per-market channel needs no such guard: snapshot frames are routed
+        // by exact channel, so `market_stats:<pair>` never reaches the bare
+        // `market_stats` subscription's snapshot handler the way its live frames
+        // reach the event handler.
+        onSnapshot && snapshotFrameHandler("all-markets stats", parseMarketStatsSummary, onSnapshot));
     };
     return {
         connect,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.51",
+	"version": "1.0.54",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -19,8 +19,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.51",
-		"@0xmonaco/types": "1.0.51",
+		"@0xmonaco/contracts": "1.0.54",
+		"@0xmonaco/types": "1.0.54",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"