@0xmonaco/core 1.0.64 → 1.0.66

package/dist/api/positions/api.d.ts

@@ -1,12 +1,24 @@
 import type { AttachPositionTpSlRequest, AttachPositionTpSlResponse, BatchCloseAllRequest, BatchCloseAllResponse, ClosePositionRequest, ClosePositionResponse, GetPositionPnlHistoryParams, GetPositionPnlHistoryResponse, GetPositionResponse, ListPositionHistoryParams, ListPositionHistoryResponse, ListPositionsParams, ListPositionsResponse, PositionRisk, PositionsAPI } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class PositionsAPIImpl extends BaseAPI implements PositionsAPI {
+    /**
+     * List the caller's positions with page-number pagination. The response
+     * `total` is bounded by the listing's pagination reach: exact up to
+     * `pageSize` x 10,000 rows and saturating there, so a `page` above 10,000 is
+     * rejected rather than served past the last page `total` can report.
+     */
     listPositions(params?: ListPositionsParams): Promise<ListPositionsResponse>;
     getPosition(positionId: string): Promise<GetPositionResponse>;
     closePosition(positionId: string, request: ClosePositionRequest): Promise<ClosePositionResponse>;
     batchCloseAllPositions(request?: BatchCloseAllRequest): Promise<BatchCloseAllResponse>;
     getPositionRisk(positionId: string): Promise<PositionRisk>;
     attachPositionTpSl(positionId: string, request: AttachPositionTpSlRequest): Promise<AttachPositionTpSlResponse>;
+    /**
+     * List the caller's position-history events with page-number pagination. The
+     * response `total` is bounded by the listing's pagination reach: exact up to
+     * `pageSize` x 10,000 rows and saturating there, so a `page` above 10,000 is
+     * rejected rather than served past the last page `total` can report.
+     */
     listPositionHistory(params?: ListPositionHistoryParams): Promise<ListPositionHistoryResponse>;
     getPositionPnlHistory(positionId: string, params: GetPositionPnlHistoryParams): Promise<GetPositionPnlHistoryResponse>;
 }

package/dist/api/positions/api.js

@@ -2,6 +2,12 @@ import { AttachPositionTpSlSchema, BatchCloseAllSchema, ClosePositionSchema, Get
 import { BaseAPI } from "../base";
 import { perpRoutes } from "../perp";
 export class PositionsAPIImpl extends BaseAPI {
+    /**
+     * List the caller's positions with page-number pagination. The response
+     * `total` is bounded by the listing's pagination reach: exact up to
+     * `pageSize` x 10,000 rows and saturating there, so a `page` above 10,000 is
+     * rejected rather than served past the last page `total` can report.
+     */
     async listPositions(params) {
         if (params) {
             validate(ListPositionsSchema, params);
@@ -69,10 +75,26 @@ export class PositionsAPIImpl extends BaseAPI {
                         expiresAt: request.stopLoss.expiresAt,
                     }
                     : undefined,
+                trailingStop: request.trailingStop
+                    ? {
+                        trailBps: request.trailingStop.trailBps,
+                        activationPrice: request.trailingStop.activationPrice,
+                        quantity: request.trailingStop.quantity,
+                        closePosition: request.trailingStop.closePosition,
+                        slippageToleranceBps: request.trailingStop.slippageToleranceBps,
+                        expiresAt: request.trailingStop.expiresAt,
+                    }
+                    : undefined,
                 oco: request.oco,
             }),
         });
     }
+    /**
+     * List the caller's position-history events with page-number pagination. The
+     * response `total` is bounded by the listing's pagination reach: exact up to
+     * `pageSize` x 10,000 rows and saturating there, so a `page` above 10,000 is
+     * rejected rather than served past the last page `total` can report.
+     */
     async listPositionHistory(params) {
         if (params) {
             validate(ListPositionHistorySchema, params);

package/dist/api/profile/api.d.ts

@@ -176,9 +176,10 @@ export declare class ProfileAPIImpl extends BaseAPI implements ProfileAPI {
      *
      * @param params - Optional query parameters for pagination and filtering
      * @param params.page - Deprecated: page number for legacy offset pagination (starts
-     * from 1). Passing it selects legacy page-number mode, which only sees recent (hot)
-     * history and populates `total`/`totalPages`. Use cursor pagination (`pageToken`)
-     * instead.
+     * from 1, at most 10,000). Passing it selects legacy page-number mode, which only sees
+     * recent (hot) history and populates `total`/`totalPages` — bounded at the pagination
+     * reach (`total` saturates at `pageSize` × 10,000 rows, `totalPages` at 10,000 pages).
+     * Use cursor pagination (`pageToken`) instead.
      * @param params.pageSize - Number of items per page (default: 20; max 100
      * in page-number mode, up to 1000 when pageToken is present)
      * @param params.tradingPairId - Filter by trading pair ID (UUID)

package/dist/api/profile/api.js

@@ -227,9 +227,10 @@ export class ProfileAPIImpl extends BaseAPI {
      *
      * @param params - Optional query parameters for pagination and filtering
      * @param params.page - Deprecated: page number for legacy offset pagination (starts
-     * from 1). Passing it selects legacy page-number mode, which only sees recent (hot)
-     * history and populates `total`/`totalPages`. Use cursor pagination (`pageToken`)
-     * instead.
+     * from 1, at most 10,000). Passing it selects legacy page-number mode, which only sees
+     * recent (hot) history and populates `total`/`totalPages` — bounded at the pagination
+     * reach (`total` saturates at `pageSize` × 10,000 rows, `totalPages` at 10,000 pages).
+     * Use cursor pagination (`pageToken`) instead.
      * @param params.pageSize - Number of items per page (default: 20; max 100
      * in page-number mode, up to 1000 when pageToken is present)
      * @param params.tradingPairId - Filter by trading pair ID (UUID)

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, GetTwapOrderTcaResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrdersParams, ListTwapOrdersResponse, MarginMode, OrderSide, ParentTpSlLegParams, PositionSide, ReplaceOrderResponse, SelfTradePreventionMode, 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, ParentTrailingStopLegParams, PositionSide, ReplaceOrderResponse, SelfTradePreventionMode, TimeInForce, TradingAPI, TradingMode, TwapOrder } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
@@ -94,6 +94,8 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         idempotencyKey?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
+        /** Trailing stop that arms when this order fully fills; margin entry orders only. */
+        trailingStop?: ParentTrailingStopLegParams;
     }): Promise<CreateOrderResponse>;
     /**
      * Places a market order for immediate execution.
@@ -152,6 +154,8 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         selfTradePreventionMode?: SelfTradePreventionMode;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
+        /** Trailing stop that arms when this order fully fills; margin entry orders only. */
+        trailingStop?: ParentTrailingStopLegParams;
         clientOrderId?: string;
         /** Generated once per call when omitted. Supply the same key to retry a logical order within 24 hours. */
         idempotencyKey?: string;
@@ -184,6 +188,19 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     }): Promise<CancelOrderResponse>;
     cancelConditionalOrder(conditionalOrderId: string): Promise<CancelConditionalOrderResponse>;
     getConditionalOrder(conditionalOrderId: string): Promise<ConditionalOrder>;
+    /**
+     * Lists conditional orders for the authenticated user.
+     *
+     * The response `total` is bounded by the listing's pagination reach: exact up
+     * to `pageSize` x 10,000 rows and saturating there, so a caller with more
+     * matching conditional orders than page-number mode can page through reads the
+     * cap, not its lifetime total; `page` is capped at 10,000 and a larger page is
+     * rejected.
+     *
+     * @param params - Optional pagination and margin-account / trading-pair / state filters
+     * @returns Promise resolving to ListConditionalOrdersResponse with orders and pagination info
+     * @throws {APIError} When API communication fails
+     */
     listConditionalOrders(params?: ListConditionalOrdersParams): Promise<ListConditionalOrdersResponse>;
     /**
      * Batch cancels specific orders by their IDs.
@@ -505,6 +522,12 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
      * Lists TWAP parent orders for the authenticated user.
      *
+     * The response `total` is bounded by the listing's pagination reach: exact up
+     * to `pageSize` x 10,000 rows and saturating there, so a caller with more
+     * matching TWAP orders than page-number mode can page through reads the cap,
+     * not its lifetime total; `page` is capped at 10,000 and a larger page is
+     * rejected.
+     *
      * @param params - Optional pagination and state / trading-pair filters
      * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails

package/dist/api/trading/api.js

@@ -41,6 +41,19 @@ function parentTpSlLegToRequest(leg) {
         closePosition: leg.closePosition,
     };
 }
+function parentTrailingStopLegToRequest(leg) {
+    if (!leg)
+        return undefined;
+    return {
+        trailBps: leg.trailBps,
+        activationPrice: leg.activationPrice,
+        // Same sizing contract as the TP/SL legs above — see the note there.
+        quantity: leg.quantity,
+        closePosition: leg.closePosition,
+        slippageToleranceBps: leg.slippageToleranceBps,
+        expiresAt: leg.expiresAt,
+    };
+}
 export class TradingAPIImpl extends BaseAPI {
     /**
      * Places a limit order on the order book.
@@ -125,6 +138,7 @@ export class TradingAPIImpl extends BaseAPI {
             idempotencyKey: options?.idempotencyKey === undefined ? crypto.randomUUID() : options.idempotencyKey,
             takeProfit: parentTpSlLegToRequest(options?.takeProfit),
             stopLoss: parentTpSlLegToRequest(options?.stopLoss),
+            trailingStop: parentTrailingStopLegToRequest(options?.trailingStop),
         };
         return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
             method: "POST",
@@ -201,6 +215,7 @@ export class TradingAPIImpl extends BaseAPI {
             selfTradePreventionMode: options?.selfTradePreventionMode,
             takeProfit: parentTpSlLegToRequest(options?.takeProfit),
             stopLoss: parentTpSlLegToRequest(options?.stopLoss),
+            trailingStop: parentTrailingStopLegToRequest(options?.trailingStop),
             clientOrderId: options?.clientOrderId,
             idempotencyKey: options?.idempotencyKey === undefined ? crypto.randomUUID() : options.idempotencyKey,
         };
@@ -258,6 +273,19 @@ export class TradingAPIImpl extends BaseAPI {
             method: "GET",
         });
     }
+    /**
+     * Lists conditional orders for the authenticated user.
+     *
+     * The response `total` is bounded by the listing's pagination reach: exact up
+     * to `pageSize` x 10,000 rows and saturating there, so a caller with more
+     * matching conditional orders than page-number mode can page through reads the
+     * cap, not its lifetime total; `page` is capped at 10,000 and a larger page is
+     * rejected.
+     *
+     * @param params - Optional pagination and margin-account / trading-pair / state filters
+     * @returns Promise resolving to ListConditionalOrdersResponse with orders and pagination info
+     * @throws {APIError} When API communication fails
+     */
     async listConditionalOrders(params) {
         if (params) {
             validate(ListConditionalOrdersSchema, params);
@@ -793,6 +821,12 @@ export class TradingAPIImpl extends BaseAPI {
     /**
      * Lists TWAP parent orders for the authenticated user.
      *
+     * The response `total` is bounded by the listing's pagination reach: exact up
+     * to `pageSize` x 10,000 rows and saturating there, so a caller with more
+     * matching TWAP orders than page-number mode can page through reads the cap,
+     * not its lifetime total; `page` is capped at 10,000 and a larger page is
+     * rejected.
+     *
      * @param params - Optional pagination and state / trading-pair filters
      * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails

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

@@ -1,5 +1,5 @@
 import type { MonacoWebSocketConfig, SessionCredentials } from "@0xmonaco/types";
-export type { MessageHandler, MonacoWebSocket, ResyncHandler, StatusHandler, WebSocketResyncInfo } from "@0xmonaco/types";
+export type { MessageHandler, MonacoWebSocket, ReauthenticationRequiredHandler, ResyncHandler, StatusHandler, WebSocketReauthenticationInfo, WebSocketResyncInfo, } from "@0xmonaco/types";
 /**
  * Options for {@link createMonacoWebSocket}. The reconnect/resync knobs and
  * callbacks are shared with the main SDK config via {@link MonacoWebSocketConfig}

package/dist/api/websocket/websocket.js

@@ -155,6 +155,13 @@ function parseConditionalOrderEventData(raw) {
         cancelledAt: readOptionalString(data, "cancelledAt"),
         expiresAt: readOptionalString(data, "expiresAt"),
         failureReason: readOptionalString(data, "failureReason"),
+        // Trailing-stop fields (0XM-2827), explicit `null` on TP/SL rows. A live
+        // `ratcheted` frame carries the moved `triggerPrice` together with the
+        // `watermarkPrice` it was derived from; none of these is validated.
+        trailBps: readOptionalNumber(data, "trailBps"),
+        activationPrice: readOptionalString(data, "activationPrice"),
+        watermarkPrice: readOptionalString(data, "watermarkPrice"),
+        trailArmedAt: readOptionalString(data, "trailArmedAt"),
         // 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"),
@@ -416,6 +423,15 @@ function parseInstrumentEventData(raw) {
         maxOrderSize: readString(data, "maxOrderSize"),
         marketType: readString(data, "marketType"),
         category: readString(data, "category"),
+        // Present-as-null on the wire: the server always sends both keys, carrying an
+        // explicit `null` when an asset has no icon. Read tolerantly — a missing key
+        // maps to `null` rather than dropping the frame — because the instrument
+        // channel must never drop a frame (a dropped frame can hide a market going
+        // inactive, 0XM-2628), and a cosmetic icon is safe to treat as absent. Unlike
+        // `readNullableString`, this does not reject a missing key; a present
+        // non-string value still throws.
+        baseIconUrl: readOptionalString(data, "baseIconUrl") ?? null,
+        quoteIconUrl: readOptionalString(data, "quoteIconUrl") ?? null,
         maxLeverage: readOptionalString(data, "maxLeverage"),
         initialMarginRate: readOptionalString(data, "initialMarginRate"),
         maintenanceMarginRate: readOptionalString(data, "maintenanceMarginRate"),
@@ -674,6 +690,15 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
     // Close code of the connection loss the next successful reopen recovers
     // from; null when no resync is owed (first connect, clean disconnect).
     let pendingResyncCode = null;
+    // Authentication-ending Error frame received on the current socket, tagged
+    // with the session it rejected. The server answers handshakes in the order
+    // they were sent, so each Authenticated / AUTH_FAILED reply belongs to the
+    // oldest pending handshake, and SESSION_INVALID revokes the session the
+    // server last confirmed. All of it resets per socket so a frame from one
+    // connection never decides how a later connection's close is read.
+    let lastAuthError = null;
+    let pendingAuthSessions = [];
+    let confirmedSession;
     // 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
@@ -723,6 +748,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             return;
         const timestamp = Date.now();
         const signature = signMessage(hexToBytes(session.privateKey), composeWsSigningString(session.publicKey, timestamp));
+        pendingAuthSessions.push(session);
         ws.send(JSON.stringify({
             type: "Authenticate",
             public_key: session.publicKey,
@@ -822,8 +848,8 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
     };
     const routeMessage = (msg) => {
         if (msg.type === "Error") {
-            // Connection-scoped, not channel-scoped: an Error frame matches no
-            // subscription, so without this it reached no consumer at all and a
+            // An Error frame matches no subscription even when it names a channel,
+            // so without this it reached no consumer at all and a
             // failed subscribe / invalidated session / unreadable subscribe-time
             // snapshot was silent. `code` is passed through whatever its value —
             // a code added server-side after this SDK shipped must still reach the
@@ -832,10 +858,31 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             // and synthesizing the missing half would send the app down a branch on
             // data the server never sent.
             if (typeof msg.code === "string" && typeof msg.message === "string") {
-                options.onError?.({ code: msg.code, message: msg.message });
+                // The server sends the reason a connection is ending as an Error
+                // frame just before the close; the close event decides from it.
+                // Recorded before any application code runs, so a throwing onError
+                // cannot make the close look transient.
+                if (msg.code === "AUTH_FAILED") {
+                    lastAuthError = { code: msg.code, message: msg.message, session: pendingAuthSessions.shift() };
+                }
+                else if (msg.code === "SESSION_INVALID") {
+                    lastAuthError = { code: msg.code, message: msg.message, session: confirmedSession ?? pendingAuthSessions[0] };
+                }
+                // A per-channel failure names the channel it concerns; the key is
+                // left off entirely otherwise, so a connection-wide failure reaches
+                // the app exactly as the server sent it. A non-string channel is
+                // dropped rather than the frame: the code and message are still
+                // actionable without it. (The frame is untyped JSON, so the declared
+                // `string` type of `channel` is not trusted here.)
+                const channel = msg.channel;
+                options.onError?.(typeof channel === "string" ? { code: msg.code, message: msg.message, channel } : { code: msg.code, message: msg.message });
             }
             return;
         }
+        if (msg.type === "Authenticated") {
+            confirmedSession = pendingAuthSessions.shift();
+            return;
+        }
         if (!msg.channel)
             return;
         if (msg.type === "Snapshot") {
@@ -867,6 +914,9 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             try {
                 const socket = new WebSocket(getUrl());
                 ws = socket;
+                lastAuthError = null;
+                pendingAuthSessions = [];
+                confirmedSession = undefined;
                 const timeout = setTimeout(() => {
                     if (ws !== socket) {
                         resolve();
@@ -938,6 +988,56 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                     }
                     ws = null;
                     stopHeartbeat();
+                    // Terminal authentication loss: the server revoked the session
+                    // (SESSION_INVALID, then 1008) or rejected this connection's
+                    // handshake (AUTH_FAILED, then a close). Reconnecting would replay
+                    // the same rejected credentials into the same rejection forever, so
+                    // drop them, skip the reconnect, and let the app supply a fresh
+                    // session. Handlers stay registered so that session resubscribes
+                    // them. A 1008 without SESSION_INVALID (the message-rate cap) is a
+                    // back-off-and-retry and falls through to the reconnect below, as
+                    // does a close after the app already replaced the rejected session
+                    // (e.g. re-authenticating from onError): the fresh session is what
+                    // the reconnect uses.
+                    const authError = lastAuthError;
+                    const authLoss = authError !== null && authError.session !== undefined && (authError.code === "AUTH_FAILED" || event.code === 1008);
+                    const terminalAuthLoss = authLoss && session === authError.session;
+                    if (terminalAuthLoss) {
+                        session = undefined;
+                        // The reopen with a fresh session still owes the app a resync —
+                        // nothing was delivered while the session was dead — whether or
+                        // not automatic reconnect is on, since that reopen is driven by
+                        // the new session, not by the reconnect loop.
+                        if (pendingResyncCode === null) {
+                            pendingResyncCode = event.code;
+                        }
+                        try {
+                            options.onStatusChange?.("disconnected");
+                        }
+                        finally {
+                            // Recovery must not hinge on the status observer not throwing.
+                            options.onReauthenticationRequired?.({ code: authError.code, message: authError.message, closeCode: event.code });
+                        }
+                        return;
+                    }
+                    // The app already handed over a replacement session on this socket.
+                    // Had it arrived after the close, setSessionKeypair would have
+                    // connected with it; honour that even with automatic reconnect off
+                    // (with it on, the reconnect below uses the new session).
+                    if (authLoss && session !== undefined && !autoReconnect) {
+                        if (pendingResyncCode === null) {
+                            pendingResyncCode = event.code;
+                        }
+                        try {
+                            options.onStatusChange?.("disconnected");
+                        }
+                        finally {
+                            connect().catch((err) => {
+                                console.warn("WebSocket: Failed to connect with the replacement session:", err);
+                            });
+                        }
+                        return;
+                    }
                     // Reconnect on abnormal close. 1013 is the server's slow-client
                     // shed: the stream has a gap, so the reopen owes the app a resync.
                     // Keep the first owed code (upgrading to 1013 if it arrives later):

package/package.json

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