@atumlabs/payment-gateway-client 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -65,7 +65,6 @@ type OpenAPIConfig = {
         response: Interceptors<AxiosResponse>;
     };
 };
-declare const OpenAPI: OpenAPIConfig;
 
 declare abstract class BaseHttpRequest {
     readonly config: OpenAPIConfig;
@@ -203,7 +202,10 @@ type PaymentRequest = {
          */
         account: string;
         /**
-         * The API endpoint URL where the verification service can be reached
+         * Origin of the fulfillment verifier service, with no path — the caller
+         * appends the verifier's own API paths. The gateway's `/defaults` response
+         * supplies the default fulfillment verifier for each chain.
+         *
          */
         endpoint: string;
     };
@@ -893,7 +895,10 @@ type CreateQuoteRequest = {
          */
         account: string;
         /**
-         * The API endpoint URL where the verification service can be reached
+         * Origin of the fulfillment verifier service, with no path — the caller
+         * appends the verifier's own API paths. The gateway's `/defaults` response
+         * supplies the default fulfillment verifier for each chain.
+         *
          */
         endpoint: string;
     };
@@ -975,7 +980,7 @@ type Quote = {
     quote_id: string;
     /**
      * The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
-     * declaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned
+     * declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
      * verbatim as an opaque signed document. A client recomputes quote_hash over the returned
      * bytes and verifies the settler signature, then re-embeds them into
      * bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
@@ -997,7 +1002,7 @@ type AwardedQuote = {
     quote_id: string;
     /**
      * The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
-     * declaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned
+     * declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
      * verbatim as an opaque signed document. A client recomputes quote_hash over the returned
      * bytes and verifies the settler signature, then re-embeds them into
      * bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
@@ -1996,8 +2001,8 @@ declare const $PaymentRequest: {
                 readonly endpoint: {
                     readonly type: "string";
                     readonly format: "uri";
-                    readonly description: "The API endpoint URL where the verification service can be reached";
-                    readonly example: "https://verifier.atum.network/api/v1/verify";
+                    readonly description: "Origin of the fulfillment verifier service, with no path — the caller\nappends the verifier's own API paths. The gateway's `/defaults` response\nsupplies the default fulfillment verifier for each chain.\n";
+                    readonly example: "https://veri-fill.production-testnet.atum.xyz";
                 };
             };
         };
@@ -2705,8 +2710,8 @@ declare const $CreateQuoteRequest: {
                 readonly endpoint: {
                     readonly type: "string";
                     readonly format: "uri";
-                    readonly description: "The API endpoint URL where the verification service can be reached";
-                    readonly example: "https://verifier.atum.network/api/v1/verify";
+                    readonly description: "Origin of the fulfillment verifier service, with no path — the caller\nappends the verifier's own API paths. The gateway's `/defaults` response\nsupplies the default fulfillment verifier for each chain.\n";
+                    readonly example: "https://veri-fill.production-testnet.atum.xyz";
                 };
             };
         };
@@ -2817,7 +2822,7 @@ declare const $Quote: {
         };
         readonly fulfillment_quote: {
             readonly type: "object";
-            readonly description: "The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1\ndeclaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned\nverbatim as an opaque signed document. A client recomputes quote_hash over the returned\nbytes and verifies the settler signature, then re-embeds them into\nbid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based\n(URDNA2015), so it is stable across JSON key-order/whitespace normalization. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what the\nsettler emitted (quotes are stored as JSONB, which normalizes on write). The gateway\nstill never re-serializes the quote through a typed struct (that renormalizes timestamp\nvalues and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.\n";
+            readonly description: "The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1\ndeclaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned\nverbatim as an opaque signed document. A client recomputes quote_hash over the returned\nbytes and verifies the settler signature, then re-embeds them into\nbid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based\n(URDNA2015), so it is stable across JSON key-order/whitespace normalization. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what the\nsettler emitted (quotes are stored as JSONB, which normalizes on write). The gateway\nstill never re-serializes the quote through a typed struct (that renormalizes timestamp\nvalues and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.\n";
             readonly 'x-go-type': "json.RawMessage";
         };
     };
@@ -2833,7 +2838,7 @@ declare const $AwardedQuote: {
         };
         readonly fulfillment_quote: {
             readonly type: "object";
-            readonly description: "The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1\ndeclaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned\nverbatim as an opaque signed document. A client recomputes quote_hash over the returned\nbytes and verifies the settler signature, then re-embeds them into\nbid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based\n(URDNA2015), so it is stable across JSON key-order/whitespace normalization. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what the\nsettler emitted (quotes are stored as JSONB, which normalizes on write). The gateway\nstill never re-serializes the quote through a typed struct (that renormalizes timestamp\nvalues and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.\n";
+            readonly description: "The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1\ndeclaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned\nverbatim as an opaque signed document. A client recomputes quote_hash over the returned\nbytes and verifies the settler signature, then re-embeds them into\nbid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based\n(URDNA2015), so it is stable across JSON key-order/whitespace normalization. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what the\nsettler emitted (quotes are stored as JSONB, which normalizes on write). The gateway\nstill never re-serializes the quote through a typed struct (that renormalizes timestamp\nvalues and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.\n";
             readonly 'x-go-type': "json.RawMessage";
         };
         readonly awarded_payment_id: {
@@ -3096,6 +3101,38 @@ declare class ApiError extends Error {
     constructor(request: ApiRequestOptions, response: ApiResult, message: string);
 }
 
+/**
+ * Type guard for the SDK's transport-level error.
+ *
+ * Every non-2xx gateway response is thrown by the generated client as an
+ * {@link ApiError}, which also carries the transport detail (`status`, `url`).
+ */
+declare function isApiError(err: unknown): err is ApiError;
+/**
+ * Return the typed, public-facing gateway error carried by a caught
+ * {@link ApiError}, or `undefined` when the value is not an `ApiError` or its
+ * body is not the public {@link ErrorResponse} shape.
+ *
+ * The gateway serializes errors as an {@link ErrorResponse}
+ * (`{ code, message, request_id?, docs_url?, domain? }`), but the generated
+ * client widens the parsed body to `unknown`. This helper narrows it back so
+ * consumers can branch on `code` and quote `request_id` to support. It only
+ * ever exposes this outward-facing shape — never any internal error taxonomy.
+ *
+ * @example
+ * try {
+ *   await client.payments.submitPayment({ requestBody });
+ * } catch (err) {
+ *   const gwError = getErrorResponse(err);
+ *   if (gwError) {
+ *     console.error(gwError.code, gwError.message, gwError.request_id);
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ */
+declare function getErrorResponse(err: unknown): ErrorResponse | undefined;
+
 /**
  * EVM Permit2 PermitWitnessTransferFrom deposit prehash + EIP-712 digest.
  *
@@ -3486,6 +3523,21 @@ declare const PAYMENT_REQUEST_VERSION = "1.0";
 declare function signPaymentRequest(request: PaymentRequest, signer: SenderSigner): Promise<PaymentRequest>;
 type HttpRequestConstructor = new (config: OpenAPIConfig) => BaseHttpRequest;
 declare const defaultGateway: string;
+/**
+ * Default request-layer configuration, with `BASE` set to this package's default
+ * gateway ({@link defaultGateway}, production-testnet).
+ *
+ * The generated value mirrors the first `servers` entry of the OpenAPI contract,
+ * which is mainnet. This package defaults to testnet instead, so a client created
+ * without an explicit URL never targets a live-funds environment. The override
+ * lives here rather than in `src/generated/`, which is reproduced from the
+ * contract and stays in sync with it.
+ *
+ * Exported for callers that want the default configuration shape.
+ * {@link PaymentGatewayClient} does not read it: the client resolves its own
+ * `BASE` and passes it explicitly.
+ */
+declare const OpenAPI: OpenAPIConfig;
 /**
  * Default quote-collection window for {@link PaymentGatewayClient.prepareQuoteRequest}
  * (`quote_deadline = now + this`, in seconds). Chosen as the largest value that still
@@ -3658,4 +3710,4 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
     }): Promise<CreateQuoteRequest>;
 }
 
-export { $AuthorizationResult, $AwardAccepted, $AwardRequest, $AwardResponse, $AwardedPayment, $AwardedQuote, $BidAward, $CreateQuoteRequest, $DataIntegrityProof, $ErrorResponse, $FulfillmentConfirmation, $GetPaymentStatusResponse, type $OpenApiTs, $OwnedAsset, $PaymentBlockchainContext, $PaymentError, $PaymentRequest, $PaymentResponse, $PaymentSummary, $PaymentTimelineResponse, $PreparePaymentRequest, $PreparePaymentResponse, $Quote, $QuoteRequestAccepted, $QuoteRequestResponse, $QuoteRequestStatusResponse, $ResolvePaymentResponse, $SenderAuth, $SenderAuthMessageScheme, $SignedMessage, $TimelineError, $TimelineStep, $VerifiableCredential, $VerifiableCredentialAuth, ApiError, type ApiRequestOptions, type ApiResult, type AuthorizationResult, AuthorizationsService, type AuthorizePaymentData, type AuthorizePaymentResponse, type AwardAccepted, type AwardQuoteData, type AwardQuoteResponse, type AwardRequest, type AwardResponse, type AwardedPayment, type AwardedQuote, type BidAward, CancelError, CancelablePromise, type ChainDefaults, type CreateQuoteRequest, type CreateQuoteRequestData, type CreateQuoteRequestResponse, DEFAULT_FULFILLMENT_DEADLINE_SECONDS, DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS, DEFAULT_QUOTE_DEADLINE_SECONDS, DEPOSIT_MESSAGE_SIZE, type DataIntegrityProof, type ErrorResponse, type FulfillmentConfirmation, type GetPaymentStatusData, type GetPaymentStatusResponse, type GetPaymentStatusResponse2, type GetPaymentTimelineData, type GetPaymentTimelineResponse, type GetQuoteRequestStatusData, type GetQuoteRequestStatusResponse, type HealthCheckResponse, HealthService, Interceptors, MAX_VALID_SLOT, type OnCancel, OpenAPI, type OpenAPIConfig, type OwnedAsset, PAYMENT_REQUEST_VERSION, PERMIT2_CONTRACT_ADDRESS, type PaymentBlockchainContext, type PaymentError, PaymentGatewayClient, type PaymentRequest, type PaymentResponse, type PaymentSummary, type PaymentTimelineResponse, PaymentsService, type PermitWitnessTransferFromParams, type PreparePaymentData, type PreparePaymentRequest, type PreparePaymentResponse, type PreparePaymentResponse2, type Quote, type QuoteRequestAccepted, type QuoteRequestResponse, type QuoteRequestStatusResponse, QuoteRequestsService, REPLAY_HORIZON_SECS, type ResolvePaymentData, type ResolvePaymentResponse, type ResolvePaymentResponse2, type SenderAuth, type SenderAuthMessageScheme, type SenderSignature, type SenderSigner, type SenderSignerOptions, type SignedMessage, type SolanaClusterUnixTimeReader, type SolanaDepositParams, type SolanaDepositPrehash, type SubmitPaymentData, type SubmitPaymentResponse, TOTAL_BUCKETS, type TimelineError, type TimelineStep, type TurnkeyConfig, TurnkeySenderSigner, type TvmPermitWitnessTransferFromParams, type VerifiableCredential, type VerifiableCredentialAuth, base58ToBytes, base58ToHex, bytesToHex, createPermitWitnessTransferFromPrehash, createSenderSigner, createSolanaDepositPrehash, createTvmPermitWitnessTransferFromPrehash, defaultGateway, type domain, encodeU64LE, type error_code, generateSolanaNonce, generateSolanaPaymentId, hashPermitWitnessTransferFrom, hashRequestId, hashSolanaDeposit, hashTvmPermitWitnessTransferFrom, hexToBytes, maskChainId, normalizeAddress, resolveTurnkeyAddresses, signPaymentRequest, type status, type status2, type status3, type status4, type status5, type status6, type status7, type status8, type status9 };
+export { $AuthorizationResult, $AwardAccepted, $AwardRequest, $AwardResponse, $AwardedPayment, $AwardedQuote, $BidAward, $CreateQuoteRequest, $DataIntegrityProof, $ErrorResponse, $FulfillmentConfirmation, $GetPaymentStatusResponse, type $OpenApiTs, $OwnedAsset, $PaymentBlockchainContext, $PaymentError, $PaymentRequest, $PaymentResponse, $PaymentSummary, $PaymentTimelineResponse, $PreparePaymentRequest, $PreparePaymentResponse, $Quote, $QuoteRequestAccepted, $QuoteRequestResponse, $QuoteRequestStatusResponse, $ResolvePaymentResponse, $SenderAuth, $SenderAuthMessageScheme, $SignedMessage, $TimelineError, $TimelineStep, $VerifiableCredential, $VerifiableCredentialAuth, ApiError, type ApiRequestOptions, type ApiResult, type AuthorizationResult, AuthorizationsService, type AuthorizePaymentData, type AuthorizePaymentResponse, type AwardAccepted, type AwardQuoteData, type AwardQuoteResponse, type AwardRequest, type AwardResponse, type AwardedPayment, type AwardedQuote, type BidAward, CancelError, CancelablePromise, type ChainDefaults, type CreateQuoteRequest, type CreateQuoteRequestData, type CreateQuoteRequestResponse, DEFAULT_FULFILLMENT_DEADLINE_SECONDS, DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS, DEFAULT_QUOTE_DEADLINE_SECONDS, DEPOSIT_MESSAGE_SIZE, type DataIntegrityProof, type ErrorResponse, type FulfillmentConfirmation, type GetPaymentStatusData, type GetPaymentStatusResponse, type GetPaymentStatusResponse2, type GetPaymentTimelineData, type GetPaymentTimelineResponse, type GetQuoteRequestStatusData, type GetQuoteRequestStatusResponse, type HealthCheckResponse, HealthService, Interceptors, MAX_VALID_SLOT, type OnCancel, OpenAPI, type OpenAPIConfig, type OwnedAsset, PAYMENT_REQUEST_VERSION, PERMIT2_CONTRACT_ADDRESS, type PaymentBlockchainContext, type PaymentError, PaymentGatewayClient, type PaymentRequest, type PaymentResponse, type PaymentSummary, type PaymentTimelineResponse, PaymentsService, type PermitWitnessTransferFromParams, type PreparePaymentData, type PreparePaymentRequest, type PreparePaymentResponse, type PreparePaymentResponse2, type Quote, type QuoteRequestAccepted, type QuoteRequestResponse, type QuoteRequestStatusResponse, QuoteRequestsService, REPLAY_HORIZON_SECS, type ResolvePaymentData, type ResolvePaymentResponse, type ResolvePaymentResponse2, type SenderAuth, type SenderAuthMessageScheme, type SenderSignature, type SenderSigner, type SenderSignerOptions, type SignedMessage, type SolanaClusterUnixTimeReader, type SolanaDepositParams, type SolanaDepositPrehash, type SubmitPaymentData, type SubmitPaymentResponse, TOTAL_BUCKETS, type TimelineError, type TimelineStep, type TurnkeyConfig, TurnkeySenderSigner, type TvmPermitWitnessTransferFromParams, type VerifiableCredential, type VerifiableCredentialAuth, base58ToBytes, base58ToHex, bytesToHex, createPermitWitnessTransferFromPrehash, createSenderSigner, createSolanaDepositPrehash, createTvmPermitWitnessTransferFromPrehash, defaultGateway, type domain, encodeU64LE, type error_code, generateSolanaNonce, generateSolanaPaymentId, getErrorResponse, hashPermitWitnessTransferFrom, hashRequestId, hashSolanaDeposit, hashTvmPermitWitnessTransferFrom, hexToBytes, isApiError, maskChainId, normalizeAddress, resolveTurnkeyAddresses, signPaymentRequest, type status, type status2, type status3, type status4, type status5, type status6, type status7, type status8, type status9 };

package/dist/index.js

@@ -1,3 +1,9 @@
+/*
+ * Copyright (c) 2026 Atum Labs, Inc. All rights reserved.
+ * Proprietary and confidential.
+ * Access and use are governed by the LICENSE file distributed with this package.
+ * Do not remove, alter, or obscure this notice.
+ */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -4674,7 +4680,7 @@ __export(index_exports, {
   HealthService: () => HealthService,
   Interceptors: () => Interceptors,
   MAX_VALID_SLOT: () => import_solana_escrow_encoding.MAX_VALID_SLOT,
-  OpenAPI: () => OpenAPI,
+  OpenAPI: () => OpenAPI2,
   PAYMENT_REQUEST_VERSION: () => PAYMENT_REQUEST_VERSION,
   PERMIT2_CONTRACT_ADDRESS: () => import_evm_escrow_encoding.PERMIT2_CONTRACT_ADDRESS,
   PaymentGatewayClient: () => PaymentGatewayClient2,
@@ -4694,11 +4700,13 @@ __export(index_exports, {
   encodeU64LE: () => import_solana_escrow_encoding.encodeU64LE,
   generateSolanaNonce: () => generateSolanaNonce,
   generateSolanaPaymentId: () => generateSolanaPaymentId,
+  getErrorResponse: () => getErrorResponse,
   hashPermitWitnessTransferFrom: () => import_evm_escrow_encoding.hashPermitWitnessTransferFrom,
   hashRequestId: () => hashRequestId,
   hashSolanaDeposit: () => hashSolanaDeposit,
   hashTvmPermitWitnessTransferFrom: () => import_tvm_escrow_encoding.hashTvmPermitWitnessTransferFrom,
   hexToBytes: () => hexToBytes,
+  isApiError: () => isApiError,
   maskChainId: () => import_tvm_escrow_encoding.maskChainId,
   normalizeAddress: () => import_tvm_escrow_encoding.normalizeAddress,
   resolveTurnkeyAddresses: () => resolveTurnkeyAddresses,
@@ -4722,7 +4730,7 @@ var Interceptors = class {
   }
 };
 var OpenAPI = {
-  BASE: "https://api.atum.network",
+  BASE: "https://payment-gw.production-mainnet.atum.xyz",
   CREDENTIALS: "include",
   ENCODE_PATH: void 0,
   HEADERS: void 0,
@@ -4905,7 +4913,7 @@ var getUrl = (config, options) => {
 var getFormData = (options) => {
   if (options.formData) {
     const formData = new FormData();
-    const process = (key, value) => {
+    const process2 = (key, value) => {
       if (isString(value) || isBlob(value)) {
         formData.append(key, value);
       } else {
@@ -4914,9 +4922,9 @@ var getFormData = (options) => {
     };
     Object.entries(options.formData).filter(([, value]) => value !== void 0 && value !== null).forEach(([key, value]) => {
       if (Array.isArray(value)) {
-        value.forEach((v) => process(key, v));
+        value.forEach((v) => process2(key, v));
       } else {
-        process(key, value);
+        process2(key, value);
       }
     });
     return formData;
@@ -5445,7 +5453,7 @@ var HealthService = class {
 var PaymentGatewayClient = class {
   constructor(config, HttpRequest = AxiosHttpRequest) {
     this.request = new HttpRequest({
-      BASE: config?.BASE ?? "https://api.atum.network",
+      BASE: config?.BASE ?? "https://payment-gw.production-mainnet.atum.xyz",
       VERSION: config?.VERSION ?? "1.0.0",
       WITH_CREDENTIALS: config?.WITH_CREDENTIALS ?? false,
       CREDENTIALS: config?.CREDENTIALS ?? "include",
@@ -5830,8 +5838,11 @@ Leave empty to use the default verifier.
         endpoint: {
           type: "string",
           format: "uri",
-          description: "The API endpoint URL where the verification service can be reached",
-          example: "https://verifier.atum.network/api/v1/verify"
+          description: `Origin of the fulfillment verifier service, with no path \u2014 the caller
+appends the verifier's own API paths. The gateway's \`/defaults\` response
+supplies the default fulfillment verifier for each chain.
+`,
+          example: "https://veri-fill.production-testnet.atum.xyz"
         }
       }
     },
@@ -6699,8 +6710,11 @@ Leave empty to use the default selector.
         endpoint: {
           type: "string",
           format: "uri",
-          description: "The API endpoint URL where the verification service can be reached",
-          example: "https://verifier.atum.network/api/v1/verify"
+          description: `Origin of the fulfillment verifier service, with no path \u2014 the caller
+appends the verifier's own API paths. The gateway's \`/defaults\` response
+supplies the default fulfillment verifier for each chain.
+`,
+          example: "https://veri-fill.production-testnet.atum.xyz"
         }
       }
     },
@@ -6820,7 +6834,7 @@ bid_award.fulfillment_quote_json.
     fulfillment_quote: {
       type: "object",
       description: `The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
-declaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned
+declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
 verbatim as an opaque signed document. A client recomputes quote_hash over the returned
 bytes and verifies the settler signature, then re-embeds them into
 bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
@@ -6846,7 +6860,7 @@ var $AwardedQuote = {
     fulfillment_quote: {
       type: "object",
       description: `The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
-declaration at https://schemas.atum.network/declarations/FulfillmentQuote/v1), returned
+declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
 verbatim as an opaque signed document. A client recomputes quote_hash over the returned
 bytes and verifies the settler signature, then re-embeds them into
 bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
@@ -7160,6 +7174,21 @@ var $AwardAccepted = {
   }
 };
 
+// src/errors.ts
+function isApiError(err) {
+  return err instanceof ApiError;
+}
+function getErrorResponse(err) {
+  if (!(err instanceof ApiError)) {
+    return void 0;
+  }
+  const body = err.body;
+  if (body && typeof body === "object" && typeof body.code === "string" && typeof body.message === "string") {
+    return body;
+  }
+  return void 0;
+}
+
 // src/sender_auth_schemes/evm_permit2.ts
 var import_ethers3 = require("ethers");
 var import_evm_escrow_encoding = __toESM(require_dist2());
@@ -7333,7 +7362,8 @@ async function signPaymentRequest(request2, signer) {
   }
   return request2;
 }
-var defaultGateway = "https://payment-gateway-testnet.atumlabs.xyz";
+var defaultGateway = "https://payment-gw.production-testnet.atum.xyz";
+var OpenAPI2 = { ...OpenAPI, BASE: defaultGateway };
 var DEFAULT_QUOTE_DEADLINE_SECONDS = 5;
 var DEFAULT_FULFILLMENT_DEADLINE_SECONDS = 3600;
 var DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS = 10;
@@ -7422,8 +7452,10 @@ async function assemblePaymentRequest(params) {
 }
 var PaymentGatewayClient2 = class extends PaymentGatewayClient {
   constructor(config, HttpRequest = AxiosHttpRequest) {
-    super(config, HttpRequest);
-    this.baseUrl = config?.BASE ?? defaultGateway;
+    const envBase = (typeof process !== "undefined" ? process.env.GATEWAY_URL : void 0)?.trim();
+    const base = config?.BASE ?? (envBase || defaultGateway);
+    super({ ...config, BASE: base }, HttpRequest);
+    this.baseUrl = base;
   }
   /**
    * Fetches chain defaults from the payment gateway.
@@ -7703,11 +7735,13 @@ var PaymentGatewayClient2 = class extends PaymentGatewayClient {
   encodeU64LE,
   generateSolanaNonce,
   generateSolanaPaymentId,
+  getErrorResponse,
   hashPermitWitnessTransferFrom,
   hashRequestId,
   hashSolanaDeposit,
   hashTvmPermitWitnessTransferFrom,
   hexToBytes,
+  isApiError,
   maskChainId,
   normalizeAddress,
   resolveTurnkeyAddresses,

package/docs/idempotency.md

@@ -0,0 +1,62 @@
+# Payment idempotency
+
+Submit the same payment twice — a retry, a timeout, a network blip — and you
+should end up with **one** payment, not two, and receive the **same** answer both
+times. The key to both properties is the `request_id` you send with each payment.
+
+## Using the SDK
+
+With `@atumlabs/payment-gateway-client` this is automatic. Pass a stable
+`request_id` and reuse it on retry. `request_id` is required on the payment path
+(`preparePaymentRequest`); the SDK derives the on-chain deposit nonce
+deterministically from it, so both guarantees below line up on their own. You
+never manage nonces — `request_id` is the only value you control.
+
+Reuse the same `request_id` across attempts of the same logical payment. Use a
+fresh `request_id` only for a genuinely new payment.
+
+## The two guarantees
+
+### 1. Gateway dedup — enforced for every caller
+
+The gateway records your `request_id` (scoped to your source account and signing
+identity). If the same `request_id` arrives again, the gateway returns the
+original payment — same `payment_id`, same status and receipt — and never creates
+a second payment or broadcasts a second deposit. This holds whether you use the
+SDK or call the API directly, as long as you send a stable `request_id` and reuse
+it on retry.
+
+### 2. On-chain single-settlement — enforced by the blockchain
+
+Each deposit authorization carries a nonce, and the chain guarantees a given
+nonce can settle at most once. This ties your retries together on-chain **only
+if** each retry carries the **same** nonce. The SDK derives that nonce from your
+`request_id`, so retries reuse it automatically. A direct caller sets the nonce
+themselves in the signed permit.
+
+The caveat runs in both directions. A changing `request_id` defeats both
+guarantees, because each attempt is then treated as a different payment — keep it
+stable and reuse it on retry. Equally, reusing a `request_id` with different terms
+(a corrected amount, a different token) returns the **original** payment rather
+than an error, so the new terms are silently dropped. A genuinely new payment
+always needs a new id.
+
+## Chain-specific behavior
+
+The SDK gives you the same guarantee on every chain; the on-chain half works
+slightly differently underneath:
+
+- **EVM / Tron:** the on-chain nonce is spent permanently, so guarantee 2 lasts
+  indefinitely.
+- **Solana:** the on-chain guard covers only a short, bounded window (roughly two
+  minutes). Beyond that window the durable protection is guarantee 1 (the
+  gateway's `request_id` record). The SDK keeps a rebuild inside the window by
+  pinning `issued_at` through its Solana clock reader, so you do not have to.
+
+Either way, a stable `request_id` keeps you safe on every chain.
+
+## A note on addresses
+
+EVM `0x` addresses are case-insensitive, so casing never affects your payment.
+Solana and Tron base58 addresses **are** case-sensitive — pass them exactly as
+issued.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atumlabs/payment-gateway-client",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "TypeScript client for Atum Payment Gateway API",
   "author": "Atum Labs, Inc.",
   "homepage": "https://github.com/Atum-Labs/protocol/tree/main/payment-gateway-client#readme",
@@ -41,11 +41,12 @@
     "generate": "openapi-ts --input ../schemas/apis/payment-gateway/v1/openapi.yaml --output ./src/generated --client axios --name PaymentGatewayClient --useOptions",
     "prebuild:deps": "node -e \"if(!require('fs').existsSync('../key-management/common/typescript/tsconfig.json')){console.error('protocol key-management packages not found at ../key-management. Is this checked out inside the protocol monorepo?');process.exit(1)}\"",
     "build:deps": "tsc -p ../key-management/common/typescript/tsconfig.json && tsc -p ../key-management/providers/turnkey/typescript/tsconfig.json && tsc -p ../contracts/svm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/evm/escrow-encoding/typescript/tsconfig.json && tsc -p ../contracts/tvm/escrow-encoding/typescript/tsconfig.json && tsc -p ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/tsconfig.json",
-    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js",
+    "build": "pnpm run build:deps && tsup && chmod +x dist/cli/*.js && node scripts/stamp-entry-headers.mjs",
     "pretest": "pnpm run build:deps",
     "test": "jest",
     "clean": "rm -rf dist ../key-management/common/typescript/dist ../key-management/providers/turnkey/typescript/dist ../contracts/svm/escrow-encoding/typescript/dist ../contracts/evm/escrow-encoding/typescript/dist ../contracts/tvm/escrow-encoding/typescript/dist ../schemas/declarations/PaymentRequest/v1/bindings/typescript/sender-auth/dist",
     "check:publishable": "node scripts/check-publishable.mjs",
+    "gen:notices": "node scripts/gen-third-party-notices.mjs",
     "prepare": "pnpm run build",
     "prepublishOnly": "pnpm run build && pnpm run check:publishable"
   },
@@ -54,6 +55,7 @@
     "axios": "1.13.2",
     "bs58": "^6.0.0",
     "commander": "^12.0.0",
+    "dotenv": "^16.6.1",
     "ethers": "^6.11.0",
     "tweetnacl": "^1.0.3",
     "zod": "^3.25.0"
@@ -62,6 +64,7 @@
     "@atum-labs/evm-escrow-encoding": "workspace:*",
     "@atum-labs/km-core": "workspace:*",
     "@atum-labs/payment-request-sender-auth": "workspace:*",
+    "@atum-labs/publish-guard": "workspace:*",
     "@atum-labs/solana-escrow-encoding": "workspace:*",
     "@atum-labs/turnkey-signer": "workspace:*",
     "@atum-labs/tvm-escrow-encoding": "workspace:*",
@@ -76,7 +79,14 @@
   },
   "files": [
     "dist/**/*",
-    "CHANGELOG.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/**",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.txt"
   ],
-  "license": "UNLICENSED"
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "restricted"
+  }
 }