@atumlabs/payment-gateway-client 1.0.2 → 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;
@@ -102,10 +101,9 @@ type AuthorizationResult = {
     };
     /**
      * Machine-readable error code (present when status is error or timeout).
-     * The counterparty and webhook codes (COUNTERPARTY_NOT_FOUND, COUNTERPARTY_TIMEOUT,
-     * WEBHOOK_ERROR, WEBHOOK_CONNECTION_ERROR, INTERNAL_ERROR) mirror the AuthorizationErrorCode
-     * protobuf enum. GATEWAY_TIMEOUT, PROOF_INVALID, and PROOF_STALE are produced by payment-gw
-     * itself and have no protobuf equivalent.
+     * Counterparty-sourced codes are derived from the error code the
+     * Counterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and
+     * PROOF_STALE are payment-gw-specific (no counterparty envelope corresponds).
      *
      */
     error_code?: 'COUNTERPARTY_NOT_FOUND' | 'COUNTERPARTY_TIMEOUT' | 'WEBHOOK_ERROR' | 'WEBHOOK_CONNECTION_ERROR' | 'INTERNAL_ERROR' | 'GATEWAY_TIMEOUT' | 'PROOF_INVALID' | 'PROOF_STALE';
@@ -126,10 +124,9 @@ type AuthorizationResult = {
 type status = 'authorized' | 'declined' | 'error' | 'timeout';
 /**
  * Machine-readable error code (present when status is error or timeout).
- * The counterparty and webhook codes (COUNTERPARTY_NOT_FOUND, COUNTERPARTY_TIMEOUT,
- * WEBHOOK_ERROR, WEBHOOK_CONNECTION_ERROR, INTERNAL_ERROR) mirror the AuthorizationErrorCode
- * protobuf enum. GATEWAY_TIMEOUT, PROOF_INVALID, and PROOF_STALE are produced by payment-gw
- * itself and have no protobuf equivalent.
+ * Counterparty-sourced codes are derived from the error code the
+ * Counterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and
+ * PROOF_STALE are payment-gw-specific (no counterparty envelope corresponds).
  *
  */
 type error_code = 'COUNTERPARTY_NOT_FOUND' | 'COUNTERPARTY_TIMEOUT' | 'WEBHOOK_ERROR' | 'WEBHOOK_CONNECTION_ERROR' | 'INTERNAL_ERROR' | 'GATEWAY_TIMEOUT' | 'PROOF_INVALID' | 'PROOF_STALE';
@@ -205,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;
     };
@@ -498,12 +498,11 @@ type status2 = 'pending' | 'completed' | 'failed' | 'cancelled';
  */
 type PaymentError = {
     /**
-     * Machine-readable error code in SCREAMING_SNAKE_CASE.
+     * Public error category in SCREAMING_SNAKE_CASE.
      * Common codes:
-     * - `QUOTE_DEADLINE_EXPIRED`: No settlement quotes received in time
-     * - `QUOTE_SELECTION_FAILED`: Quotes received but none met requirements
-     * - `INSUFFICIENT_FUNDS`: Sender wallet has insufficient balance
-     * - `FULFILLMENT_TIMEOUT`: Settlement agent didn't complete in time
+     * - `SETTLEMENT_FAILED`: The settlement could not be completed
+     * - `NO_ROUTE_AVAILABLE`: No settlement route was available
+     * - `INTERNAL_ERROR`: An unexpected error occurred
      *
      */
     code: string;
@@ -749,7 +748,7 @@ type TimelineError = {
 };
 type TimelineStep = {
     /**
-     * Name of the step
+     * Internal name of the step (matches settlement event type)
      */
     name: string;
     /**
@@ -799,11 +798,30 @@ type TimelineStep = {
  *
  */
 type status4 = 'completed' | 'in_progress' | 'pending' | 'failed' | 'skipped';
+/**
+ * Safe, outward-facing error. Derived from an internal error through the shared error catalog. The public code identifies the category and the message is a curated, safe description.
+ */
 type ErrorResponse = {
     /**
-     * Error message
+     * Public, machine-readable error category in SCREAMING_SNAKE_CASE.
+     */
+    code: string;
+    /**
+     * Curated, safe, human-readable message.
+     */
+    message: string;
+    /**
+     * Correlation id to quote to support to locate the internal error record.
      */
-    error?: string;
+    request_id?: string;
+    /**
+     * Link to the documentation page for this public code.
+     */
+    docs_url?: string;
+    /**
+     * Originating service domain.
+     */
+    domain?: string;
 };
 /**
  * Request body for opening a quote-request batch. Structurally the existing PaymentRequest
@@ -877,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;
     };
@@ -959,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
@@ -981,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
@@ -1083,7 +1104,9 @@ type QuoteRequestStatusResponse = {
     /**
      * Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
      * from the payment-status enum returned by the award and payment-status endpoints.
-     * - `collecting` — collection window in progress; `quotes` absent.
+     * - `collecting` — collection window still open; `quotes` lists those collected so far
+     * (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until
+     * `collection_close`).
      * - `ready` — collection complete; none awarded yet; either at least one quote is still
      * within its `award_deadline`, or no settler bid (empty `quotes` array — the successful
      * "no quotes available" result).
@@ -1095,7 +1118,7 @@ type QuoteRequestStatusResponse = {
      */
     status: 'collecting' | 'ready' | 'awarded' | 'expired';
     /**
-     * Collected quotes with award linkage. Absent while status is `collecting`.
+     * Collected quotes with award linkage — those collected so far while `collecting`, the full set once the window closes.
      */
     quotes?: Array<AwardedQuote>;
     /**
@@ -1106,7 +1129,9 @@ type QuoteRequestStatusResponse = {
 /**
  * Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
  * from the payment-status enum returned by the award and payment-status endpoints.
- * - `collecting` — collection window in progress; `quotes` absent.
+ * - `collecting` — collection window still open; `quotes` lists those collected so far
+ * (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until
+ * `collection_close`).
  * - `ready` — collection complete; none awarded yet; either at least one quote is still
  * within its `award_deadline`, or no settler bid (empty `quotes` array — the successful
  * "no quotes available" result).
@@ -1294,10 +1319,26 @@ type $OpenApiTs = {
                  * Invalid request
                  */
                 400: ErrorResponse;
+                /**
+                 * Signature or sender authorization could not be verified
+                 */
+                401: ErrorResponse;
+                /**
+                 * Payment declined during counterparty authorization
+                 */
+                403: ErrorResponse;
+                /**
+                 * Payment request too large to process
+                 */
+                413: ErrorResponse;
                 /**
                  * Internal server error
                  */
                 500: ErrorResponse;
+                /**
+                 * A dependency is temporarily unavailable
+                 */
+                503: ErrorResponse;
             };
         };
     };
@@ -1397,6 +1438,10 @@ type $OpenApiTs = {
                  * Counterparty not found (no registration for the resolved DID)
                  */
                 404: ErrorResponse;
+                /**
+                 * Internal server error
+                 */
+                500: ErrorResponse;
                 /**
                  * Counterparty webhook error (HTTP error or connection failure)
                  */
@@ -1695,6 +1740,25 @@ declare class PaymentGatewayClient$1 {
     constructor(config?: Partial<OpenAPIConfig>, HttpRequest?: HttpRequestConstructor$1);
 }
 
+/**
+ * Chain defaults returned by the payment gateway /defaults endpoint.
+ */
+interface ChainDefaults {
+    escrowContract: string;
+    quoteSelector: string;
+    fulfillmentVerifierAccount: string;
+    fulfillmentVerifierEndpoint: string;
+    fulfillmentProxy: string;
+    permit2Contract?: string;
+    /**
+     * V3 Solana escrow domain-separation fields, surfaced by payment-gw
+     * `/defaults` for Solana source chains. Used to build the EscrowDomain that the
+     * V3 deposit hash binds to. Absent for EVM/Tron.
+     */
+    svmSignatureClusterId?: string;
+    svmSignatureDomainVersion?: number;
+}
+
 interface Logger {
     debug(obj: unknown, msg?: string): void;
     info(obj: unknown, msg?: string): void;
@@ -1737,124 +1801,6 @@ interface Meter {
 /** Reads the cluster's on-chain unix timestamp (seconds) from an RPC endpoint. */
 type SolanaClusterUnixTimeReader = (rpcUrl: string, timeoutMs: number) => Promise<bigint>;
 
-/**
- * Chain defaults returned by the payment gateway /defaults endpoint.
- */
-interface ChainDefaults {
-    escrowContract: string;
-    quoteSelector: string;
-    fulfillmentVerifierAccount: string;
-    fulfillmentVerifierEndpoint: string;
-    fulfillmentProxy: string;
-    permit2Contract?: string;
-    /**
-     * V3 Solana escrow domain-separation fields, surfaced by payment-gw
-     * `/defaults` for Solana source chains. Used to build the EscrowDomain that the
-     * V3 deposit hash binds to. Absent for EVM/Tron.
-     */
-    svmSignatureClusterId?: string;
-    svmSignatureDomainVersion?: number;
-}
-/**
- * Result of building a sender auth message for a specific chain.
- */
-interface AuthMessageResult {
-    messageScheme: SenderAuthMessageScheme;
-    messageHash: string;
-    messagePrehash: string;
-}
-/**
- * Chain-specific overrides for the request-body contract fields
- * (`quote_selector`, `fulfillment_verifier`). Some chains must rewrite the raw
- * /defaults values before they go on the wire — e.g. Tron normalizes base58
- * (`T…`) addresses to the canonical 20-byte hex the on-chain verifier and the
- * signed permit witness use. A chain that needs no rewrite returns undefined
- * and the caller falls back to the raw defaults. Applied identically on the
- * payment and quote paths, so their contract fields never diverge.
- */
-interface ContractFieldOverrides {
-    quote_selector?: string;
-    fulfillment_verifier?: {
-        account: string;
-        endpoint: string;
-    };
-}
-/**
- * Chain adapter that handles all chain-specific logic:
- * message building (SDK), key formatting, and signing (CLI).
- */
-interface ChainAdapter {
-    /**
-     * Turnkey account address format (e.g. `ADDRESS_FORMAT_ETHEREUM`), used to map a
-     * wallet account back to this chain's namespace.
-     */
-    turnkeyAddressFormat: string;
-    /**
-     * Build the sender_auth message (hash + prehash). May be async: the Solana
-     * adapter reads the on-chain cluster clock to ground `issued_at`.
-     */
-    buildAuthMessage(params: {
-        sourceAsset: string;
-        depositor: string;
-        fulfillmentAmount: string;
-        requestId: string;
-        sourceDefaults: ChainDefaults;
-        deadlineSeconds?: number;
-        /** Solana-only: override the RPC used to read the cluster clock for issued_at. */
-        solanaRpcUrl?: string;
-        /** Solana-only: injectable clock reader, primarily a test seam. */
-        solanaClockReader?: SolanaClusterUnixTimeReader;
-        /** Solana-only: optional logger; warns if the cluster clock read fails and issued_at falls back to the wall clock. */
-        solanaLogger?: Logger;
-    }): Promise<AuthMessageResult>;
-    /**
-     * Resolve chain-specific overrides for the request-body contract fields
-     * (`quote_selector`, `fulfillment_verifier`). Both preparePaymentRequest and
-     * prepareQuoteRequest resolve these fields through this one method, so the
-     * payment and quote paths always carry byte-identical contract fields.
-     * Returns undefined when the chain needs no rewrite (EVM); Tron normalizes
-     * base58 → canonical hex.
-     */
-    resolveContractOverrides?(sourceDefaults: ChainDefaults): ContractFieldOverrides | undefined;
-    /** Normalize private key format for this chain. */
-    formatPrivateKey(key: string): string;
-    /**
-     * Reject a malformed raw key value-free (throwing `Invalid private key`)
-     * before it reaches the chain's signing library. Chains whose key decoding
-     * already fails without echoing the key (e.g. Solana's bs58/length checks)
-     * omit this; EVM/Tron implement it because `ethers.Wallet` embeds the key
-     * value verbatim in its error for malformed input.
-     */
-    validatePrivateKey?(key: string): void;
-    /**
-     * Sign a sender-auth signed_messages[i] entry, returning a 0x-prefixed
-     * hex signature. The adapter chooses the appropriate signing scheme
-     * based on its chain:
-     *   - EVM:    EIP-712 typed-data signing over signedMessage.message_prehash
-     *             (which is shaped to be a direct ethers.signTypedData arg set).
-     *   - Tron:   TIP-712 typed-data signing (chain-specific quirks).
-     *   - Solana: ed25519 over a chain-specific canonicalized digest.
-     */
-    sign(signedMessage: SignedMessage, privateKey: string): Promise<string>;
-    /**
-     * Derive the base58 public key of the signing key, for chains whose signatures
-     * are NOT public-key-recoverable and must therefore ship the signer's pubkey
-     * alongside the signature. Solana (Ed25519) implements this; EVM/Tron do not
-     * (secp256k1 signatures are recoverable via ecrecover, so the verifier derives
-     * the signer from the signature itself). The result is attached to
-     * sender_auth.signed_messages[0].payload.delegate_signer so the settler can feed
-     * it to the on-chain Ed25519 verify instruction.
-     */
-    deriveDelegateSigner?(privateKey: string): string;
-    /**
-     * Assert the private key derives `address`, so a wrong key/sender pair fails
-     * fast (mirrors the Turnkey pinnedAddress check) instead of signing as the
-     * wrong depositor and only failing downstream. Throws on mismatch. The error
-     * names the addresses (public) but never the key.
-     */
-    verifyAddressMatchesKey?(privateKey: string, address: string): void;
-}
-
 /** Result of signing a sender_auth message. */
 interface SenderSignature {
     /** 0x-prefixed signature hex (65-byte secp256k1 for EVM/Tron, 64-byte ed25519 for Solana). */
@@ -1898,18 +1844,6 @@ type SenderSignerOptions = {
     provider: 'turnkey';
 } & TurnkeyConfig);
 
-/**
- * Private-key sender signer. Delegates to the chain adapter so the local-key
- * signing path is unchanged. The adapter validates the key in the constructor,
- * so a malformed EVM/Tron key can't leak via ethers even on direct construction.
- */
-declare class RawSenderSigner implements SenderSigner {
-    private readonly adapter;
-    private readonly privateKey;
-    constructor(adapter: ChainAdapter, privateKey: string);
-    sign(signedMessage: SignedMessage): Promise<SenderSignature>;
-}
-
 /** Typed contract for the lazily-loaded ./turnkey-impl module; also the test's conformance target. */
 interface TurnkeyImplModule {
     turnkeySign: (chainPrefix: string, cfg: {
@@ -1973,9 +1907,9 @@ declare const $AuthorizationResult: {
         };
         readonly error_code: {
             readonly type: "string";
-            readonly description: "Machine-readable error code (present when status is error or timeout).\nThe counterparty and webhook codes (COUNTERPARTY_NOT_FOUND, COUNTERPARTY_TIMEOUT,\nWEBHOOK_ERROR, WEBHOOK_CONNECTION_ERROR, INTERNAL_ERROR) mirror the AuthorizationErrorCode\nprotobuf enum. GATEWAY_TIMEOUT, PROOF_INVALID, and PROOF_STALE are produced by payment-gw\nitself and have no protobuf equivalent.\n";
+            readonly description: "Machine-readable error code (present when status is error or timeout).\nCounterparty-sourced codes are derived from the error code the\nCounterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and\nPROOF_STALE are payment-gw-specific (no counterparty envelope corresponds).\n";
             readonly enum: readonly ["COUNTERPARTY_NOT_FOUND", "COUNTERPARTY_TIMEOUT", "WEBHOOK_ERROR", "WEBHOOK_CONNECTION_ERROR", "INTERNAL_ERROR", "GATEWAY_TIMEOUT", "PROOF_INVALID", "PROOF_STALE"];
-            readonly 'x-enum-description': "The counterparty and webhook codes mirror the AuthorizationErrorCode protobuf enum\n(without the AUTHORIZATION_ERROR_CODE_ prefix for readability in HTTP responses).\nGATEWAY_TIMEOUT, PROOF_INVALID, and PROOF_STALE are payment-gw-local codes with no protobuf equivalent.\n";
+            readonly 'x-enum-description': "COUNTERPARTY_NOT_FOUND, COUNTERPARTY_TIMEOUT, WEBHOOK_ERROR,\nWEBHOOK_CONNECTION_ERROR, and INTERNAL_ERROR are derived from the\nerror code the Counterparty Gateway publishes.\nGATEWAY_TIMEOUT is emitted by payment-gw when no authorization\nresponse is received within the system-wide timeout — source unknown\n(counterparty delay, transport failure, or gateway unavailability).\nOriginator should retry; counterparty-side idempotency prevents PSP re-charge\nif the original was already processed.\n\nPROOF_INVALID is emitted when the W3C Data Integrity proof on the\nbeneficiary PSP's AuthorizationResponse fails verification: signature\nrecovery failed, recovered DID does not match the destination DID,\nresponse shape is malformed (missing @context / payment_id /\ncounterparty_did / proof), or the suite type is unsupported. The\nunderlying reason cardinality is collapsed so originators see one\nactionable category.\n\nPROOF_STALE is emitted when proof.created falls outside the\nconfigured freshness window. Originators should retry with a fresh\nrequest — the freshness window closes a replay attack vector where a\ncaptured-but-cryptographically-valid proof could otherwise be replayed\nindefinitely.\n";
         };
         readonly error_message: {
             readonly type: "string";
@@ -2067,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";
                 };
             };
         };
@@ -2362,8 +2296,8 @@ declare const $PaymentError: {
     readonly properties: {
         readonly code: {
             readonly type: "string";
-            readonly description: "Machine-readable error code in SCREAMING_SNAKE_CASE.\nCommon codes:\n- `QUOTE_DEADLINE_EXPIRED`: No settlement quotes received in time\n- `QUOTE_SELECTION_FAILED`: Quotes received but none met requirements\n- `INSUFFICIENT_FUNDS`: Sender wallet has insufficient balance\n- `FULFILLMENT_TIMEOUT`: Settlement agent didn't complete in time\n";
-            readonly example: "QUOTE_DEADLINE_EXPIRED";
+            readonly description: "Public error category in SCREAMING_SNAKE_CASE.\nCommon codes:\n- `SETTLEMENT_FAILED`: The settlement could not be completed\n- `NO_ROUTE_AVAILABLE`: No settlement route was available\n- `INTERNAL_ERROR`: An unexpected error occurred\n";
+            readonly example: "SETTLEMENT_FAILED";
         };
         readonly message: {
             readonly type: "string";
@@ -2626,7 +2560,7 @@ declare const $TimelineStep: {
     readonly properties: {
         readonly name: {
             readonly type: "string";
-            readonly description: "Name of the step";
+            readonly description: "Internal name of the step (matches settlement event type)";
             readonly example: "BID_AWARDED";
         };
         readonly label: {
@@ -2667,11 +2601,35 @@ declare const $TimelineStep: {
 };
 declare const $ErrorResponse: {
     readonly type: "object";
+    readonly description: "Safe, outward-facing error. Derived from an internal error through the shared error catalog. The public code identifies the category and the message is a curated, safe description.";
+    readonly required: readonly ["code", "message"];
     readonly properties: {
-        readonly error: {
+        readonly code: {
+            readonly type: "string";
+            readonly description: "Public, machine-readable error category in SCREAMING_SNAKE_CASE.";
+            readonly pattern: "^[A-Z][A-Z0-9_]*$";
+            readonly example: "INVALID_SOURCE_ASSET";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Curated, safe, human-readable message.";
+            readonly maxLength: 500;
+            readonly example: "The source asset identifier is not a valid CAIP-19 asset.";
+        };
+        readonly request_id: {
+            readonly type: "string";
+            readonly description: "Correlation id to quote to support to locate the internal error record.";
+            readonly example: "req_123456789";
+        };
+        readonly docs_url: {
             readonly type: "string";
-            readonly description: "Error message";
-            readonly example: "Invalid request: missing required field";
+            readonly format: "uri";
+            readonly description: "Link to the documentation page for this public code.";
+        };
+        readonly domain: {
+            readonly type: "string";
+            readonly description: "Originating service domain.";
+            readonly example: "PAYMENT_GATEWAY";
         };
     };
 };
@@ -2752,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";
                 };
             };
         };
@@ -2864,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";
         };
     };
@@ -2880,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: {
@@ -3014,12 +2972,12 @@ declare const $QuoteRequestStatusResponse: {
         readonly status: {
             readonly type: "string";
             readonly enum: readonly ["collecting", "ready", "awarded", "expired"];
-            readonly description: "Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint\nfrom the payment-status enum returned by the award and payment-status endpoints.\n- `collecting` — collection window in progress; `quotes` absent.\n- `ready` — collection complete; none awarded yet; either at least one quote is still\n  within its `award_deadline`, or no settler bid (empty `quotes` array — the successful\n  \"no quotes available\" result).\n- `awarded` — a quote produced a payment row; no further awards accepted (MVP).\n- `expired` — collection closed, nothing awarded, and every collected quote is now past\n  its `award_deadline` (\"quotes lapsed\"). An empty batch is `ready`, not `expired` — the\n  two are deliberately distinct (\"no quotes available\" vs \"quotes lapsed\").\n";
+            readonly description: "Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint\nfrom the payment-status enum returned by the award and payment-status endpoints.\n- `collecting` — collection window still open; `quotes` lists those collected so far\n  (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until\n  `collection_close`).\n- `ready` — collection complete; none awarded yet; either at least one quote is still\n  within its `award_deadline`, or no settler bid (empty `quotes` array — the successful\n  \"no quotes available\" result).\n- `awarded` — a quote produced a payment row; no further awards accepted (MVP).\n- `expired` — collection closed, nothing awarded, and every collected quote is now past\n  its `award_deadline` (\"quotes lapsed\"). An empty batch is `ready`, not `expired` — the\n  two are deliberately distinct (\"no quotes available\" vs \"quotes lapsed\").\n";
             readonly example: "awarded";
         };
         readonly quotes: {
             readonly type: "array";
-            readonly description: "Collected quotes with award linkage. Absent while status is `collecting`.";
+            readonly description: "Collected quotes with award linkage — those collected so far while `collecting`, the full set once the window closes.";
             readonly items: {
                 readonly $ref: "#/components/schemas/AwardedQuote";
             };
@@ -3143,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.
  *
@@ -3533,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
@@ -3568,6 +3573,32 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
     /**
      * Prepares a payment request with defaults, ready for signing.
      *
+     * By default this resolves the corridor addresses from the gateway `/defaults`
+     * endpoint. It reaches the gateway only for what the caller has NOT already
+     * supplied via `resolvedDefaults`: supply `resolvedDefaults.source` to skip the
+     * source-chain fetch and `resolvedDefaults.destination` to skip the destination
+     * fetch. Supplying both builds the request **entirely offline** (no network) —
+     * how a caller that already holds the corridor addresses (e.g. from a signed
+     * challenge) constructs and signs a request without gateway access. Such a
+     * caller typically also injects `now` so the deadlines are deterministic.
+     *
+     * @example Minimal — fetch corridor addresses from the gateway, then sign
+     * ```ts
+     * const client = new PaymentGatewayClient({ BASE: "https://gateway.example.com" });
+     *
+     * const request = await client.preparePaymentRequest({
+     *   depositor: "0xPayerAddress",
+     *   sourceAsset: "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",       // USDC on Base
+     *   destinationAccount: "0xMerchantAddress",
+     *   destinationAsset: "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
+     *   fulfillmentAmount: "10000000", // 10 USDC (6 decimals)
+     * });
+     * // max_source_amount, deadlines, request id, and nonce are all defaulted.
+     *
+     * const signer = createSenderSigner("eip155:8453", { provider: "raw", privateKey });
+     * await signPaymentRequest(request, signer); // fills sender_auth, ready to submit
+     * ```
+     *
      * @param params Payment parameters
      * @returns A complete PaymentRequest object without the signature
      */
@@ -3578,17 +3609,54 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
         destinationAccount: string;
         destinationAsset: string;
         maxSourceAmount?: string;
-        requestId?: string;
-        requestIdPrefix?: string;
+        /**
+         * REQUIRED idempotency key. It seeds the deterministic deposit nonce, so a retry that
+         * reuses the same `requestId` reproduces the same single-use permit (no double-charge),
+         * and the gateway dedups on it. The caller owns it and must reuse it on retry — there is
+         * no auto-generated fallback (a random one would silently break idempotency).
+         */
+        requestId: string;
         settlerRequirements?: {
             whitelist?: string[];
             blacklist?: string[];
         };
-        deadlineSeconds?: number;
+        /** How long the auction stays open (seconds from now). */
         quoteDeadlineSeconds?: number;
+        /** How long settlement may take (seconds from now). */
         fulfillmentDeadlineSeconds?: number;
+        /** EVM/Tron-only: the Permit2 signature's own on-chain expiry (seconds from now). */
+        deadlineSeconds?: number;
+        /** Clock source used to stamp the deadlines. Defaults to `Date.now`; inject for offline/deterministic builds. */
+        now?: () => number;
+        /**
+         * Explicit deposit-nonce override. OMIT this in normal use: the deposit's single-use nonce is
+         * then derived deterministically from `requestId` + depositor, so rebuilding the same payment
+         * reproduces the same nonce. What that guarantees differs by chain:
+         *   - EVM/Tron: the Permit2 nonce is a PERMANENT on-chain bitmap, so across any number of
+         *     rebuilds only one deposit can EVER settle — retry-safe without a time bound.
+         *   - Solana: the escrow replay nonce only protects within a ~128s window — the nonce pins the
+         *     replay slot/bucket, but `issued_at` is re-read on each build, so a rebuild in a later
+         *     window is not blocked on-chain by the nonce alone. The payment gateway's `request_id`
+         *     dedup (and the init-only deposit PDA, which blocks a byte-identical re-POST forever) are
+         *     the durable backstop; pin `issued_at` via `solanaClockReader` to keep a rebuild inside
+         *     the same window.
+         * Pass a value only to override the derived nonce.
+         */
+        nonce?: bigint | string;
         /** Solana-only: override the RPC used to read the cluster clock for issued_at. */
         solanaRpcUrl?: string;
+        /** Solana-only: injectable clock reader for `issued_at` (offline / test seam). */
+        solanaClockReader?: SolanaClusterUnixTimeReader;
+        /**
+         * Pre-resolved corridor addresses. Omit to fetch them from the gateway
+         * `/defaults`; supply to build offline. Each side is resolved independently —
+         * a field left out is still fetched. The destination contributes only its
+         * `fulfillmentProxy` (its escrow/roles are source-side concepts, unused here).
+         */
+        resolvedDefaults?: {
+            source?: ChainDefaults;
+            destination?: Pick<ChainDefaults, 'fulfillmentProxy'>;
+        };
     }): Promise<PaymentRequest>;
     /**
      * Prepares a quote-request body (`CreateQuoteRequest`), ready to POST to
@@ -3642,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 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, RawSenderSigner, type ResolvePaymentData, type ResolvePaymentResponse, type ResolvePaymentResponse2, type SenderAuth, type SenderAuthMessageScheme, type SenderSignature, type SenderSigner, type SenderSignerOptions, type SignedMessage, 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 };