@0xmonaco/types 1.1.5 → 1.1.6

package/dist/validation/trading.js

@@ -171,6 +171,26 @@ export const TrailingStopLegSchema = z
 export const ParentTrailingStopLegSchema = TrailingStopLegSchema;
 const hasParentTpSl = (options) => options?.takeProfit !== undefined || options?.stopLoss !== undefined || options?.trailingStop !== undefined;
 const legacyPositionSideMatchesOrderSide = (side, positionSide) => positionSide === undefined || (positionSide !== "NONE" && ((side === "BUY" && positionSide === "LONG") || (side === "SELL" && positionSide === "SHORT")));
+/**
+ * An order's `strategyKey` names one of the caller's margin accounts by its
+ * sub-account key (`default` is the default margin account), as
+ * `marginAccountId` names it by id; a copy trading account's `copy:` key names
+ * it too, for the reduce-only close a copy account admits. The server refuses
+ * a key outside the sub-account key alphabet and a key naming none of the
+ * caller's open sub-accounts.
+ */
+export const OrderStrategyKeySchema = z
+    .string()
+    .trim()
+    .min(1, "strategyKey cannot be empty")
+    .max(64, "strategyKey must be a sub-account key: letters, digits, _ - . :, up to 64 characters")
+    .regex(/^[A-Za-z0-9_.:-]+$/, "strategyKey must be a sub-account key: letters, digits, _ - . :, up to 64 characters");
+/**
+ * A risk-bucket transfer's or preview's `strategyKey`: the order rule, and a
+ * reserved `copy:` key is refused (a copy account's risk buckets are funded
+ * by its follow only).
+ */
+export const StrategyKeySchema = OrderStrategyKeySchema.refine((key) => !key.toLowerCase().startsWith("copy:"), "strategy keys starting with copy: are reserved");
 /**
  * Place Limit Order validation schema
  */
@@ -196,7 +216,7 @@ export const PlaceLimitOrderSchema = z
         marginMode: MarginModeSchema.optional(),
         riskBucketId: UUIDSchema.optional(),
         riskBucketCollateral: PositiveDecimalStringSchema.optional(),
-        strategyKey: z.string().min(1).max(128).optional(),
+        strategyKey: OrderStrategyKeySchema.optional(),
         positionSide: PositionSideSchema.optional(),
         leverage: PositiveDecimalStringSchema.optional(),
         reduceOnly: z.boolean().optional(),
@@ -216,7 +236,7 @@ export const PlaceLimitOrderSchema = z
     message: "leverage is required for normal MARGIN orders",
     path: ["options", "leverage"],
 })
-    .refine((data) => !hasParentTpSl(data.options) || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => !hasParentTpSl(data.options) || data.options?.tradingMode !== "SPOT", {
     message: "takeProfit/stopLoss/trailingStop are only supported for MARGIN orders",
     path: ["options"],
 })
@@ -224,17 +244,13 @@ export const PlaceLimitOrderSchema = z
     message: "takeProfit/stopLoss/trailingStop cannot be attached to reduce-only orders",
     path: ["options"],
 })
-    .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.tradingMode !== "SPOT", {
     message: "riskBucketCollateral is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
 })
-    .refine((data) => data.options?.marginMode === undefined || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => data.options?.marginMode === undefined || data.options?.tradingMode !== "SPOT", {
     message: "marginMode is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
-})
-    .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.marginAccountId !== undefined, {
-    message: "marginAccountId is required for CROSS margin orders",
-    path: ["options", "marginAccountId"],
 })
     .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.riskBucketId === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketId",
@@ -243,10 +259,6 @@ export const PlaceLimitOrderSchema = z
     .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.riskBucketCollateral === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketCollateral",
     path: ["options", "riskBucketCollateral"],
-})
-    .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.strategyKey === undefined, {
-    message: "marginMode CROSS cannot be combined with strategyKey",
-    path: ["options", "strategyKey"],
 })
     .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.riskBucketId === undefined, {
     message: "riskBucketCollateral creates a new risk bucket and cannot be combined with riskBucketId",
@@ -277,7 +289,7 @@ export const PlaceMarketOrderSchema = z
         marginMode: MarginModeSchema.optional(),
         riskBucketId: UUIDSchema.optional(),
         riskBucketCollateral: PositiveDecimalStringSchema.optional(),
-        strategyKey: z.string().min(1).max(128).optional(),
+        strategyKey: OrderStrategyKeySchema.optional(),
         positionSide: PositionSideSchema.optional(),
         leverage: PositiveDecimalStringSchema.optional(),
         reduceOnly: z.boolean().optional(),
@@ -296,7 +308,7 @@ export const PlaceMarketOrderSchema = z
     message: "leverage is required for normal MARGIN orders",
     path: ["options", "leverage"],
 })
-    .refine((data) => !hasParentTpSl(data.options) || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => !hasParentTpSl(data.options) || data.options?.tradingMode !== "SPOT", {
     message: "takeProfit/stopLoss/trailingStop are only supported for MARGIN orders",
     path: ["options"],
 })
@@ -304,17 +316,13 @@ export const PlaceMarketOrderSchema = z
     message: "takeProfit/stopLoss/trailingStop cannot be attached to reduce-only orders",
     path: ["options"],
 })
-    .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.tradingMode !== "SPOT", {
     message: "riskBucketCollateral is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
 })
-    .refine((data) => data.options?.marginMode === undefined || data.options?.tradingMode === "MARGIN", {
+    .refine((data) => data.options?.marginMode === undefined || data.options?.tradingMode !== "SPOT", {
     message: "marginMode is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
-})
-    .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.marginAccountId !== undefined, {
-    message: "marginAccountId is required for CROSS margin orders",
-    path: ["options", "marginAccountId"],
 })
     .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.riskBucketId === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketId",
@@ -323,10 +331,6 @@ export const PlaceMarketOrderSchema = z
     .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.riskBucketCollateral === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketCollateral",
     path: ["options", "riskBucketCollateral"],
-})
-    .refine((data) => data.options?.marginMode !== "CROSS" || data.options?.strategyKey === undefined, {
-    message: "marginMode CROSS cannot be combined with strategyKey",
-    path: ["options", "strategyKey"],
 })
     .refine((data) => data.options?.riskBucketCollateral === undefined || data.options?.riskBucketId === undefined, {
     message: "riskBucketCollateral creates a new risk bucket and cannot be combined with riskBucketId",
@@ -466,7 +470,7 @@ export const CreateTwapOrderSchema = z
         riskBucketId: UUIDSchema.optional(),
         marginMode: MarginModeSchema.optional(),
         leverage: PositiveDecimalStringSchema.optional(),
-        strategyKey: z.string().min(1).max(128).optional(),
+        strategyKey: OrderStrategyKeySchema.optional(),
         useMasterBalance: z.boolean().optional(),
         clientTwapId: z.string().min(1).max(36, "clientTwapId cannot exceed 36 characters").optional(),
         triggerPrice: PositiveDecimalStringSchema.optional(),
@@ -482,21 +486,17 @@ export const CreateTwapOrderSchema = z
     message: "startTime is only valid together with endTime",
     path: ["options", "startTime"],
 })
-    .refine((data) => data.options.marginMode === undefined || data.options.tradingMode === "MARGIN", {
+    .refine((data) => data.options.marginMode === undefined || data.options.tradingMode !== "SPOT", {
     message: "marginMode is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
 })
-    .refine((data) => data.options.riskBucketId === undefined || data.options.tradingMode === "MARGIN", {
+    .refine((data) => data.options.riskBucketId === undefined || data.options.tradingMode !== "SPOT", {
     message: "riskBucketId is only supported for MARGIN orders",
     path: ["options", "tradingMode"],
 })
     .refine((data) => data.options.marginMode !== "CROSS" || data.options.riskBucketId === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketId",
     path: ["options", "riskBucketId"],
-})
-    .refine((data) => data.options.marginMode !== "CROSS" || data.options.strategyKey === undefined, {
-    message: "marginMode CROSS cannot be combined with strategyKey",
-    path: ["options", "strategyKey"],
 })
     .refine((data) => data.options.tradingMode !== "MARGIN" || data.options.reduceOnly === true || data.options.leverage !== undefined, {
     message: "leverage is required for normal MARGIN TWAP orders",
@@ -614,7 +614,7 @@ export const BatchCreateOrderItemSchema = z
     marginMode: MarginModeSchema.optional(),
     riskBucketId: UUIDSchema.optional(),
     riskBucketCollateral: PositiveDecimalStringSchema.optional(),
-    strategyKey: z.string().min(1).max(128).optional(),
+    strategyKey: OrderStrategyKeySchema.optional(),
     positionSide: PositionSideSchema.optional(),
     leverage: PositiveDecimalStringSchema.optional(),
     reduceOnly: z.boolean().optional(),
@@ -641,17 +641,13 @@ export const BatchCreateOrderItemSchema = z
     message: "postOnly cannot be combined with IOC/FOK time in force",
     path: ["postOnly"],
 })
-    .refine((data) => data.riskBucketCollateral === undefined || data.tradingMode === "MARGIN", {
+    .refine((data) => data.riskBucketCollateral === undefined || data.tradingMode !== "SPOT", {
     message: "riskBucketCollateral is only supported for MARGIN orders",
     path: ["tradingMode"],
 })
-    .refine((data) => data.marginMode === undefined || data.tradingMode === "MARGIN", {
+    .refine((data) => data.marginMode === undefined || data.tradingMode !== "SPOT", {
     message: "marginMode is only supported for MARGIN orders",
     path: ["tradingMode"],
-})
-    .refine((data) => data.marginMode !== "CROSS" || data.marginAccountId !== undefined, {
-    message: "marginAccountId is required for CROSS margin orders",
-    path: ["marginAccountId"],
 })
     .refine((data) => data.marginMode !== "CROSS" || data.riskBucketId === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketId",
@@ -660,10 +656,6 @@ export const BatchCreateOrderItemSchema = z
     .refine((data) => data.marginMode !== "CROSS" || data.riskBucketCollateral === undefined, {
     message: "marginMode CROSS cannot be combined with riskBucketCollateral",
     path: ["riskBucketCollateral"],
-})
-    .refine((data) => data.marginMode !== "CROSS" || data.strategyKey === undefined, {
-    message: "marginMode CROSS cannot be combined with strategyKey",
-    path: ["strategyKey"],
 })
     .refine((data) => data.riskBucketCollateral === undefined || data.riskBucketId === undefined, {
     message: "riskBucketCollateral creates a new risk bucket and cannot be combined with riskBucketId",

package/dist/websocket/base.d.ts

@@ -71,23 +71,43 @@ export interface WebSocketStatusInfo {
  */
 export type StatusHandler = (status: WebSocketStatus, info: WebSocketStatusInfo) => void;
 /**
- * Why the connection was re-established. Delivered by
- * {@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.
+ * Why the application should refetch REST state, delivered by
+ * {@link MonacoWebSocketConfig.onResync}. Two cases:
+ *
+ * - A reconnect (`reason` absent): sent after the socket reopens and sends its
+ *   authentication/subscription requests, without waiting for server acks or
+ *   snapshots. Refetch every channel.
+ * - A scoped resync (`reason: "resynced"`, 0XM-3553): the connection stayed
+ *   open, but the server reported that an upstream loss may have cost the
+ *   listed `channels` frames, or re-sent a snapshot for a channel that has no
+ *   snapshot handler. Delivered once per burst, no earlier than the server's
+ *   requested delay, with `code: 1013` and `slowClient: true` so a handler
+ *   written for reconnects still refetches (everything). Refetch only
+ *   `channels` to recover precisely. The subscriptions stay active.
+ *
+ * The application owns channel-specific recovery; the SDK does not refetch
+ * REST state itself.
  */
 export interface WebSocketResyncInfo {
     /** WebSocket close code of the connection that was lost. */
     code: number;
     /**
-     * True when the server closed with 1013 (try again later): the client fell
-     * behind a sequential stream (orders, conditional orders, liquidations,
-     * trades, movements) and the stream has a gap. There is no wire sequence
-     * number — the 1013 close is the gap signal, and a snapshot refetch is the
-     * only safe repair.
+     * True when the server closed with 1013 (try again later): the connection
+     * fell behind, or the server lost events upstream, and any of its streams
+     * may have a gap. Order, account and engine-sourced public streams carry no
+     * wire sequence number, so the 1013 close is their gap signal and a snapshot
+     * refetch is the only safe repair. `depth`, `bbo` and a single market's
+     * market-data-sourced `trades` rebuild from the snapshot the reconnect
+     * brings; `trades:*` has no snapshot, so backfill its history over REST.
      */
     slowClient: boolean;
+    /** `"resynced"` for a scoped resync; absent on a reconnect. */
+    reason?: "resynced";
+    /**
+     * The channels to refetch, exactly as subscribed, on a scoped resync;
+     * absent on a reconnect, which covers every channel.
+     */
+    channels?: string[];
 }
 /** Handler invoked after a reconnect resumes the live stream. */
 export type ResyncHandler = (info: WebSocketResyncInfo) => void;
@@ -200,6 +220,16 @@ export type ReauthenticationRequiredHandler = (info: WebSocketReauthenticationIn
 export interface MonacoWebSocketConfig {
     /** Enable auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
+    /**
+     * Offer the server the `resync` capability (default: true when
+     * {@link onResync} is set, 0XM-3553; never without it, since the channels
+     * would have nowhere to go): on an
+     * upstream loss it can attribute, the server keeps the connection open and
+     * names the channels to refetch (delivered through {@link onResync} with
+     * `reason: "resynced"`), or re-sends their snapshots, instead of closing it
+     * with 1013. `false` keeps the close-and-reconnect behaviour.
+     */
+    scopedResync?: boolean;
     /**
      * Maximum reconnection attempts per outage (default: unlimited). Retry
      * delay is full-jitter exponential backoff capped at 30s, so unlimited

package/dist/websocket/client.d.ts

@@ -59,8 +59,14 @@ import type { Interval } from "../market";
 import type { TradingMode } from "../trading";
 import type { SubscriptionChangeHandler, WebSocketStatus, WebSocketSubscriptionState } from "./base";
 import type { OrderbookQuotationMode } from "./clients/orderbook-client";
-import type { AccountEvent, AccountEventData, ConditionalOrderEvent, ConditionalOrderEventData, CopyEvent, CopyRelationshipEventData, InstrumentEvent, InstrumentEventData, LiquidationEvent, LiquidationEventData, MarketLiquidationEvent, MarketStatsAllEvent, MarketStatsData, MarketStatsEvent, MarketStatsSummary, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, PositionEventData, PositionValuationEvent, RfqEvent, RfqTradeEvent, TradeEvent, TradeEventData, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
+import type { Bbo, DepthBook, LocalBookOptions } from "./depth";
+import type { AccountEvent, AccountEventData, ConditionalOrderEvent, ConditionalOrderEventData, CopyEvent, CopyRelationshipEventData, InstrumentEvent, InstrumentEventData, LiquidationEvent, LiquidationEventData, MarketLiquidationEvent, MarketStatsAllEvent, MarketStatsData, MarketStatsEvent, MarketStatsSummary, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderEvent, PositionEvent, PositionEventData, PositionValuationEvent, RfqEvent, RfqTradeEvent, TradeEvent, TradeEventData, TradeGap, TwapOrderEvent, TwapOrderEventData, UserBalanceEvent, UserBalanceEventData, UserMovementEvent } from "./events";
 import type { OHLCVSnapshotCandle, OrderSnapshotItem, SnapshotHandler } from "./snapshots";
+/** Options for `ws.trades`. */
+export interface TradesOptions {
+    /** Called when a sequenced trade does not link to the last trade delivered (it is still delivered). */
+    onGap?: (gap: TradeGap) => void;
+}
 export type MessageHandler<T> = (data: T) => void;
 export interface MonacoWebSocket {
     /** Connect to the WebSocket server */
@@ -92,10 +98,26 @@ export interface MonacoWebSocket {
     /** 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); `onSnapshot` receives one event, the current book read from the matching
-     * engine, in the same shape as a live event. Its `sequence` is 0. A pair or mode with no book gets `[]`.
+     * Subscribe to orderbook events (public); `onSnapshot` receives one event, the current book, in the same shape as a
+     * live event. From the matching engine it is the top 20 levels with `sequence` 0; from the market-data service it is
+     * grouped over the whole book (at most 20 levels or buckets per side), carries `bookSeq`, and its `sequence` equals
+     * `bookSeq`. From the engine, a pair or mode with no book gets `[]`; from the market-data service, an unknown pair
+     * gets a `SNAPSHOT_UNAVAILABLE` error (through `onError`) instead, and no snapshot until the pair is listed.
      */
     orderbook: (tradingPairId: string, tradingMode: TradingMode, magnitude: number, quotationMode: OrderbookQuotationMode, handler: MessageHandler<OrderbookEvent>, onSnapshot?: SnapshotHandler<OrderbookEvent>) => () => void;
+    /**
+     * Keep a local depth book from the market-data `depth:<tradingPairId>:<SPOT|MARGIN>` channel (public): up to 1000
+     * levels per side. The subscribe-time snapshot is the base; live frames that do not link to it are dropped or
+     * trigger a rebuild from a fresh snapshot. `onBook` receives the whole book after the snapshot and after every
+     * applied frame. Subscribers on the same channel share one book. Returns a function that stops listening.
+     */
+    depth: (tradingPairId: string, tradingMode: TradingMode, onBook: MessageHandler<DepthBook>, options?: LocalBookOptions) => () => void;
+    /**
+     * Keep the top of book from the market-data `bbo:<tradingPairId>:<SPOT|MARGIN>` channel (public), with the same
+     * snapshot handoff and link checks as `depth`. `onBbo` receives the current best bid and ask (an empty side is
+     * `null`) after the snapshot and after every applied frame.
+     */
+    bbo: (tradingPairId: string, tradingMode: TradingMode, onBbo: MessageHandler<Bbo>, options?: LocalBookOptions) => () => void;
     /**
      * Subscribe to OHLCV candlestick events (public); `onSnapshot` receives the series' newest 350 candles, oldest first.
      * The newest snapshot candle can be partial or missing, so upsert live candles by `T`. A `*` price type gets no snapshot.
@@ -104,8 +126,14 @@ export interface MonacoWebSocket {
     /**
      * Subscribe to trade events (public); `onSnapshot` receives the pair's newest 50 trades, newest first.
      * The snapshot can overlap the first live trades or miss one executed just before subscribing, so dedupe on `tradeId`.
+     *
+     * When the server sources trades from market-data, each trade carries `seq` / `matchIndex` / `prevSeq` /
+     * `prevMatchIndex`, and the snapshot's `meta.cursor` names the trade it is current as of. The helper then drops
+     * trades at or below the cursor or the last delivered trade, and reports one that does not link to the last
+     * delivered trade to `options.onGap` (still delivering it: the server forwards only linking trades, so a mismatch
+     * means a frame was lost on this client). Without those fields every trade is delivered as before.
      */
-    trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>, onSnapshot?: SnapshotHandler<TradeEventData>) => () => void;
+    trades: (tradingPairId: string, handler: MessageHandler<TradeEvent>, onSnapshot?: SnapshotHandler<TradeEventData>, options?: TradesOptions) => () => void;
     /** Subscribe to user movement events (requires authentication) */
     movements: (handler: MessageHandler<UserMovementEvent>) => () => void;
     /** Subscribe to user order events for all trading pairs (requires authentication); `onSnapshot` receives every resting order */

package/dist/websocket/depth.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Market-data depth and BBO types (0XM-3551).
+ *
+ * The `depth:<tradingPairId>:<SPOT|MARGIN>` and `bbo:<tradingPairId>:<SPOT|MARGIN>`
+ * WebSocket channels carry the market-data service's sequenced book: a
+ * subscribe-time snapshot, then live frames linked by `bookSeq` /
+ * `prevBookSeq`. The SDK's `ws.depth` and `ws.bbo` helpers keep the local
+ * state for you; the frame shapes are exported for callers that need them.
+ *
+ * Sequence numbers are durable-log positions (u64). They are surfaced as
+ * decimal strings, since a u64 can exceed `Number.MAX_SAFE_INTEGER`; compare
+ * them with `BigInt`.
+ */
+import type { TradingMode } from "../trading";
+/** One price level, with its absolute (not incremental) values. */
+export interface DepthLevel {
+    /** Price, a decimal string. */
+    price: string;
+    /** Resting quantity at this price, a decimal string. */
+    quantity: string;
+    /** Number of resting orders at this price. */
+    orderCount: number;
+}
+/**
+ * The `depth` channel's subscribe-time snapshot: up to 1000 levels per side,
+ * best first, exact as of `bookSeq`.
+ */
+export interface DepthSnapshot {
+    tradingPairId: string;
+    tradingMode: TradingMode | (string & {});
+    /** The durable-log sequence the snapshot is exact as of (u64, decimal string). */
+    bookSeq: string;
+    bids: DepthLevel[];
+    asks: DepthLevel[];
+    /** Every bid level is in `bids`; when false, levels below the last one are unknown. */
+    bidsComplete: boolean;
+    /** Every ask level is in `asks`; when false, levels above the last one are unknown. */
+    asksComplete: boolean;
+}
+/**
+ * A live `depth` frame: only the levels that changed since `prevBookSeq`,
+ * each with its absolute value at `bookSeq`. A quantity of `"0"` (order
+ * count 0) removes the level.
+ */
+export interface DepthDelta {
+    tradingPairId: string;
+    tradingMode: TradingMode | (string & {});
+    /** The durable-log sequence of the last change this frame includes. */
+    bookSeq: string;
+    /** The `bookSeq` this frame continues from. */
+    prevBookSeq: string;
+    /** The durable-log timestamp of the step at `bookSeq`, in milliseconds. */
+    timestampMs: number;
+    bids: DepthLevel[];
+    asks: DepthLevel[];
+    /** Set while the publisher lags the durable log. */
+    stale: boolean;
+}
+/** The local book `ws.depth` maintains and hands to its listener. */
+export interface DepthBook {
+    tradingPairId: string;
+    tradingMode: TradingMode | (string & {});
+    /** The sequence the book is current as of (u64, decimal string). */
+    bookSeq: string;
+    /** Bids, best (highest) first. */
+    bids: DepthLevel[];
+    /** Asks, best (lowest) first. */
+    asks: DepthLevel[];
+    /**
+     * Every bid level is known. When false, the book holds only levels at or
+     * above the snapshot's deepest bid: a level below it that a removal would
+     * promote stays unknown until the next snapshot.
+     */
+    bidsComplete: boolean;
+    /** Every ask level is known (see `bidsComplete`). */
+    asksComplete: boolean;
+    /** The latest applied frame was published while the service lagged. */
+    stale: boolean;
+    /** Durable-log time of the latest applied frame; absent right after a snapshot. */
+    timestampMs?: number;
+}
+/** The `bbo` channel's subscribe-time snapshot. An empty side is `null`. */
+export interface BboSnapshot {
+    tradingPairId: string;
+    tradingMode: TradingMode | (string & {});
+    bookSeq: string;
+    bestBid: string | null;
+    /** Quantity resting at `bestBid`. */
+    bidQty: string | null;
+    bestAsk: string | null;
+    /** Quantity resting at `bestAsk`. */
+    askQty: string | null;
+}
+/** A live `bbo` frame. */
+export interface BboEvent extends BboSnapshot {
+    prevBookSeq: string;
+    timestampMs: number;
+    stale: boolean;
+}
+/** The top of book `ws.bbo` maintains and hands to its listener. */
+export interface Bbo extends BboSnapshot {
+    /** The latest applied frame was published while the service lagged. */
+    stale: boolean;
+    /** Durable-log time of the latest applied frame; absent right after a snapshot. */
+    timestampMs?: number;
+}
+/** Why a local book was discarded and is being rebuilt from a new snapshot. */
+export type LocalBookResyncReason = 
+/** A frame did not link to the book (a lost frame), or could not be read. */
+"gap"
+/**
+ * The server could not serve a snapshot (`SNAPSHOT_UNAVAILABLE`; it retries
+ * and sends one when the book heals), or the one it sent could not be read.
+ */
+ | "snapshot_unavailable"
+/**
+ * A side whose snapshot was incomplete has thinned below half its snapshot
+ * depth: the levels beyond its boundary are unknown, so a fresh snapshot is
+ * taken.
+ */
+ | "truncated"
+/** The connection dropped; the book is rebuilt from the snapshot the reconnect brings. */
+ | "disconnected";
+/** A channel-level error the server sent for a `depth` / `bbo` subscription. */
+export interface LocalBookError {
+    /** The server's error code, e.g. `INVALID_SUBSCRIPTION`. */
+    code: string;
+    message: string;
+}
+/** Options for `ws.depth` and `ws.bbo`. */
+export interface LocalBookOptions {
+    /**
+     * Called when the local state is discarded to be rebuilt; the listener is
+     * called again once the new snapshot arrives.
+     */
+    onResync?: (reason: LocalBookResyncReason) => void;
+    /**
+     * Called when the server rejects the subscription with an error other than
+     * `SNAPSHOT_UNAVAILABLE` (which is retried): the book will not arrive.
+     */
+    onError?: (error: LocalBookError) => void;
+}

package/dist/websocket/depth.js

@@ -0,0 +1,13 @@
+/**
+ * Market-data depth and BBO types (0XM-3551).
+ *
+ * The `depth:<tradingPairId>:<SPOT|MARGIN>` and `bbo:<tradingPairId>:<SPOT|MARGIN>`
+ * WebSocket channels carry the market-data service's sequenced book: a
+ * subscribe-time snapshot, then live frames linked by `bookSeq` /
+ * `prevBookSeq`. The SDK's `ws.depth` and `ws.bbo` helpers keep the local
+ * state for you; the frame shapes are exported for callers that need them.
+ *
+ * Sequence numbers are durable-log positions (u64). They are surfaced as
+ * decimal strings, since a u64 can exceed `Number.MAX_SAFE_INTEGER`; compare
+ * them with `BigInt`.
+ */

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

@@ -67,6 +67,46 @@ export interface OrderbookEvent {
     quoteDecimals: number;
     /** Event timestamp */
     timestamp: string;
-    /** Sequence number for ordering */
+    /**
+     * Sequence number for ordering. Under the default engine source it is the
+     * matching engine's own frame counter; when the server renders the channel
+     * from market-data's book (`WS_ORDERBOOK_SOURCE=market_data`) it equals
+     * `bookSeq`. The two are different number spaces: do not compare a value
+     * from one source with a value from the other (a reconnect or deploy can
+     * switch sources). For exact comparison under the market-data source use
+     * `bookSeq`, a u64 decimal string.
+     */
     sequence: number;
+    /**
+     * Durable-log sequence this book is exact as of, as a decimal string
+     * (a u64 can exceed `Number.MAX_SAFE_INTEGER`; compare with `BigInt`).
+     *
+     * Present on a REST snapshot of more than 100 levels: a point-in-time
+     * read and staleness check, not a base for applying depth deltas (the REST
+     * snapshot may come from a different market-data replica than the stream;
+     * for a live local book use `sdk.ws.depth`, which hands off from the
+     * `depth` channel's own snapshot). A side that came back with as many
+     * levels as requested may hold more.
+     *
+     * Also present on every `orderbook` WebSocket frame and snapshot row when
+     * the server renders the channel from market-data's book
+     * (`WS_ORDERBOOK_SOURCE=market_data`): the same watermark the `depth`
+     * channel carries, identical on every server. Each such frame restates the
+     * book, so per subscription (one channel string: pair, mode, magnitude and
+     * quotation) a frame whose `bookSeq` is not past the last one applied to it
+     * can be ignored. The watermark is the book's, shared by every magnitude
+     * and quotation of it: a newly subscribed variant starts from its own
+     * snapshot even when its `bookSeq` equals another variant's.
+     */
+    bookSeq?: string;
+    /**
+     * On an `orderbook` WebSocket frame rendered from market-data's book
+     * (`WS_ORDERBOOK_SOURCE=market_data`): the `bookSeq` of the previous frame
+     * this server rendered for the book, `"0"` before the first, as a decimal
+     * string. A `prevBookSeq` at or below the `bookSeq` you hold means no
+     * rendered state was skipped. Informational only: every frame restates the
+     * whole book, so nothing needs to be re-requested when it is higher.
+     * Absent under the engine source and on REST snapshots.
+     */
+    prevBookSeq?: string;
 }

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

@@ -42,9 +42,17 @@ export interface RfqRequestedEvent {
 }
 /** One side of the taker's view: the allocation that would fill the quantity. */
 export interface RfqSideViewEventData {
-    /** All-in volume-weighted price, the taker's fee included. */
+    /** All-in volume-weighted price, the taker's Monaco and builder fees included. */
     vwap: string;
     availableQuantity: string;
+    /** The volume-weighted price before fees. */
+    grossVwap?: string;
+    /** Estimated Monaco taker fee on `availableQuantity`, in the quote asset. */
+    estimatedMonacoFee?: string;
+    /** Estimated builder fee on `availableQuantity`, in the quote asset. */
+    estimatedBuilderFee?: string;
+    /** Estimated total taker fee on `availableQuantity`, in the quote asset. */
+    estimatedTotalFee?: string;
 }
 /** The taker's view of the quotes. No maker identity or individual quote. */
 export interface RfqViewEventData {
@@ -57,6 +65,10 @@ export interface RfqViewEventData {
     asOfMs: number;
     /** Pushes can arrive out of order: keep the view with the highest `sequence`. */
     sequence: number;
+    /** Your Monaco taker fee rate in this view, in centi-bps. */
+    monacoFeeCbps?: number;
+    /** Your frontend's builder fee rate in this view, in centi-bps; frozen when you accept. */
+    builderFeeCbps?: number;
 }
 /** To the taker: its view moved. */
 export interface RfqViewEvent {
@@ -82,6 +94,18 @@ export interface RfqSelectionEventData {
     makerFeeCbps: number;
     /** Reject or improve before this time; silence executes. */
     lastLookDeadlineAtMs: number;
+    /**
+     * The MOST your frontend's builder add-on charges on this fill, in centi-bps:
+     * the rate stored on your quote order. A fill charges it or nothing, never
+     * more; the receipt shows what was charged. Absent when it could not be read.
+     */
+    maxBuilderFeeCbps?: number;
+    /**
+     * Estimated net at `quantity` and `price`, in the quote asset, at
+     * `makerFeeCbps` plus `maxBuilderFeeCbps`: the least you receive when
+     * selling, the most you pay when buying. Absent with `maxBuilderFeeCbps`.
+     */
+    estimatedNet?: string;
 }
 /** To one selected maker: its last-look prompt. */
 export interface RfqSelectedEvent {
@@ -94,7 +118,12 @@ export interface RfqFillEventData {
     executionId: string;
     price: string;
     quantity: string;
+    /** Your whole taker fee on this fill: `monacoFee` plus `builderFee`. */
     fee: string;
+    /** The Monaco part of `fee`. */
+    monacoFee?: string;
+    /** The builder part of `fee`. */
+    builderFee?: string;
 }
 /** How an RFQ ended, for its taker. */
 export interface RfqOutcomeEventData {

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

@@ -40,6 +40,12 @@ export interface TradeEventData {
     quoteVolumeRaw?: string;
     /** Application (frontend) that placed the taker order; trade volume and fees are attributed to it. REST trade reads only. */
     takerApplicationId?: string;
+    /**
+     * The taker's builder fee: the add-on the taker's application charged, in
+     * raw quote-asset units, on top of `takerFeeRaw`; `"0"` when it charged
+     * none. REST trade reads only.
+     */
+    builderFeeRaw?: string;
 }
 /**
  * Trade event emitted when a trade is executed
@@ -53,4 +59,35 @@ export interface TradeEvent {
     tradingMode: TradingMode | (string & {});
     /** Trade execution data */
     data: TradeEventData;
+    /**
+     * The trade's position in its pair's chain: the durable-log sequence of the
+     * step that executed it. Present only when the server sources trades from
+     * market-data (`WS_TRADES_SOURCE=market_data`); absent otherwise.
+     */
+    seq?: number;
+    /** The trade's index among its step's fills; with `seq`, the trade's key. Same presence as `seq`. */
+    matchIndex?: number;
+    /** `seq` of the previous trade on the pair; 0 when the publisher knows none. Same presence as `seq`. */
+    prevSeq?: number;
+    /** `matchIndex` of the previous trade on the pair; `null` when the publisher knows none. Same presence as `seq`. */
+    prevMatchIndex?: number | null;
+}
+/**
+ * A sequenced trade `ws.trades` received that did not link to the last trade
+ * it delivered (or the snapshot cursor). The server forwards only linking
+ * trades, so this means a frame was lost or unreadable on the client; the
+ * trade is still delivered and the chain continues from it.
+ */
+export interface TradeGap {
+    tradingPairId: string;
+    /** The key of the last trade delivered, or the snapshot cursor. */
+    expected: {
+        seq: number;
+        matchIndex: number;
+    };
+    /** The received trade's link as sent; `null` where the frame carried none. */
+    received: {
+        prevSeq: number | null;
+        prevMatchIndex: number | null;
+    };
 }

package/dist/websocket/index.d.ts

@@ -6,5 +6,6 @@
 export * from "./base";
 export * from "./client";
 export * from "./clients/orderbook-client";
+export * from "./depth";
 export * from "./events";
 export * from "./snapshots";