@0xmonaco/core 1.0.65 → 1.0.67

package/dist/api/base.d.ts

@@ -22,6 +22,7 @@
  */
 import type { RequestSigning, SessionCredentials } from "@0xmonaco/types";
 import { type SessionKeypair } from "../crypto/session";
+import { ServerClock } from "../utils/server-clock";
 export interface RetryOptions {
     maxRetries?: number;
     baseDelayMs?: number;
@@ -33,9 +34,13 @@ export declare abstract class BaseAPI {
     /** Application secret key (`sk_...`) sent in the `x-server-key` header for backend-authenticated requests. */
     protected serverKey?: string;
     private requestSigning;
+    /** Server time learned from responses; signing timestamps are read from it. */
+    protected serverClock: ServerClock;
     /** Opt in only after the target server supports RFC 9421. No automatic downgrade. */
     setRequestSigning(protocol: RequestSigning): void;
     protected retryOptions: Required<RetryOptions>;
+    /** Share one server clock across API instances so any response calibrates all of them. */
+    setServerClock(clock: ServerClock): void;
     /**
      * Creates a new BaseAPI instance.
      *

package/dist/api/base.js

@@ -25,6 +25,8 @@ import { StatusCodes } from "http-status-codes";
 import { buildHttpSignatureHeaders } from "../crypto/http-signatures";
 import { composeSigningString, keypairFromHex, sha256Hex, signMessage } from "../crypto/session";
 import { APIError } from "../errors";
+import { parseHttpDate } from "../utils/http-date";
+import { CLOCK_CORRECTION_THRESHOLD_MS, ServerClock } from "../utils/server-clock";
 /**
  * Product token sent as the `User-Agent` on every request. Monaco's edge
  * rejects requests with an empty or absent `User-Agent`, so we set one
@@ -35,112 +37,6 @@ import { APIError } from "../errors";
  * only takes effect in server runtimes (Node/undici, Bun, Deno).
  */
 const SDK_USER_AGENT = "@0xmonaco/core";
-const MONTHS = {
-    Jan: 0,
-    Feb: 1,
-    Mar: 2,
-    Apr: 3,
-    May: 4,
-    Jun: 5,
-    Jul: 6,
-    Aug: 7,
-    Sep: 8,
-    Oct: 9,
-    Nov: 10,
-    Dec: 11,
-};
-// The three RFC 7231 §7.1.1.1 `HTTP-date` grammars a recipient must accept.
-// Each is anchored so trailing junk is rejected, and `Date.parse` is avoided
-// entirely (it is permissive — it reads asctime in local time and rolls
-// impossible dates like 31 Feb forward instead of rejecting them).
-const MONTH = "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec";
-const IMF_FIXDATE = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\\d{2}) (${MONTH}) (\\d{4}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
-const RFC850_DATE = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\\d{2})-(${MONTH})-(\\d{2}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
-const ASCTIME_DATE = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (${MONTH}) ([ \\d]\\d) (\\d{2}):(\\d{2}):(\\d{2}) (\\d{4})$`);
-/**
- * Expand an RFC 850 two-digit year per RFC 7231 §7.1.1.1: a full timestamp that
- * appears more than 50 years in the future is interpreted as the most recent
- * past year with the same last two digits. The comparison is against the exact
- * receipt instant plus 50 years (not just calendar years), so the boundary can
- * fall mid-year — e.g. received 2026-06-01, `31-Dec-76` is 50y7m ahead and maps
- * to 1976, while `01-Jan-76` is under 50 years ahead and stays 2076.
- */
-function expandTwoDigitYear(twoDigitYear, month, day, hour, minute, second) {
-    const now = new Date(Date.now());
-    const candidateYear = Math.floor(now.getUTCFullYear() / 100) * 100 + twoDigitYear;
-    const candidate = Date.UTC(candidateYear, month, day, hour, minute, second);
-    const fiftyYearsAhead = Date.UTC(now.getUTCFullYear() + 50, now.getUTCMonth(), now.getUTCDate(), now.getUTCHours(), now.getUTCMinutes(), now.getUTCSeconds());
-    return candidate > fiftyYearsAhead ? candidateYear - 100 : candidateYear;
-}
-/**
- * Parse an RFC 7231 `HTTP-date` — in any of the three formats a recipient must
- * accept (IMF-fixdate, the obsolete RFC 850 form, and asctime) — into a UTC
- * epoch in milliseconds, or `undefined` if the value is not a well-formed, real
- * calendar date. All three denote UTC, so timestamps are built with `Date.UTC`
- * and the fields are round-tripped to reject impossible dates such as
- * `31 Feb` or `25:00:00`. RFC 850's 2-digit year follows the RFC 7231 rule
- * (see {@link expandTwoDigitYear}). The redundant day-name is intentionally not
- * validated against the date — RFC 7231 encourages robust parsing, and the
- * date/time fields already determine the instant unambiguously, so a mismatched
- * weekday still yields the intended delay rather than a dropped header and an
- * arbitrary fallback.
- */
-function parseHttpDate(value) {
-    let day;
-    let month;
-    let year;
-    let hour;
-    let minute;
-    let second;
-    const imf = IMF_FIXDATE.exec(value);
-    const rfc850 = RFC850_DATE.exec(value);
-    const asctime = ASCTIME_DATE.exec(value);
-    if (imf) {
-        day = Number(imf[1]);
-        month = MONTHS[imf[2]];
-        year = Number(imf[3]);
-        hour = Number(imf[4]);
-        minute = Number(imf[5]);
-        second = Number(imf[6]);
-    }
-    else if (rfc850) {
-        day = Number(rfc850[1]);
-        month = MONTHS[rfc850[2]];
-        hour = Number(rfc850[4]);
-        minute = Number(rfc850[5]);
-        second = Number(rfc850[6]);
-        if (month === undefined)
-            return undefined;
-        year = expandTwoDigitYear(Number(rfc850[3]), month, day, hour, minute, second);
-    }
-    else if (asctime) {
-        month = MONTHS[asctime[1]];
-        day = Number((asctime[2] ?? "").trim());
-        hour = Number(asctime[3]);
-        minute = Number(asctime[4]);
-        second = Number(asctime[5]);
-        year = Number(asctime[6]);
-    }
-    else {
-        return undefined;
-    }
-    if (month === undefined)
-        return undefined;
-    const timestamp = Date.UTC(year, month, day, hour, minute, second);
-    const utc = new Date(timestamp);
-    // Reject impossible calendar/clock values that Date.UTC silently rolls over
-    // (e.g. 31 Feb, 25:00:00). A `:60` leap second is likewise dropped rather
-    // than special-cased — leap seconds never appear in a Retry-After header.
-    if (utc.getUTCFullYear() !== year ||
-        utc.getUTCMonth() !== month ||
-        utc.getUTCDate() !== day ||
-        utc.getUTCHours() !== hour ||
-        utc.getUTCMinutes() !== minute ||
-        utc.getUTCSeconds() !== second) {
-        return undefined;
-    }
-    return timestamp;
-}
 export class BaseAPI {
     apiUrl;
     /** Active session keypair (raw bytes) used to sign authenticated requests. */
@@ -148,6 +44,8 @@ export class BaseAPI {
     /** Application secret key (`sk_...`) sent in the `x-server-key` header for backend-authenticated requests. */
     serverKey;
     requestSigning = "legacy";
+    /** Server time learned from responses; signing timestamps are read from it. */
+    serverClock = new ServerClock();
     /** Opt in only after the target server supports RFC 9421. No automatic downgrade. */
     setRequestSigning(protocol) {
         if (protocol !== "legacy" && protocol !== "rfc9421")
@@ -155,6 +53,10 @@ export class BaseAPI {
         this.requestSigning = protocol;
     }
     retryOptions;
+    /** Share one server clock across API instances so any response calibrates all of them. */
+    setServerClock(clock) {
+        this.serverClock = clock;
+    }
     /**
      * Creates a new BaseAPI instance.
      *
@@ -293,6 +195,7 @@ export class BaseAPI {
                 requestBody,
             });
         }
+        this.serverClock.observeResponse(response.headers, Date.now());
         // Parse response body with error handling for non-JSON responses
         let responseBody;
         const contentType = response.headers?.get("content-type") || "unknown";
@@ -396,7 +299,6 @@ export class BaseAPI {
         }
         const url = `${this.apiUrl}${endpoint}`;
         const requestBody = this.parseRequestBody(options.body);
-        const signatureHeaders = this.buildSignatureHeaders(endpoint, options);
         let extraHeaders = options.headers;
         if (this.requestSigning === "rfc9421") {
             const normalized = {};
@@ -405,15 +307,28 @@ export class BaseAPI {
             });
             extraHeaders = normalized;
         }
-        return this.executeRequest(url, endpoint, {
+        const send = () => this.executeRequest(url, endpoint, {
             ...options,
             ...(this.requestSigning === "rfc9421" ? { redirect: "error" } : {}),
             headers: {
                 "Content-Type": "application/json",
                 ...extraHeaders,
-                ...signatureHeaders,
+                ...this.buildSignatureHeaders(endpoint, options),
             },
         }, requestBody);
+        // A 401 whose response moved the server clock was most likely a
+        // timestamp-skew rejection: re-sign once with the corrected time.
+        const offsetBefore = this.serverClock.offsetMs;
+        try {
+            return await send();
+        }
+        catch (error) {
+            const clockMoved = Math.abs(this.serverClock.offsetMs - offsetBefore) >= CLOCK_CORRECTION_THRESHOLD_MS;
+            if (error instanceof APIError && error.statusCode === StatusCodes.UNAUTHORIZED && clockMoved) {
+                return send();
+            }
+            throw error;
+        }
     }
     /**
      * Compute the per-request ed25519 signature headers.
@@ -441,9 +356,9 @@ export class BaseAPI {
                     throw new Error("Signature headers are managed by the SDK");
             }
             const url = new URL(`${this.apiUrl}${endpoint}`);
-            return buildHttpSignatureHeaders(this.sessionKeypair, method, url.pathname + url.search, utf8ToBytes(options.body ?? ""), Math.floor(Date.now() / 1000));
+            return buildHttpSignatureHeaders(this.sessionKeypair, method, url.pathname + url.search, utf8ToBytes(options.body ?? ""), Math.floor(this.serverClock.now() / 1000));
         }
-        const timestampMs = Date.now();
+        const timestampMs = this.serverClock.now();
         const bodyBytes = typeof options.body === "string" ? utf8ToBytes(options.body) : new Uint8Array(0);
         const bodyHash = sha256Hex(bodyBytes);
         const signingString = composeSigningString(method, endpoint, timestampMs, bodyHash);

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

@@ -23,6 +23,7 @@ export declare const perpRoutes: {
             state?: string;
             page?: number;
             pageSize?: number;
+            pageToken?: string;
         }) => string;
         readonly cancelConditional: (conditionalOrderId: string) => string;
         readonly getConditional: (conditionalOrderId: string) => string;
@@ -32,6 +33,7 @@ export declare const perpRoutes: {
             tradingPairId?: string;
             page?: number;
             pageSize?: number;
+            pageToken?: string;
         }) => string;
         readonly getTwap: (twapOrderId: string) => string;
         readonly getTwapTca: (twapOrderId: string) => string;

package/dist/api/positions/api.js

@@ -75,6 +75,16 @@ 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,
             }),
         });

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;
@@ -187,13 +191,20 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
      * 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.
+     * Cursor (pageToken) pagination is the default: when neither `page` nor
+     * `pageToken` is passed, the SDK drives a cursor walk (it sends
+     * `pageToken=""`), which seeks on `(createdAt, id)` newest-first and resumes
+     * via each response's `nextPageToken` until that token comes back empty. A
+     * cursor page size may go up to 1000.
      *
-     * @param params - Optional pagination and margin-account / trading-pair / state filters
+     * Passing the deprecated `page` (without `pageToken`) selects legacy
+     * page-number mode instead, which keeps the 100 page-size cap and populates a
+     * bounded `total` (exact up to `pageSize` x 10,000 rows, saturating there);
+     * `page` is capped at 10,000. Cursor mode returns `total`/`page` as 0 and runs
+     * no COUNT.
+     *
+     * @param params - Optional filters and pagination; `pageToken` drives cursor
+     * mode, `page` drives the deprecated legacy mode
      * @returns Promise resolving to ListConditionalOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails
      */
@@ -518,20 +529,27 @@ 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.
+     * Cursor (pageToken) pagination is the default: when neither `page` nor
+     * `pageToken` is passed, the SDK drives a cursor walk (it sends
+     * `pageToken=""`), which seeks on `(createdAt, id)` newest-first and resumes
+     * via each response's `nextPageToken` until that token comes back empty. A
+     * cursor page size may go up to 1000.
+     *
+     * Passing the deprecated `page` (without `pageToken`) selects legacy
+     * page-number mode instead, which keeps the 100 page-size cap and populates a
+     * bounded `total` (exact up to `pageSize` x 10,000 rows, saturating there);
+     * `page` is capped at 10,000. Cursor mode returns `total`/`page` as 0 and runs
+     * no COUNT.
      *
-     * @param params - Optional pagination and state / trading-pair filters
+     * @param params - Optional filters and pagination; `pageToken` drives cursor
+     * mode, `page` drives the deprecated legacy mode
      * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails
      *
      * @example
      * ```typescript
      * const active = await tradingAPI.listTwapOrders({ state: "ACTIVE", pageSize: 50 });
-     * console.log(`Found ${active.total} active TWAP orders`);
+     * console.log(`Found ${active.orders.length} active TWAP orders`);
      * ```
      */
     listTwapOrders(params?: ListTwapOrdersParams): Promise<ListTwapOrdersResponse>;

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,
         };
@@ -261,13 +276,20 @@ export class TradingAPIImpl extends BaseAPI {
     /**
      * 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.
+     * Cursor (pageToken) pagination is the default: when neither `page` nor
+     * `pageToken` is passed, the SDK drives a cursor walk (it sends
+     * `pageToken=""`), which seeks on `(createdAt, id)` newest-first and resumes
+     * via each response's `nextPageToken` until that token comes back empty. A
+     * cursor page size may go up to 1000.
      *
-     * @param params - Optional pagination and margin-account / trading-pair / state filters
+     * Passing the deprecated `page` (without `pageToken`) selects legacy
+     * page-number mode instead, which keeps the 100 page-size cap and populates a
+     * bounded `total` (exact up to `pageSize` x 10,000 rows, saturating there);
+     * `page` is capped at 10,000. Cursor mode returns `total`/`page` as 0 and runs
+     * no COUNT.
+     *
+     * @param params - Optional filters and pagination; `pageToken` drives cursor
+     * mode, `page` drives the deprecated legacy mode
      * @returns Promise resolving to ListConditionalOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails
      */
@@ -275,13 +297,24 @@ export class TradingAPIImpl extends BaseAPI {
         if (params) {
             validate(ListConditionalOrdersSchema, params);
         }
-        const { page = 1, pageSize = 20, marginAccountId, tradingPairId, state } = params || {};
+        const { page, pageSize = 20, marginAccountId, tradingPairId, state, pageToken } = params || {};
+        // Legacy offset mode only when the caller explicitly asked for a page and no
+        // cursor was given; everything else drives cursor (pageToken) mode.
+        const legacyOffsetMode = page !== undefined && pageToken === undefined;
+        // Cursor requests may use pages up to 1000 (keyset reads); page-number
+        // requests keep the server's 100 cap.
+        const boundedPageSize = Math.min(Math.max(pageSize, 1), legacyOffsetMode ? 100 : 1000);
         return await this.makeAuthenticatedRequest(perpRoutes.orders.listConditional({
-            page,
-            pageSize: Math.min(Math.max(pageSize, 1), 100),
             marginAccountId,
             tradingPairId,
             state,
+            // Legacy mode sends `page` and omits `pageToken`; cursor mode omits
+            // `page` and sends `pageToken` — present even as the empty string, the
+            // documented way to start a walk (the server selects cursor mode by the
+            // token's presence, not its value).
+            page: legacyOffsetMode ? page : undefined,
+            pageSize: boundedPageSize,
+            pageToken: legacyOffsetMode ? undefined : (pageToken ?? ""),
         }), { method: "GET" });
     }
     /**
@@ -806,32 +839,50 @@ 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.
+     * Cursor (pageToken) pagination is the default: when neither `page` nor
+     * `pageToken` is passed, the SDK drives a cursor walk (it sends
+     * `pageToken=""`), which seeks on `(createdAt, id)` newest-first and resumes
+     * via each response's `nextPageToken` until that token comes back empty. A
+     * cursor page size may go up to 1000.
      *
-     * @param params - Optional pagination and state / trading-pair filters
+     * Passing the deprecated `page` (without `pageToken`) selects legacy
+     * page-number mode instead, which keeps the 100 page-size cap and populates a
+     * bounded `total` (exact up to `pageSize` x 10,000 rows, saturating there);
+     * `page` is capped at 10,000. Cursor mode returns `total`/`page` as 0 and runs
+     * no COUNT.
+     *
+     * @param params - Optional filters and pagination; `pageToken` drives cursor
+     * mode, `page` drives the deprecated legacy mode
      * @returns Promise resolving to ListTwapOrdersResponse with orders and pagination info
      * @throws {APIError} When API communication fails
      *
      * @example
      * ```typescript
      * const active = await tradingAPI.listTwapOrders({ state: "ACTIVE", pageSize: 50 });
-     * console.log(`Found ${active.total} active TWAP orders`);
+     * console.log(`Found ${active.orders.length} active TWAP orders`);
      * ```
      */
     async listTwapOrders(params) {
         if (params) {
             validate(ListTwapOrdersSchema, params);
         }
-        const { page = 1, pageSize = 20, state, tradingPairId } = params || {};
+        const { page, pageSize = 20, state, tradingPairId, pageToken } = params || {};
+        // Legacy offset mode only when the caller explicitly asked for a page and no
+        // cursor was given; everything else drives cursor (pageToken) mode.
+        const legacyOffsetMode = page !== undefined && pageToken === undefined;
+        // Cursor requests may use pages up to 1000 (keyset reads); page-number
+        // requests keep the server's 100 cap.
+        const boundedPageSize = Math.min(Math.max(pageSize, 1), legacyOffsetMode ? 100 : 1000);
         return await this.makeAuthenticatedRequest(perpRoutes.orders.listTwap({
-            page,
-            pageSize: Math.min(Math.max(pageSize, 1), 100),
             state,
             tradingPairId,
+            // Legacy mode sends `page` and omits `pageToken`; cursor mode omits
+            // `page` and sends `pageToken` — present even as the empty string, the
+            // documented way to start a walk (the server selects cursor mode by the
+            // token's presence, not its value).
+            page: legacyOffsetMode ? page : undefined,
+            pageSize: boundedPageSize,
+            pageToken: legacyOffsetMode ? undefined : (pageToken ?? ""),
         }), { method: "GET" });
     }
 }

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.d.ts

@@ -1,5 +1,10 @@
+import { ServerClock } from "../../utils/server-clock";
 import type { MonacoWebSocket, MonacoWebSocketOptions } from "./types";
 /**
  * Create a Monaco WebSocket client
+ *
+ * @param serverClock - Server time used to stamp the auth handshake; the SDK
+ *   passes the clock its REST clients calibrate so a skewed device clock does
+ *   not fail authentication.
  */
-export declare function createMonacoWebSocket(baseUrl: string, options?: MonacoWebSocketOptions): MonacoWebSocket;
+export declare function createMonacoWebSocket(baseUrl: string, options?: MonacoWebSocketOptions, serverClock?: ServerClock): MonacoWebSocket;

package/dist/api/websocket/websocket.js

@@ -1,12 +1,21 @@
 import { hexToBytes } from "@noble/hashes/utils.js";
 import { composeWsSigningString, signMessage } from "../../crypto/session";
 import { ALL_MAGNITUDES } from "../../utils";
+import { ServerClock } from "../../utils/server-clock";
 import { keysToCamelCase } from "./utils";
 // Connection constants
 const CONNECTION_TIMEOUT = 10000;
 const HEARTBEAT_INTERVAL = 15000;
 const MAX_RECONNECT_DELAY = 30000;
 const RECONNECT_BASE_DELAY = 1000;
+/**
+ * Handshakes rejected for timestamp skew that are retried before the session
+ * is treated as lost. A restored session can authenticate before any REST
+ * response has calibrated the server clock; each retry re-signs with
+ * whatever the clock has learned since.
+ */
+const MAX_SKEW_AUTH_RETRIES = 3;
+const SKEW_REJECTION = /timestamp outside allowed skew/i;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -155,9 +164,21 @@ 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"),
+        // Sent on every frame by current servers, but read optionally: a frame
+        // from an older deployment during a rolling release omits it, and a
+        // `readString` there would throw inside the message handler and drop the
+        // update.
+        createdAt: readOptionalString(data, "createdAt"),
         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
@@ -662,8 +683,12 @@ function snapshotFrameHandler(channel, parseItem, onSnapshot) {
 }
 /**
  * Create a Monaco WebSocket client
+ *
+ * @param serverClock - Server time used to stamp the auth handshake; the SDK
+ *   passes the clock its REST clients calibrate so a skewed device clock does
+ *   not fail authentication.
  */
-export function createMonacoWebSocket(baseUrl, options = {}) {
+export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new ServerClock()) {
     let ws = null;
     let session = options.session;
     let reconnectAttempts = 0;
@@ -683,6 +708,17 @@ 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 = [];
+    // Consecutive handshakes rejected for clock skew; reset on success.
+    let skewAuthRetries = 0;
+    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
@@ -730,8 +766,9 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
     const sendAuthenticate = () => {
         if (!session || ws?.readyState !== WebSocket.OPEN)
             return;
-        const timestamp = Date.now();
+        const timestamp = serverClock.now();
         const signature = signMessage(hexToBytes(session.privateKey), composeWsSigningString(session.publicKey, timestamp));
+        pendingAuthSessions.push(session);
         ws.send(JSON.stringify({
             type: "Authenticate",
             public_key: session.publicKey,
@@ -831,8 +868,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
@@ -841,10 +878,32 @@ 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();
+            skewAuthRetries = 0;
+            return;
+        }
         if (!msg.channel)
             return;
         if (msg.type === "Snapshot") {
@@ -876,6 +935,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();
@@ -947,6 +1009,62 @@ 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;
+                    // A handshake stamped outside the server's window is a clock
+                    // problem, not a dead session: reconnect and re-sign, a bounded
+                    // number of times, instead of discarding the credentials.
+                    const skewRetry = autoReconnect && authError?.code === "AUTH_FAILED" && SKEW_REJECTION.test(authError.message) && skewAuthRetries < MAX_SKEW_AUTH_RETRIES;
+                    if (skewRetry)
+                        skewAuthRetries++;
+                    const authLoss = !skewRetry && 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):
@@ -1574,6 +1692,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         getStatus,
         setSessionKeypair: (credentials) => {
             session = credentials ?? undefined;
+            skewAuthRetries = 0;
             // If already connected, (re)send the signed handshake so the connection
             // picks up the new session without tearing down. If not yet connected,
             // onopen will send it. Clearing the session leaves the connection up for

package/dist/sdk.js

@@ -24,6 +24,7 @@ import { WithdrawalsAPIImpl } from "./api/withdrawals";
 import { generateSessionKeypair, privateKeyHex, publicKeyHex } from "./crypto/session";
 import { APIError, InvalidConfigError, InvalidStateError } from "./errors";
 import { resolveApiUrl, resolveWsUrl } from "./networks";
+import { ServerClock } from "./utils/server-clock";
 /**
  * Default receipt-polling frequency for the SDK's internal viem public client.
  * Sei produces sub-second blocks, so viem's 4000ms default adds seconds of
@@ -189,8 +190,10 @@ export class MonacoSDKImpl {
             this.walletClient = cfg.walletClient;
         }
         // Instantiate APIs (wallet-dependent APIs will be initialized lazily or error if wallet not set)
+        const serverClock = new ServerClock();
         const configureSigning = (api) => {
             api.setRequestSigning(cfg.requestSigning ?? "legacy");
+            api.setServerClock(serverClock);
             return api;
         };
         this.applications = configureSigning(new ApplicationsAPIImpl(apiUrl));
@@ -218,7 +221,7 @@ export class MonacoSDKImpl {
         // Thread the reconnect/resync knobs and callbacks from SDK config into the
         // internally-built ws client. The session keypair is not passed here — it
         // is propagated on login via propagateSession/setSessionKeypair.
-        this.ws = createMonacoWebSocket(wsUrl, cfg.ws);
+        this.ws = createMonacoWebSocket(wsUrl, cfg.ws, serverClock);
         // Auto-connect WebSocket, log errors
         this.ws.connect().catch(console.error);
     }

package/dist/utils/http-date.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse an RFC 7231 `HTTP-date` — in any of the three formats a recipient must
+ * accept (IMF-fixdate, the obsolete RFC 850 form, and asctime) — into a UTC
+ * epoch in milliseconds, or `undefined` if the value is not a well-formed, real
+ * calendar date. All three denote UTC, so timestamps are built with `Date.UTC`
+ * and the fields are round-tripped to reject impossible dates such as
+ * `31 Feb` or `25:00:00`. RFC 850's 2-digit year follows the RFC 7231 rule
+ * (see {@link expandTwoDigitYear}). The redundant day-name is intentionally not
+ * validated against the date — RFC 7231 encourages robust parsing, and the
+ * date/time fields already determine the instant unambiguously, so a mismatched
+ * weekday still yields the intended delay rather than a dropped header and an
+ * arbitrary fallback.
+ */
+export declare function parseHttpDate(value: string): number | undefined;

package/dist/utils/http-date.js

@@ -0,0 +1,106 @@
+const MONTHS = {
+    Jan: 0,
+    Feb: 1,
+    Mar: 2,
+    Apr: 3,
+    May: 4,
+    Jun: 5,
+    Jul: 6,
+    Aug: 7,
+    Sep: 8,
+    Oct: 9,
+    Nov: 10,
+    Dec: 11,
+};
+// The three RFC 7231 §7.1.1.1 `HTTP-date` grammars a recipient must accept.
+// Each is anchored so trailing junk is rejected, and `Date.parse` is avoided
+// entirely (it is permissive — it reads asctime in local time and rolls
+// impossible dates like 31 Feb forward instead of rejecting them).
+const MONTH = "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec";
+const IMF_FIXDATE = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\\d{2}) (${MONTH}) (\\d{4}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+const RFC850_DATE = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\\d{2})-(${MONTH})-(\\d{2}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+const ASCTIME_DATE = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (${MONTH}) ([ \\d]\\d) (\\d{2}):(\\d{2}):(\\d{2}) (\\d{4})$`);
+/**
+ * Expand an RFC 850 two-digit year per RFC 7231 §7.1.1.1: a full timestamp that
+ * appears more than 50 years in the future is interpreted as the most recent
+ * past year with the same last two digits. The comparison is against the exact
+ * receipt instant plus 50 years (not just calendar years), so the boundary can
+ * fall mid-year — e.g. received 2026-06-01, `31-Dec-76` is 50y7m ahead and maps
+ * to 1976, while `01-Jan-76` is under 50 years ahead and stays 2076.
+ */
+function expandTwoDigitYear(twoDigitYear, month, day, hour, minute, second) {
+    const now = new Date(Date.now());
+    const candidateYear = Math.floor(now.getUTCFullYear() / 100) * 100 + twoDigitYear;
+    const candidate = Date.UTC(candidateYear, month, day, hour, minute, second);
+    const fiftyYearsAhead = Date.UTC(now.getUTCFullYear() + 50, now.getUTCMonth(), now.getUTCDate(), now.getUTCHours(), now.getUTCMinutes(), now.getUTCSeconds());
+    return candidate > fiftyYearsAhead ? candidateYear - 100 : candidateYear;
+}
+/**
+ * Parse an RFC 7231 `HTTP-date` — in any of the three formats a recipient must
+ * accept (IMF-fixdate, the obsolete RFC 850 form, and asctime) — into a UTC
+ * epoch in milliseconds, or `undefined` if the value is not a well-formed, real
+ * calendar date. All three denote UTC, so timestamps are built with `Date.UTC`
+ * and the fields are round-tripped to reject impossible dates such as
+ * `31 Feb` or `25:00:00`. RFC 850's 2-digit year follows the RFC 7231 rule
+ * (see {@link expandTwoDigitYear}). The redundant day-name is intentionally not
+ * validated against the date — RFC 7231 encourages robust parsing, and the
+ * date/time fields already determine the instant unambiguously, so a mismatched
+ * weekday still yields the intended delay rather than a dropped header and an
+ * arbitrary fallback.
+ */
+export function parseHttpDate(value) {
+    let day;
+    let month;
+    let year;
+    let hour;
+    let minute;
+    let second;
+    const imf = IMF_FIXDATE.exec(value);
+    const rfc850 = RFC850_DATE.exec(value);
+    const asctime = ASCTIME_DATE.exec(value);
+    if (imf) {
+        day = Number(imf[1]);
+        month = MONTHS[imf[2]];
+        year = Number(imf[3]);
+        hour = Number(imf[4]);
+        minute = Number(imf[5]);
+        second = Number(imf[6]);
+    }
+    else if (rfc850) {
+        day = Number(rfc850[1]);
+        month = MONTHS[rfc850[2]];
+        hour = Number(rfc850[4]);
+        minute = Number(rfc850[5]);
+        second = Number(rfc850[6]);
+        if (month === undefined)
+            return undefined;
+        year = expandTwoDigitYear(Number(rfc850[3]), month, day, hour, minute, second);
+    }
+    else if (asctime) {
+        month = MONTHS[asctime[1]];
+        day = Number((asctime[2] ?? "").trim());
+        hour = Number(asctime[3]);
+        minute = Number(asctime[4]);
+        second = Number(asctime[5]);
+        year = Number(asctime[6]);
+    }
+    else {
+        return undefined;
+    }
+    if (month === undefined)
+        return undefined;
+    const timestamp = Date.UTC(year, month, day, hour, minute, second);
+    const utc = new Date(timestamp);
+    // Reject impossible calendar/clock values that Date.UTC silently rolls over
+    // (e.g. 31 Feb, 25:00:00). A `:60` leap second is likewise dropped rather
+    // than special-cased — leap seconds never appear in a Retry-After header.
+    if (utc.getUTCFullYear() !== year ||
+        utc.getUTCMonth() !== month ||
+        utc.getUTCDate() !== day ||
+        utc.getUTCHours() !== hour ||
+        utc.getUTCMinutes() !== minute ||
+        utc.getUTCSeconds() !== second) {
+        return undefined;
+    }
+    return timestamp;
+}

package/dist/utils/server-clock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Offsets below this are left uncorrected: the server accepts signatures
+ * within ±30s, and the `Date` header only has whole-second resolution, so
+ * correcting a nearly-right clock would add noise without fixing anything.
+ */
+export declare const CLOCK_CORRECTION_THRESHOLD_MS = 5000;
+/**
+ * The server's notion of "now", learned from API response `Date` headers.
+ *
+ * Request signatures carry a timestamp the server rejects outside a ±30s
+ * window, so a device whose clock is minutes off fails every signed call.
+ * Each response reports the server's time; the offset from the local clock
+ * is applied to signing timestamps once it exceeds
+ * {@link CLOCK_CORRECTION_THRESHOLD_MS}.
+ */
+export declare class ServerClock {
+    private offset;
+    /** Milliseconds added to the local clock; 0 while the device clock is close enough. */
+    get offsetMs(): number;
+    /** Current epoch milliseconds on the server's clock. */
+    now(): number;
+    /**
+     * Record the server time from a response, skipping any the browser may
+     * have served from its HTTP cache: a cached copy keeps its original `Date`,
+     * which can be older than the ±30s signing window.
+     */
+    observeResponse(headers: Headers | undefined, receivedAtMs: number): void;
+    /**
+     * Record the server time from a response `Date` header.
+     *
+     * The server stamps `Date` when it sends the response, so it is compared
+     * with the local receipt time; request upload and server processing do not
+     * skew the estimate. The header is truncated to the second, so it is read
+     * as the middle of that second. A missing or malformed header leaves the
+     * offset unchanged.
+     */
+    observe(dateHeader: string | null | undefined, receivedAtMs: number): void;
+}

package/dist/utils/server-clock.js

@@ -0,0 +1,67 @@
+import { parseHttpDate } from "./http-date";
+/**
+ * Offsets below this are left uncorrected: the server accepts signatures
+ * within ±30s, and the `Date` header only has whole-second resolution, so
+ * correcting a nearly-right clock would add noise without fixing anything.
+ */
+export const CLOCK_CORRECTION_THRESHOLD_MS = 5_000;
+/** True when `Cache-Control` lets a cache store the response and serve it later. */
+function mayBeCached(cacheControl) {
+    if (!cacheControl)
+        return false;
+    const directives = cacheControl.split(",").map((directive) => {
+        const [name = "", value = ""] = directive.split("=", 2);
+        return { name: name.trim().toLowerCase(), value: value.trim().replace(/^"(.*)"$/, "$1") };
+    });
+    if (directives.some(({ name }) => name === "no-store" || name === "no-cache"))
+        return false;
+    return directives.some(({ name, value }) => name === "immutable" || ((name === "max-age" || name === "s-maxage") && Number(value) > 0));
+}
+/**
+ * The server's notion of "now", learned from API response `Date` headers.
+ *
+ * Request signatures carry a timestamp the server rejects outside a ±30s
+ * window, so a device whose clock is minutes off fails every signed call.
+ * Each response reports the server's time; the offset from the local clock
+ * is applied to signing timestamps once it exceeds
+ * {@link CLOCK_CORRECTION_THRESHOLD_MS}.
+ */
+export class ServerClock {
+    offset = 0;
+    /** Milliseconds added to the local clock; 0 while the device clock is close enough. */
+    get offsetMs() {
+        return this.offset;
+    }
+    /** Current epoch milliseconds on the server's clock. */
+    now() {
+        return Date.now() + this.offset;
+    }
+    /**
+     * Record the server time from a response, skipping any the browser may
+     * have served from its HTTP cache: a cached copy keeps its original `Date`,
+     * which can be older than the ±30s signing window.
+     */
+    observeResponse(headers, receivedAtMs) {
+        if (!headers || mayBeCached(headers.get("cache-control")))
+            return;
+        this.observe(headers.get("date"), receivedAtMs);
+    }
+    /**
+     * Record the server time from a response `Date` header.
+     *
+     * The server stamps `Date` when it sends the response, so it is compared
+     * with the local receipt time; request upload and server processing do not
+     * skew the estimate. The header is truncated to the second, so it is read
+     * as the middle of that second. A missing or malformed header leaves the
+     * offset unchanged.
+     */
+    observe(dateHeader, receivedAtMs) {
+        if (!dateHeader)
+            return;
+        const serverMs = parseHttpDate(dateHeader.trim());
+        if (serverMs === undefined)
+            return;
+        const estimate = Math.round(serverMs + 500 - receivedAtMs);
+        this.offset = Math.abs(estimate) < CLOCK_CORRECTION_THRESHOLD_MS ? 0 : estimate;
+    }
+}

package/package.json

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