@0xmonaco/core 1.0.90 → 1.0.91

package/dist/api/base.d.ts

@@ -82,6 +82,7 @@ export declare abstract class BaseAPI {
      *
      * @param endpoint - The API endpoint to call (should start with /)
      * @param options - Request options (method, body, headers, etc.)
+     * @param resendDeadline - Epoch ms after which a clock-skew 401 is returned instead of re-signed
      * @returns Promise resolving to the response data
      * @throws {APIError} When access token is not set or API request fails
      *
@@ -100,7 +101,25 @@ export declare abstract class BaseAPI {
      * );
      * ```
      */
-    protected makeAuthenticatedRequest<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    protected makeAuthenticatedRequest<T>(endpoint: string, options?: RequestInit, resendDeadline?: number): Promise<T>;
+    /**
+     * Sends a keyed submission, re-sending the identical body while its outcome
+     * is unknown (network failure or a 5xx), for at most `maxRetries` extra
+     * attempts with exponential backoff.
+     *
+     * Only safe for a body that carries an `idempotencyKey`: the server replays
+     * the original result for a repeated key instead of executing again. A
+     * maintenance `OPERATIONS_BLOCKED` refusal and every 4xx are definitive and
+     * returned at once. A `Retry-After` beyond {@link MAX_SUBMISSION_RETRY_DELAY_MS},
+     * a resend later than {@link MAX_SUBMISSION_RETRY_WINDOW_MS} after the first
+     * send, or a session change during backoff also stops the loop: keys are
+     * scoped per account, so a resend signed by another session would be a new order.
+     *
+     * @throws {APIError} The last failure, naming the key to reuse, when every attempt is ambiguous
+     */
+    protected makeKeyedSubmission<T>(endpoint: string, options: RequestInit & {
+        body: string;
+    }): Promise<T>;
     /**
      * Compute the per-request ed25519 signature headers.
      *

package/dist/api/base.js

@@ -37,6 +37,56 @@ import { CLOCK_CORRECTION_THRESHOLD_MS, ServerClock } from "../utils/server-cloc
  * only takes effect in server runtimes (Node/undici, Bun, Deno).
  */
 const SDK_USER_AGENT = "@0xmonaco/core";
+/** Longest server-requested wait a keyed submission retry will honour. */
+const MAX_SUBMISSION_RETRY_DELAY_MS = 5000;
+/**
+ * Keyed submission retries stop this long after the first send, far inside
+ * the server's 15-minute key window even if a suspended tab stretches a wait.
+ */
+const MAX_SUBMISSION_RETRY_WINDOW_MS = 60_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * True when a submission may or may not have been applied: no response came
+ * back at all, a 2xx body could not be read, or the server answered 5xx.
+ * Maintenance (`OPERATIONS_BLOCKED`) is a deliberate refusal before the book,
+ * not an unknown outcome.
+ */
+function isUnknownSubmissionOutcome(error) {
+    if (!(error instanceof APIError))
+        return false;
+    if (error.statusCode === undefined)
+        return error.cause !== undefined;
+    if (error.statusCode >= StatusCodes.OK && error.statusCode < StatusCodes.MULTIPLE_CHOICES)
+        return error.cause !== undefined;
+    if (error.statusCode < StatusCodes.INTERNAL_SERVER_ERROR)
+        return false;
+    const body = error.responseBody;
+    return !(body && typeof body === "object" && body.error === "OPERATIONS_BLOCKED");
+}
+function hasIdempotencyKey(body) {
+    try {
+        const key = JSON.parse(body)?.idempotencyKey;
+        return typeof key === "string" && key.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function unresolvedSubmissionError(last, attempts, reason, cause = last) {
+    const key = last.requestBody?.idempotencyKey;
+    const stopped = reason ? ` (stopped: ${reason})` : "";
+    return new APIError(`Submission outcome unknown after ${attempts} attempts${stopped}: ${last.message}. Retry with idempotencyKey ${String(key)} and the same payload within 15 minutes of the first attempt, under the same account; a new key can execute again.`, {
+        endpoint: last.endpoint,
+        // A 2xx whose body never arrived is no answer at all: report no status
+        // so callers branching on it treat the outcome as unknown.
+        statusCode: last.statusCode !== undefined && last.statusCode < StatusCodes.MULTIPLE_CHOICES ? undefined : last.statusCode,
+        responseBody: last.responseBody,
+        cause,
+        requestBody: last.requestBody,
+        requestId: last.requestId,
+        retryAfter: last.retryAfter,
+    });
+}
 export class BaseAPI {
     apiUrl;
     /** Active session keypair (raw bytes) used to sign authenticated requests. */
@@ -260,6 +310,7 @@ export class BaseAPI {
      *
      * @param endpoint - The API endpoint to call (should start with /)
      * @param options - Request options (method, body, headers, etc.)
+     * @param resendDeadline - Epoch ms after which a clock-skew 401 is returned instead of re-signed
      * @returns Promise resolving to the response data
      * @throws {APIError} When access token is not set or API request fails
      *
@@ -278,7 +329,7 @@ export class BaseAPI {
      * );
      * ```
      */
-    async makeAuthenticatedRequest(endpoint, options = {}) {
+    async makeAuthenticatedRequest(endpoint, options = {}, resendDeadline) {
         if (!this.sessionKeypair) {
             throw new APIError("Session keypair not set. Authenticate (login) first.", {
                 endpoint: `${this.apiUrl}${endpoint}`,
@@ -305,19 +356,80 @@ export class BaseAPI {
             },
         }, requestBody);
         // A 401 whose response moved the server clock was most likely a
-        // timestamp-skew rejection: re-sign once with the corrected time.
+        // timestamp-skew rejection: re-sign once with the corrected time, but
+        // only under the session that signed the rejected request and before the
+        // caller's resend deadline.
         const offsetBefore = this.serverClock.offsetMs;
+        const signer = this.sessionKeypair;
         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) {
+            if (error instanceof APIError &&
+                error.statusCode === StatusCodes.UNAUTHORIZED &&
+                clockMoved &&
+                this.sessionKeypair === signer &&
+                (resendDeadline === undefined || Date.now() <= resendDeadline)) {
                 return send();
             }
             throw error;
         }
     }
+    /**
+     * Sends a keyed submission, re-sending the identical body while its outcome
+     * is unknown (network failure or a 5xx), for at most `maxRetries` extra
+     * attempts with exponential backoff.
+     *
+     * Only safe for a body that carries an `idempotencyKey`: the server replays
+     * the original result for a repeated key instead of executing again. A
+     * maintenance `OPERATIONS_BLOCKED` refusal and every 4xx are definitive and
+     * returned at once. A `Retry-After` beyond {@link MAX_SUBMISSION_RETRY_DELAY_MS},
+     * a resend later than {@link MAX_SUBMISSION_RETRY_WINDOW_MS} after the first
+     * send, or a session change during backoff also stops the loop: keys are
+     * scoped per account, so a resend signed by another session would be a new order.
+     *
+     * @throws {APIError} The last failure, naming the key to reuse, when every attempt is ambiguous
+     */
+    async makeKeyedSubmission(endpoint, options) {
+        if (!hasIdempotencyKey(options.body))
+            throw new Error("Keyed submission requires a JSON body with an idempotencyKey");
+        const { maxRetries, baseDelayMs } = this.retryOptions;
+        const session = this.sessionKeypair;
+        const startedAt = Date.now();
+        let unknownOutcome;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.makeAuthenticatedRequest(endpoint, options, startedAt + MAX_SUBMISSION_RETRY_WINDOW_MS);
+            }
+            catch (error) {
+                const attempts = attempt + 1;
+                if (!isUnknownSubmissionOutcome(error)) {
+                    // A refusal of a resend says nothing about the earlier attempt,
+                    // which may have executed: report that outcome as still unknown.
+                    if (!unknownOutcome)
+                        throw error;
+                    const refusal = error instanceof Error ? error : new Error(String(error));
+                    throw unresolvedSubmissionError(unknownOutcome, attempts, `retry refused: ${refusal.message}`, refusal);
+                }
+                unknownOutcome = error;
+                const retryAfterMs = (error.retryAfter ?? 0) * 1000;
+                if (attempt >= maxRetries || retryAfterMs > MAX_SUBMISSION_RETRY_DELAY_MS) {
+                    throw unresolvedSubmissionError(error, attempts);
+                }
+                const delayMs = Math.max(baseDelayMs * 2 ** attempt, retryAfterMs);
+                if (Date.now() + delayMs - startedAt > MAX_SUBMISSION_RETRY_WINDOW_MS) {
+                    throw unresolvedSubmissionError(error, attempts, "retry window passed");
+                }
+                await sleep(delayMs);
+                if (Date.now() - startedAt > MAX_SUBMISSION_RETRY_WINDOW_MS) {
+                    throw unresolvedSubmissionError(error, attempts, "retry window passed");
+                }
+                if (this.sessionKeypair !== session)
+                    throw unresolvedSubmissionError(error, attempts, "session changed");
+            }
+        }
+    }
     /**
      * Compute the per-request ed25519 signature headers.
      *

package/dist/api/buildercodes/api.d.ts

@@ -61,7 +61,8 @@ export declare class BuildercodesAPIImpl extends BaseAPI implements Buildercodes
      * Read the authenticated wallet's available BuilderCodes reward balances.
      *
      * Current enrollment is not required: a former payout wallet can still see
-     * and claim the balance it accrued before an address rotation.
+     * and claim whatever remains in its bucket. Shortly after a payout-address
+     * change the old wallet's unclaimed balance moves to the new wallet.
      */
     getRewardsBalance(): Promise<GetBuildercodeRewardsBalanceResponse>;
     /**

package/dist/api/buildercodes/api.js

@@ -173,7 +173,8 @@ export class BuildercodesAPIImpl extends BaseAPI {
      * Read the authenticated wallet's available BuilderCodes reward balances.
      *
      * Current enrollment is not required: a former payout wallet can still see
-     * and claim the balance it accrued before an address rotation.
+     * and claim whatever remains in its bucket. Shortly after a payout-address
+     * change the old wallet's unclaimed balance moves to the new wallet.
      */
     async getRewardsBalance() {
         return this.makeAuthenticatedRequest("/api/v1/buildercodes/rewards/balance", { method: "GET" });

package/dist/api/margin-accounts/api.d.ts

@@ -5,8 +5,12 @@ export declare class MarginAccountsAPIImpl extends BaseAPI implements MarginAcco
     closeMarginSubAccount(marginAccountId: string): Promise<CloseMarginSubAccountResponse>;
     getMarginAccountPnl(marginAccountId: string): Promise<MarginAccountPnl>;
     transferMarginCollateral(request: TransferMarginCollateralRequest): Promise<TransferMarginCollateralResponse>;
-    transferCollateralToSubAccount(marginAccountId: string, amount: string): Promise<TransferMarginCollateralResponse>;
-    transferCollateralFromSubAccount(marginAccountId: string, amount: string): Promise<TransferMarginCollateralResponse>;
+    transferCollateralToSubAccount(marginAccountId: string, amount: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<TransferMarginCollateralResponse>;
+    transferCollateralFromSubAccount(marginAccountId: string, amount: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<TransferMarginCollateralResponse>;
     listMarginAccounts(params?: ListMarginAccountsParams): Promise<ListMarginAccountsResponse>;
     getMarginAccountSummary(marginAccountId: string, params?: GetMarginAccountSummaryParams): Promise<MarginAccountSummary>;
     getParentMarginAccountSummary(params?: GetMarginAccountSummaryParams): Promise<MarginAccountSummary>;

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

@@ -29,21 +29,24 @@ export class MarginAccountsAPIImpl extends BaseAPI {
                 amount: request.amount,
                 from: request.from,
                 to: request.to,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }
-    async transferCollateralToSubAccount(marginAccountId, amount) {
-        validate(SubAccountCollateralTransferSchema, { marginAccountId, amount });
+    async transferCollateralToSubAccount(marginAccountId, amount, options) {
+        const idempotencyKey = options?.idempotencyKey;
+        validate(SubAccountCollateralTransferSchema, { marginAccountId, amount, idempotencyKey });
         return await this.makeAuthenticatedRequest(perpRoutes.marginAccounts.subAccountTransferIn(marginAccountId), {
             method: "POST",
-            body: JSON.stringify({ amount }),
+            body: JSON.stringify({ amount, idempotencyKey }),
         });
     }
-    async transferCollateralFromSubAccount(marginAccountId, amount) {
-        validate(SubAccountCollateralTransferSchema, { marginAccountId, amount });
+    async transferCollateralFromSubAccount(marginAccountId, amount, options) {
+        const idempotencyKey = options?.idempotencyKey;
+        validate(SubAccountCollateralTransferSchema, { marginAccountId, amount, idempotencyKey });
         return await this.makeAuthenticatedRequest(perpRoutes.marginAccounts.subAccountTransferOut(marginAccountId), {
             method: "POST",
-            body: JSON.stringify({ amount }),
+            body: JSON.stringify({ amount, idempotencyKey }),
         });
     }
     async listMarginAccounts(params) {
@@ -90,6 +93,7 @@ export class MarginAccountsAPIImpl extends BaseAPI {
                 amount: request.amount,
                 tradingPairId: request.tradingPairId,
                 strategyKey: request.strategyKey,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }
@@ -100,6 +104,7 @@ export class MarginAccountsAPIImpl extends BaseAPI {
             body: JSON.stringify({
                 asset: request.asset,
                 amount: request.amount,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }
@@ -121,6 +126,7 @@ export class MarginAccountsAPIImpl extends BaseAPI {
                 // the wire or the server applies its Adjust Margin default and every
                 // funding-loop top-up converts into initial margin requirement.
                 applyToPositionMargin: request.applyToPositionMargin,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }
@@ -134,6 +140,7 @@ export class MarginAccountsAPIImpl extends BaseAPI {
                 tradingPairId: request.tradingPairId,
                 strategyKey: request.strategyKey,
                 marginMode: request.marginMode,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }
@@ -144,6 +151,7 @@ export class MarginAccountsAPIImpl extends BaseAPI {
             body: JSON.stringify({
                 asset: request.asset,
                 amount: request.amount,
+                idempotencyKey: request.idempotencyKey,
             }),
         });
     }

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

@@ -24,6 +24,12 @@
 import type { BatchCancelOrdersResponse, BatchCreateOrderParams, BatchCreateOrdersResponse, BatchReplaceOrderParams, BatchReplaceOrdersResponse, CancelConditionalOrderResponse, CancelOrderResponse, CancelTwapOrderResponse, ConditionalOrder, CreateOrderResponse, CreateTwapOrderOptions, CreateTwapOrderResponse, GetOrderResponse, GetPaginatedOrdersParams, GetPaginatedOrdersResponse, GetTwapOrderTcaResponse, ListConditionalOrdersParams, ListConditionalOrdersResponse, ListTwapOrderSlicesParams, ListTwapOrderSlicesResponse, 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 {
+    /**
+     * Sends a single create. A key the SDK generated for this call is resent
+     * after a lost response; a caller-supplied key is sent once, because it may
+     * be a recovery of an earlier submission whose 15-minute window is nearly over.
+     */
+    private submitCreate;
     /**
      * Places a limit order on the order book.
      *
@@ -90,7 +96,7 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         postOnly?: boolean;
         selfTradePreventionMode?: SelfTradePreventionMode;
         clientOrderId?: string;
-        /** Generated once per call when omitted. Supply the same key to retry a logical order within 15 minutes. */
+        /** Generated once per call when omitted, and then re-sent inside the call after a lost response. A supplied key is sent once: reuse it with the same order to recover across calls within 15 minutes. */
         idempotencyKey?: string;
         takeProfit?: ParentTpSlLegParams;
         stopLoss?: ParentTpSlLegParams;
@@ -157,7 +163,7 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
         /** 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 15 minutes. */
+        /** Generated once per call when omitted, and then re-sent inside the call after a lost response. A supplied key is sent once: reuse it with the same order to recover across calls within 15 minutes. */
         idempotencyKey?: string;
     }): Promise<CreateOrderResponse>;
     /**

package/dist/api/trading/api.js

@@ -55,6 +55,17 @@ function parentTrailingStopLegToRequest(leg) {
     };
 }
 export class TradingAPIImpl extends BaseAPI {
+    /**
+     * Sends a single create. A key the SDK generated for this call is resent
+     * after a lost response; a caller-supplied key is sent once, because it may
+     * be a recovery of an earlier submission whose 15-minute window is nearly over.
+     */
+    submitCreate(requestBody, keyGenerated) {
+        const request = { method: "POST", body: JSON.stringify(requestBody) };
+        return keyGenerated
+            ? this.makeKeyedSubmission(perpRoutes.orders.create(), request)
+            : this.makeAuthenticatedRequest(perpRoutes.orders.create(), request);
+    }
     /**
      * Places a limit order on the order book.
      *
@@ -140,10 +151,7 @@ export class TradingAPIImpl extends BaseAPI {
             stopLoss: parentTpSlLegToRequest(options?.stopLoss),
             trailingStop: parentTrailingStopLegToRequest(options?.trailingStop),
         };
-        return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
-            method: "POST",
-            body: JSON.stringify(requestBody),
-        });
+        return await this.submitCreate(requestBody, options?.idempotencyKey === undefined);
     }
     /**
      * Places a market order for immediate execution.
@@ -219,10 +227,7 @@ export class TradingAPIImpl extends BaseAPI {
             clientOrderId: options?.clientOrderId,
             idempotencyKey: options?.idempotencyKey === undefined ? crypto.randomUUID() : options.idempotencyKey,
         };
-        return await this.makeAuthenticatedRequest(perpRoutes.orders.create(), {
-            method: "POST",
-            body: JSON.stringify(requestBody),
-        });
+        return await this.submitCreate(requestBody, options?.idempotencyKey === undefined);
     }
     /**
      * Cancels an existing order.

package/package.json

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