@0xmonaco/core 1.0.45 → 1.0.46

package/dist/api/perp/routes.d.ts

@@ -34,6 +34,7 @@ export declare const perpRoutes: {
             pageSize?: number;
         }) => string;
         readonly getTwap: (twapOrderId: string) => string;
+        readonly getTwapTca: (twapOrderId: string) => string;
         readonly cancelTwap: (twapOrderId: string) => string;
     };
     readonly delegatedAgents: {

package/dist/api/perp/routes.js

@@ -32,6 +32,7 @@ export const perpRoutes = {
         createTwap: () => `${API_V1}/orders/twap`,
         listTwap: (params) => withQuery(`${API_V1}/orders/twap`, params),
         getTwap: (twapOrderId) => `${API_V1}/orders/twap/${encodeSegment(twapOrderId)}`,
+        getTwapTca: (twapOrderId) => `${API_V1}/orders/twap/${encodeSegment(twapOrderId)}/tca`,
         cancelTwap: (twapOrderId) => `${API_V1}/orders/twap/${encodeSegment(twapOrderId)}/cancel`,
     },
     delegatedAgents: {

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

@@ -21,7 +21,7 @@
  * );
  * ```
  */
-import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MarginMode, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, TimeInForce, TradingAPI, TradingMode, TwapOrder } from "@0xmonaco/types";
+import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, GetTwapOrderTcaResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MarginMode, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, TimeInForce, TradingAPI, TradingMode, TwapOrder } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
@@ -444,6 +444,28 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * ```
      */
     getTwapOrder(twapOrderId: string): Promise<TwapOrder>;
+    /**
+     * Gets the post-execution TCA (transaction cost analysis) report for a
+     * TERMINAL TWAP parent order.
+     *
+     * Available once the parent is COMPLETED or CANCELLED (a non-terminal
+     * parent returns 400). Reports realized average price against the arrival
+     * price and the window-TWAP benchmark over the parent's active window.
+     * Sign convention: positive bps = execution beat the reference. Benchmark
+     * fields are null when no price series covered the window sufficiently.
+     *
+     * @param twapOrderId - The TWAP parent order UUID
+     * @returns Promise resolving to the TCA report
+     * @throws {APIError} When API communication fails, the order is not found,
+     * or the order has not reached a terminal state
+     *
+     * @example
+     * ```typescript
+     * const tca = await tradingAPI.getTwapOrderTca(twapOrderId);
+     * console.log(`vs benchmark: ${tca.performanceVsBenchmarkBps} bps (${tca.benchmarkSource})`);
+     * ```
+     */
+    getTwapOrderTca(twapOrderId: string): Promise<GetTwapOrderTcaResponse>;
     /**
      * Lists TWAP parent orders for the authenticated user.
      *

package/dist/api/trading/api.js

@@ -720,6 +720,33 @@ export class TradingAPIImpl extends BaseAPI {
             method: "GET",
         });
     }
+    /**
+     * Gets the post-execution TCA (transaction cost analysis) report for a
+     * TERMINAL TWAP parent order.
+     *
+     * Available once the parent is COMPLETED or CANCELLED (a non-terminal
+     * parent returns 400). Reports realized average price against the arrival
+     * price and the window-TWAP benchmark over the parent's active window.
+     * Sign convention: positive bps = execution beat the reference. Benchmark
+     * fields are null when no price series covered the window sufficiently.
+     *
+     * @param twapOrderId - The TWAP parent order UUID
+     * @returns Promise resolving to the TCA report
+     * @throws {APIError} When API communication fails, the order is not found,
+     * or the order has not reached a terminal state
+     *
+     * @example
+     * ```typescript
+     * const tca = await tradingAPI.getTwapOrderTca(twapOrderId);
+     * console.log(`vs benchmark: ${tca.performanceVsBenchmarkBps} bps (${tca.benchmarkSource})`);
+     * ```
+     */
+    async getTwapOrderTca(twapOrderId) {
+        validate(CancelTwapOrderSchema, { twapOrderId });
+        return await this.makeAuthenticatedRequest(perpRoutes.orders.getTwapTca(twapOrderId), {
+            method: "GET",
+        });
+    }
     /**
      * Lists TWAP parent orders for the authenticated user.
      *

package/dist/api/websocket/types.d.ts

@@ -1,4 +1,4 @@
-import type { AccountEvent, ConditionalOrderEvent, Interval, LiquidationEvent, MarketStatsAllEvent, MarketStatsEvent, MonacoWebSocketConfig, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderbookQuotationMode, OrderEvent, PositionEvent, SessionCredentials, TradeEvent, TradingMode, TwapOrderEvent, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
+import type { AccountEvent, ConditionalOrderEvent, InstrumentEvent, Interval, LiquidationEvent, MarketStatsAllEvent, MarketStatsEvent, MonacoWebSocketConfig, OHLCVEvent, OHLCVPriceType, OrderbookEvent, OrderbookQuotationMode, OrderEvent, PositionEvent, SessionCredentials, TradeEvent, TradingMode, TwapOrderEvent, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
 export type { ResyncHandler, StatusHandler, WebSocketResyncInfo } from "@0xmonaco/types";
 export type MessageHandler<T> = (data: T) => void;
 /**
@@ -46,6 +46,8 @@ export interface MonacoWebSocket {
     liquidations: (handler: MessageHandler<LiquidationEvent>, tradingPairId?: string) => () => 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;
     /** Subscribe to per-market statistics for one trading pair (public) */
     marketStats: (tradingPairId: string, handler: MessageHandler<MarketStatsEvent>) => () => void;
     /** Subscribe to the all-markets statistics summary (public) */

package/dist/api/websocket/websocket.js

@@ -13,6 +13,7 @@ const CONDITIONAL_ORDER_TRIGGER_SOURCES = ["MARK_PRICE"];
 const CONDITIONAL_ORDER_STATES = ["PENDING_PARENT", "ACTIVE", "TRIGGERING", "TRIGGERED", "CANCELLED", "EXPIRED", "FAILED"];
 const CONDITIONAL_ORDER_ASSOCIATION_TYPES = ["POSITION", "PARENT_ORDER"];
 const TWAP_ORDER_STATES = ["PENDING", "ACTIVE", "COMPLETED", "CANCELLED"];
+const INSTRUMENT_CHANGE_KINDS = ["listing", "delisting", "halt", "unhalt", "config_change"];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -48,6 +49,13 @@ function readOptionalNumber(source, field) {
     }
     return value;
 }
+function readStringArray(source, field) {
+    const value = source[field];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`Invalid WebSocket event: ${field} must be an array of strings`);
+    }
+    return value;
+}
 function readEnum(source, field, allowed) {
     const value = readString(source, field);
     if (!allowed.includes(value)) {
@@ -269,6 +277,42 @@ function parseMarketStatsAllEvent(rawData) {
         markets: rawData.markets.map(parseMarketStatsSummary),
     };
 }
+function parseInstrumentEventData(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid instrument event: data must be an object");
+    }
+    const data = keysToCamelCase(raw);
+    return {
+        change: readEnum(data, "change", INSTRUMENT_CHANGE_KINDS),
+        tradingPairId: readString(data, "tradingPairId"),
+        symbol: readString(data, "symbol"),
+        isActive: readBoolean(data, "isActive"),
+        tickSize: readString(data, "tickSize"),
+        quantityStepSize: readString(data, "quantityStepSize"),
+        minOrderSize: readString(data, "minOrderSize"),
+        maxOrderSize: readString(data, "maxOrderSize"),
+        marketType: readString(data, "marketType"),
+        category: readString(data, "category"),
+        maxLeverage: readOptionalString(data, "maxLeverage"),
+        initialMarginRate: readOptionalString(data, "initialMarginRate"),
+        maintenanceMarginRate: readOptionalString(data, "maintenanceMarginRate"),
+        // Values are snake_case wire field NAMES (e.g. "tick_size"); only object
+        // keys are camelCased, so they pass through untouched.
+        changedFields: readStringArray(data, "changedFields"),
+        updatedAt: readString(data, "updatedAt"),
+    };
+}
+function parseInstrumentEvent(rawData) {
+    if (!isRecord(rawData)) {
+        throw new Error("Invalid instrument event: payload must be an object");
+    }
+    // The frame's top-level `trading_pair_id` is not inside `data`, so it stays
+    // snake_case (only `data` is camelCased by parseInstrumentEventData).
+    return {
+        tradingPairId: readString(rawData, "trading_pair_id"),
+        data: parseInstrumentEventData(rawData.data),
+    };
+}
 /**
  * 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
@@ -337,6 +381,23 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
     let pendingResyncCode = null;
     // Handler storage: channel -> set of handlers (supports multiple subscribers per channel)
     const handlers = new Map();
+    // Subscribe-time Snapshot frame handlers, keyed by the RAW subscribed
+    // channel: the server echoes that exact channel on the Snapshot frame
+    // (unlike live Event frames, which can arrive on a more specific channel and
+    // are prefix-matched). Only subscriptions that opt in receive them — a
+    // snapshot's data shape differs from the channel's Event shape, so blindly
+    // reusing the Event handlers would feed every other channel's parser a frame
+    // it must reject.
+    const snapshotHandlers = new Map();
+    // Latest known full-config frame per market for each subscribed instrument
+    // channel, seeded by the subscribe-time Snapshot and superseded by every
+    // live frame (instrument frames are terminal-state, never deltas). The
+    // server sends a snapshot only for a genuinely new wire subscription, so a
+    // late local subscriber on an already-held channel bootstraps from this
+    // cache instead of starting blind. Dropped when the channel's last local
+    // subscriber unsubscribes — the next first subscriber triggers a fresh wire
+    // Subscribe whose snapshot is authoritative, never the stale cache.
+    const instrumentBaseline = new Map();
     const getStatus = () => {
         if (!ws)
             return reconnectTimer ? "reconnecting" : "disconnected";
@@ -431,6 +492,11 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         }
     };
     const resubscribeAll = () => {
+        // Every re-sent Subscribe is genuinely new to the server (new
+        // connection), so fresh authoritative snapshots are inbound: the
+        // pre-outage instrument cache is stale — markets may have been delisted
+        // during the gap — and must not be replayed to late subscribers.
+        instrumentBaseline.clear();
         const channels = Array.from(handlers.keys());
         if (channels.length > 0) {
             send({ type: "Subscribe", channels });
@@ -460,7 +526,17 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         return frameChannel === subscriptionChannel || frameChannel.startsWith(`${subscriptionChannel}:`);
     };
     const routeMessage = (msg) => {
-        if (msg.type !== "Event" || !msg.channel)
+        if (!msg.channel)
+            return;
+        if (msg.type === "Snapshot") {
+            // Exact match only: the Snapshot frame's channel echoes the raw
+            // subscribed channel, never a more specific one.
+            for (const handler of snapshotHandlers.get(msg.channel) ?? []) {
+                handler(msg.data);
+            }
+            return;
+        }
+        if (msg.type !== "Event")
             return;
         // Find matching handlers and call all of them
         for (const [subscriptionChannel, channelHandlers] of handlers) {
@@ -579,23 +655,38 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         stopHeartbeat();
         pendingResyncCode = null;
         handlers.clear();
+        snapshotHandlers.clear();
+        instrumentBaseline.clear();
         ws?.close(1000, "Client disconnect");
         ws = null;
         options.onStatusChange?.("disconnected");
     };
-    const subscribe = (channel, handler) => {
+    const subscribe = (channel, handler, snapshotHandler) => {
         const isFirstSubscriber = !handlers.has(channel);
         // Add handler to the set for this channel
         if (!handlers.has(channel)) {
             handlers.set(channel, new Set());
         }
         handlers.get(channel)?.add(handler);
+        if (snapshotHandler) {
+            if (!snapshotHandlers.has(channel)) {
+                snapshotHandlers.set(channel, new Set());
+            }
+            snapshotHandlers.get(channel)?.add(snapshotHandler);
+        }
         // Only send Subscribe message on first subscriber for this channel
         if (isFirstSubscriber && ws?.readyState === WebSocket.OPEN) {
             send({ type: "Subscribe", channels: [channel] });
         }
         // Return unsubscribe function
         return () => {
+            if (snapshotHandler) {
+                const channelSnapshotHandlers = snapshotHandlers.get(channel);
+                channelSnapshotHandlers?.delete(snapshotHandler);
+                if (channelSnapshotHandlers?.size === 0) {
+                    snapshotHandlers.delete(channel);
+                }
+            }
             const channelHandlers = handlers.get(channel);
             if (channelHandlers) {
                 channelHandlers.delete(handler);
@@ -952,6 +1043,110 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             }
         });
     };
+    /**
+     * Subscribe to market lifecycle + configuration changes (public): listings,
+     * delistings, and edits to tick size, step size, order-size bounds, or (for
+     * perp markets) leverage/margin-rate bounds. Omit `tradingPairId` for all
+     * markets, or pass one to filter. Every frame carries the market's FULL
+     * current config as a terminal-state snapshot (never an additive delta);
+     * `changedFields` names what the mutation touched. A subscribe-time snapshot
+     * 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.
+     */
+    const subscribeInstruments = (handler, tradingPairId) => {
+        if (!handler) {
+            throw new Error("instruments subscription requires a handler");
+        }
+        if (tradingPairId !== undefined && tradingPairId.length === 0) {
+            throw new Error("instruments tradingPairId cannot be empty");
+        }
+        // Every live frame is published on instrument:<pairId>; a bare
+        // `instrument` subscription receives all of them via routeMessage's prefix
+        // match, so unlike market_stats there is no distinct all-markets frame
+        // shape to guard against.
+        const channel = tradingPairId ? `instrument:${tradingPairId}` : "instrument";
+        const cacheEvent = (event) => {
+            let byPair = instrumentBaseline.get(channel);
+            if (!byPair) {
+                byPair = new Map();
+                instrumentBaseline.set(channel, byPair);
+            }
+            byPair.set(event.tradingPairId, event);
+        };
+        // A subscriber joining a channel this connection already holds gets no
+        // fresh server snapshot (the wire Subscribe is suppressed, and the server
+        // snapshots only genuinely new subscriptions), so replay the cached
+        // baseline to it instead. Asynchronously, matching how a real snapshot
+        // arrives — never during the subscribe call itself.
+        const isLateSubscriber = handlers.has(channel);
+        let unsubscribed = false;
+        const unsubscribe = subscribe(channel, (rawData) => {
+            try {
+                const event = parseInstrumentEvent(rawData);
+                cacheEvent(event);
+                handler(event);
+            }
+            catch (err) {
+                console.error("WebSocket: Error processing instrument event", err);
+            }
+        }, 
+        // 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);
+                }
+            }
+            catch (err) {
+                console.error("WebSocket: Error processing instrument snapshot", err);
+            }
+        });
+        // 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()];
+                queueMicrotask(() => {
+                    if (unsubscribed)
+                        return;
+                    for (const event of replay) {
+                        try {
+                            handler(event);
+                        }
+                        catch (err) {
+                            console.error("WebSocket: Error processing instrument baseline replay", err);
+                        }
+                    }
+                });
+            }
+        }
+        return () => {
+            unsubscribed = true;
+            unsubscribe();
+            // Last local subscriber gone: the wire Unsubscribe was sent, so the
+            // cache would only go stale from here — drop it.
+            if (!handlers.has(channel)) {
+                instrumentBaseline.delete(channel);
+            }
+        };
+    };
     /**
      * Subscribe to per-market statistics for a single trading pair (public). Each
      * frame carries the market's full current stats as a terminal-state snapshot.
@@ -1029,6 +1224,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         positions: subscribePositions,
         liquidations: subscribeLiquidations,
         account: subscribeAccount,
+        instruments: subscribeInstruments,
         marketStats: subscribeMarketStats,
         marketStatsAll: subscribeMarketStatsAll,
     };

package/dist/coverage.d.ts

@@ -13,6 +13,7 @@ export declare const COVERED: {
     cancel_twap_order: string;
     create_twap_order: string;
     get_twap_order: string;
+    get_twap_order_tca: string;
     list_twap_orders: string;
     close_position: string;
     create_challenge: string;

package/dist/coverage.js

@@ -13,6 +13,7 @@ export const COVERED = {
     cancel_twap_order: "cancelTwapOrder",
     create_twap_order: "createTwapOrder",
     get_twap_order: "getTwapOrder",
+    get_twap_order_tca: "getTwapOrderTca",
     list_twap_orders: "listTwapOrders",
     close_position: "closePosition",
     create_challenge: "createChallenge",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.45",
+	"version": "1.0.46",
 	"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.45",
-		"@0xmonaco/types": "1.0.45",
+		"@0xmonaco/contracts": "1.0.46",
+		"@0xmonaco/types": "1.0.46",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"