@atumlabs/payment-gateway-client 2.2.0 → 3.0.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AxiosRequestConfig, AxiosResponse } from 'axios';
+import { Signer } from 'ethers';
 
 type ApiRequestOptions = {
     readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
@@ -103,7 +104,7 @@ type AuthorizationResult = {
      * Machine-readable error code (present when status is error or timeout).
      * 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).
+     * PROOF_STALE are raised by this gateway itself (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,7 +127,7 @@ type status = 'authorized' | 'declined' | 'error' | 'timeout';
  * Machine-readable error code (present when status is error or timeout).
  * 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).
+ * PROOF_STALE are raised by this gateway itself (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';
@@ -135,10 +136,7 @@ type error_code = 'COUNTERPARTY_NOT_FOUND' | 'COUNTERPARTY_TIMEOUT' | 'WEBHOOK_E
  */
 type PaymentRequest = {
     /**
-     * Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's
-     * parent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the
-     * bindings' Version constant; the canonical bumps on each additive minor evolution.
-     *
+     * Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the bindings' Version constant; the canonical bumps on each additive minor evolution.
      */
     version: string;
     /**
@@ -147,17 +145,16 @@ type PaymentRequest = {
     request_id: string;
     source: OwnedAsset;
     /**
-     * Array of destination assets for the settlement agent to choose from (at least one required)
+     * Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
+     * The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
      */
     destination: Array<OwnedAsset>;
     /**
      * The exact amount to be received at the destination (in the smallest unit, e.g., wei for ETH, cents for USD).
-     *
      */
     fulfillment_amount: string;
     /**
      * The maximum amount willing to be spent from the source (in the smallest unit).
-     *
      */
     max_source_amount?: string;
     /**
@@ -165,7 +162,6 @@ type PaymentRequest = {
      * point no new quotes are accepted. The gateway injects no default and validates the value
      * is in the future. The originator must supply it, and a request that omits it or supplies
      * a past value is rejected with 400.
-     *
      */
     quote_deadline: string;
     /**
@@ -173,12 +169,10 @@ type PaymentRequest = {
      * payment is cancelled and eligible for a refund. The gateway injects no default and validates
      * the value is in the future. The originator must supply it, and a request that omits it or
      * supplies a past value is rejected with 400.
-     *
      */
     fulfillment_deadline: string;
     /**
      * Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.
-     *
      */
     settler_auth_required?: {
         [key: string]: (boolean);
@@ -188,13 +182,11 @@ type PaymentRequest = {
     /**
      * Wallet address or public key of a trusted service that will automatically select
      * the best exchange rate for your payment. Leave empty to use the default selector.
-     *
      */
     quote_selector?: string;
     /**
      * Third-party service that will independently verify your payment was delivered.
      * Leave empty to use the default verifier.
-     *
      */
     fulfillment_verifier?: {
         /**
@@ -203,42 +195,29 @@ type PaymentRequest = {
         account: string;
         /**
          * Origin of the fulfillment verifier service, with no path — the caller
-         * appends the verifier's own API paths. The gateway's `/defaults` response
+         * appends the verifier's own API paths. The gateway's `/v1/defaults` response
          * supplies the default fulfillment verifier for each chain.
-         *
          */
         endpoint: string;
     };
     /**
      * Escrow contract address, used to protect source funds until proof of fulfillment has been verified. Leave empty to use the default.
-     *
      */
     escrow_contract_address?: string;
     /**
      * Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.
-     *
      */
     fulfillment_proxy?: string;
     /**
-     * Optional settler filtering requirements.
-     * If whitelist is present, only whitelisted settlers may win.
-     * If blacklist is present, blacklisted settlers are excluded.
-     * Both can be specified together; blacklist takes precedence
-     * (a settler in both lists is rejected).
-     *
+     * Optional settler filtering requirements. If whitelist is present, only whitelisted settlers may win. If blacklist is present, blacklisted settlers are excluded. Both can be specified; blacklist takes precedence (a settler in both lists is rejected).
      */
     settler_requirements?: {
         /**
-         * List of settler DIDs permitted to fulfill this request.
-         * If present, only these settlers may win.
-         * Use W3C DID format.
-         *
+         * List of settler DIDs permitted to fulfill this request. If present and non-empty, only these settlers may win. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
          */
         whitelist?: Array<(string)>;
         /**
-         * List of settler DIDs excluded from fulfilling this request.
-         * Use W3C DID format.
-         *
+         * List of settler DIDs excluded from fulfilling this request. If present and non-empty, these settlers are rejected. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
          */
         blacklist?: Array<(string)>;
     };
@@ -305,9 +284,7 @@ type FulfillmentConfirmation = {
     destination_block_number?: number;
 };
 /**
- * Represents a cryptocurrency or token in a specific wallet.
- * This tells the system what asset you're sending/receiving and which wallet to use.
- *
+ * Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.
  */
 type OwnedAsset = {
     /**
@@ -318,7 +295,6 @@ type OwnedAsset = {
      * - Arbitrum USDC: "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
      * - Solana USDC: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      * - Tron USDT: "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
-     *
      */
     asset_identifier: string;
     /**
@@ -328,15 +304,21 @@ type OwnedAsset = {
      * - Solana: Base58 encoded address
      * - Tron: T-prefixed Base58 address
      *
+     * A destination account is checked at ingress and must be payable on the chain named by
+     * its `asset_identifier`: it parses for that chain, carries a valid EIP-55 checksum when
+     * mixed-case, has no surrounding whitespace, and is not the zero address. A receiver that
+     * fails any of these is refused with `INVALID_DESTINATION_ACCOUNT`, before any funds move.
      */
     account: string;
 };
 /**
- * Authorization from the asset owner to execute the payment. The exact format depends on
- * the source blockchain's authorization mechanism.
- *
+ * Authorization from the asset owner to execute the payment. The exact format depends on the source blockchain's authorization mechanism.
  */
 type SenderAuth = {
+    /**
+     * DEPRECATED: inner-document credential carrier. Credentials MUST ride ONLY in the holder-signed PaymentRequestEnvelope (PRE); the inner PaymentRequest carries no credential and its Data Integrity signature EXCLUDES this field (stripped before canonicalization on both producer and verifier). Populated only for one back-compat rollout cycle, then removed.
+     * @deprecated
+     */
     verifiable_credential?: VerifiableCredentialAuth;
     message_scheme: SenderAuthMessageScheme;
     /**
@@ -347,42 +329,44 @@ type SenderAuth = {
 /**
  * The signature method used for authorizing this payment:
  * - `EVM_PERMIT2`: Gasless token approvals for Ethereum/EVM chains
+ * - `EVM_PERMIT2_ESCROW`: Gasless approvals with escrow support
  * - `SOLANA`: Standard Solana transaction signatures
  * - `TRON`: Tron transaction signatures
- *
  */
 type SenderAuthMessageScheme = 'EVM_PERMIT2' | 'EVM_PERMIT2_ESCROW' | 'SOLANA' | 'TRON';
 /**
- * A message that has been cryptographically signed to prove authorization.
- * The signature proves you control the wallet that's sending funds.
- *
+ * A message that has been cryptographically signed to prove authorization. The signature proves you control the wallet that's sending funds.
  */
 type SignedMessage = {
     /**
      * The data that was signed. Format depends on the blockchain:
      * - EVM: Hex-encoded message hash (with 0x prefix)
-     * - Solana: Base64 encoded message
+     * - Solana: Hex-encoded message hash (with 0x prefix)
      * - Tron: Hex-encoded message hash (possibly without 0x prefix)
-     *
      */
     message: string;
     /**
-     * Optional: If 'message' contains a hash, this field contains the original data
-     * before it was hashed. Useful for verification and debugging.
-     *
+     * Optional: If 'message' contains a hash, this field contains the original data before it was hashed. Useful for verification and debugging.
      */
     message_prehash?: string;
     /**
-     * The cryptographic signature proving you authorized this message.
-     * Format varies by blockchain (hex for EVM/Tron, base58 for Solana).
-     *
+     * The cryptographic signature proving you authorized this message. Hex-encoded with a 0x prefix on every supported chain. The signer's own public key is base58 on Solana, but the signature itself is not.
      */
     signature: string;
+    /**
+     * Optional chain-specific payload containing additional signing context (e.g., delegate_signer for Solana). Preserved through the pipeline for downstream consumers.
+     */
+    payload?: {
+        [key: string]: unknown;
+    };
 };
 /**
  * Optional identity verification using cryptographic credentials.
- * Required when regulatory compliance or KYC verification is needed for the payment.
  *
+ * DEPRECATED. Credentials are moving to a holder-signed W3C VerifiablePresentation that
+ * travels alongside a request rather than inside it. That envelope is not part of this
+ * HTTP contract, so there is nothing here to move them to yet: treat this as a legacy
+ * carrier, and do not build a new integration on it.
  */
 type VerifiableCredentialAuth = {
     verifiable_credential: VerifiableCredential;
@@ -432,7 +416,7 @@ type VerifiableCredential = {
         [key: string]: unknown;
     };
     /**
-     * Information for credential revocation checking
+     * Information for credential revocation checking. Not consulted by the verifier today.
      */
     credentialStatus?: {
         [key: string]: unknown;
@@ -456,6 +440,13 @@ type VerifiableCredential = {
  * request_id resolves to the same terminal payment, so a genuine re-attempt needs a
  * new request_id.
  *
+ * **A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When
+ * settlement lands inside the window you get `status: completed`, a full
+ * `fulfillment_confirmation`, and — since a quote necessarily was awarded to get there —
+ * `quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to
+ * verify: recompute `quote_hash` over the returned quote and compare it against the on-chain
+ * commitment from this response alone.
+ *
  */
 type PaymentResponse = {
     /**
@@ -510,6 +501,29 @@ type PaymentResponse = {
      *
      */
     idempotent_replay: boolean;
+    /**
+     * The winning quote's ID. Present when `status` is `completed` — a payment cannot settle
+     * without an award — and absent on a `pending` response, where no quote has been selected
+     * yet. Same value and meaning as on GET /v1/payments/{paymentId}/status.
+     *
+     */
+    quote_id?: string;
+    /**
+     * The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
+     * opaque signed document — the PREIMAGE of the `quote_hash` committed on-chain. Same
+     * value, semantics and canonicalization caveats as on
+     * GET /v1/payments/{paymentId}/status; see that field for how to verify it.
+     *
+     * Present when `status` is `completed`. It may be absent even then, if the stored quote
+     * is unreadable: the award is reported through `quote_id` regardless, so a present
+     * `quote_id` with no `fulfillment_quote` means "verification preimage unavailable" and
+     * never "no quote was awarded". A consumer that requires the preimage should fall back to
+     * the status endpoint rather than treat the payment as unverified.
+     *
+     */
+    fulfillment_quote?: {
+        [key: string]: unknown;
+    };
     fulfillment_confirmation?: FulfillmentConfirmation;
     error?: PaymentError;
 };
@@ -546,8 +560,59 @@ type GetPaymentStatusResponse = {
      * When the status was last updated
      */
     updated_at?: string;
+    /**
+     * The winning quote's ID. Present once a quote has been awarded for this payment;
+     * absent while the payment is still collecting or awarding. Cross-references the
+     * `quote_id` returned by GET /v1/payments/quote-requests/{quoteRequestId}.
+     *
+     */
+    quote_id?: string;
+    /**
+     * The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
+     * opaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at
+     * https://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has
+     * been awarded — including after the payment completes and `fulfillment_confirmation` is
+     * populated, since that is precisely when a consumer verifies.
+     *
+     * This is the PREIMAGE of the `quote_hash` committed on-chain in the escrow deposit and
+     * reserve witnesses. On-chain we commit only the hash, so a quote-selector consumer
+     * recomputes quote_hash over these bytes and compares it against the on-chain commitment
+     * to confirm the payment settled against the quote it selected ("trust but verify"), and
+     * verifies the settler signature over the same bytes.
+     *
+     * quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON
+     * key-order/whitespace normalization and across JSON string-escaping differences. The
+     * returned bytes are hash-equivalent to, but not necessarily byte-identical with, what
+     * the settler emitted (quotes are stored as JSONB, which normalizes on write). The
+     * gateway still never re-serializes the quote through a typed struct (that renormalizes
+     * timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw
+     * JSON passthrough.
+     *
+     */
+    fulfillment_quote?: {
+        [key: string]: unknown;
+    };
     fulfillment_confirmation?: FulfillmentConfirmation;
     error?: PaymentError;
+    /**
+     * How many settler agents this payment's auction was broadcast to. Absent means
+     * unknown, never zero.
+     *
+     */
+    requested_count?: number;
+    /**
+     * Why the payment drew few or no quotes. Read from the same settler reports as the
+     * quote-request endpoints, keyed by this payment, so a payment that failed on an expired
+     * quote deadline can say WHY nobody funded it instead of only that nobody did.
+     *
+     * Every declining agent is counted exactly once under its most recent reason. Empty means
+     * no agent declined against this payment, absent means the breakdown could not be read. A
+     * payment awarded out of a quote-request batch was bid on at quote time, so its declines
+     * are keyed to that batch and are read from the batch's status endpoint rather than here.
+     * As on the quote-request endpoints, the free-form decline detail is never relayed.
+     *
+     */
+    decline_summary?: Array<DeclineSummaryEntry>;
 };
 /**
  * Error details when payment status is "failed".
@@ -560,7 +625,7 @@ type PaymentError = {
      * Public error category in SCREAMING_SNAKE_CASE.
      * Common codes:
      * - `SETTLEMENT_FAILED`: The settlement could not be completed
-     * - `NO_ROUTE_AVAILABLE`: No settlement route was available
+     * - `NO_QUOTES_RECEIVED`: No quotes arrived within the auction window
      * - `INTERNAL_ERROR`: An unexpected error occurred
      *
      */
@@ -574,14 +639,14 @@ type PaymentError = {
      * Service domain where the error originated.
      *
      */
-    domain?: 'PAYMENT_GATEWAY' | 'SOLVER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
+    domain?: 'PAYMENT_GATEWAY' | 'SETTLER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
     blockchain_context?: PaymentBlockchainContext;
 };
 /**
  * Service domain where the error originated.
  *
  */
-type domain = 'PAYMENT_GATEWAY' | 'SOLVER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
+type domain = 'PAYMENT_GATEWAY' | 'SETTLER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
 /**
  * Blockchain-specific error context. Only present when the error
  * originated from an on-chain operation (e.g., escrow revert,
@@ -859,6 +924,8 @@ 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.
+ *
+ * A panic is caught by shared middleware that responds `{"error": "Internal server error occurred"}` instead, so a 500 is not guaranteed to carry this shape.
  */
 type ErrorResponse = {
     /**
@@ -873,6 +940,10 @@ type ErrorResponse = {
      * Correlation id to quote to support to locate the internal error record.
      */
     request_id?: string;
+    /**
+     * The payment this error was raised against. Absent when the error is not about a specific payment.
+     */
+    payment_id?: string;
     /**
      * Link to the documentation page for this public code.
      */
@@ -881,6 +952,11 @@ type ErrorResponse = {
      * Originating service domain.
      */
     domain?: string;
+    /**
+     * What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.
+     * Re-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.
+     */
+    retry_classification?: string;
 };
 /**
  * Request body for opening a quote-request batch. Structurally the existing PaymentRequest
@@ -903,7 +979,9 @@ type CreateQuoteRequest = {
     request_id: string;
     source: OwnedAsset;
     /**
-     * Array of destination assets for the settlement agent to choose from (at least one required).
+     * Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
+     * The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
+     *
      */
     destination: Array<OwnedAsset>;
     /**
@@ -955,7 +1033,7 @@ type CreateQuoteRequest = {
         account: string;
         /**
          * Origin of the fulfillment verifier service, with no path — the caller
-         * appends the verifier's own API paths. The gateway's `/defaults` response
+         * appends the verifier's own API paths. The gateway's `/v1/defaults` response
          * supplies the default fulfillment verifier for each chain.
          *
          */
@@ -998,31 +1076,31 @@ type CreateQuoteRequest = {
     verifiableCredential?: Array<VerifiableCredential>;
 };
 /**
- * W3C Data Integrity proof conforming to the Data Integrity 1.0 specification.
+ * W3C Data Integrity proof conforming to the Data Integrity 1.0 specification. Which of jws or proofValue is required depends on the cryptosuite named in type, and that pairing is checked where the proof is verified rather than by this schema, so a document can satisfy the schema and still be refused at verification.
  */
 type DataIntegrityProof = {
     /**
-     * Proof type identifier (e.g. EcdsaSecp256k1RecoverySignature2020).
+     * Proof type identifier. ECDSA-secp256k1 (recoverable, EVM-compatible) for did:pkh:eip155:* signers; Ed25519 for did:pkh:solana:* signers.
      */
     type: string;
     /**
-     * ISO 8601 timestamp when the proof was created.
+     * ISO 8601 timestamp when the proof was created. Canonicalize the value exactly as it appears in the raw JSON: parsing it into a date-time and re-serializing can change the spelling (Z versus +00:00), and a different spelling canonicalizes to different bytes, so the signature no longer verifies.
      */
     created: string;
     /**
-     * DID URL identifying the verification method.
+     * DID URL identifying the verification method, e.g., 'did:pkh:eip155:1:0x...#blockchainAccountId' for ECDSA or 'did:pkh:solana:<chain>:<addr>#SolanaMethod2021' for Ed25519.
      */
     verificationMethod: string;
     /**
-     * Purpose of the proof (e.g. assertionMethod, authentication).
+     * Purpose of the proof (e.g., assertionMethod, authentication).
      */
     proofPurpose: string;
     /**
-     * Detached JWS signature (header..signature format for ES256K-R).
+     * Detached JWS signature in <base64url(header)>..<base64url(sig)> form, header {alg:ES256K-R, b64:false, crit:[b64]}. Required at runtime for EcdsaSecp256k1RecoverySignature2020.
      */
     jws?: string;
     /**
-     * Alternative to jws: base-encoded proof value.
+     * Multibase-encoded raw signature bytes. Required at runtime for Ed25519Signature2020; mutually exclusive with jws in practice.
      */
     proofValue?: string;
 };
@@ -1094,6 +1172,10 @@ type AwardedPayment = {
  * fields are echoed at the response root so a drop-recovery client can build the award call
  * without retaining the original request body.
  *
+ * The corridor echoed here describes the batch you actually receive. On an idempotent
+ * replay that is the ORIGINAL batch's corridor and window, which may differ from what you
+ * just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
+ *
  */
 type QuoteRequestResponse = {
     /**
@@ -1110,6 +1192,33 @@ type QuoteRequestResponse = {
      *
      */
     status: 'collecting' | 'ready';
+    /**
+     * Whether this response describes a batch that already existed, rather than one opened
+     * by this request. `true` means the `request_id` had been used before and you are being
+     * handed the ORIGINAL batch — no second batch was opened and no second broadcast went
+     * out to settlement agents.
+     *
+     * **Re-attempting a quote-request.** Re-submit the same request and you get the same
+     * batch back. You may re-send the original bytes unchanged: `quote_deadline` bounds the
+     * collection window and is short, so it will usually have expired by the time you
+     * retry, and an expired deadline on a re-submission is not an error — the request is
+     * resolved onto the batch that already exists rather than used to open one.
+     * Re-signing with fresh deadlines is equally fine and returns the same batch.
+     *
+     * The window is NOT extended either way: it belongs to the batch, and `quote_deadline`
+     * in this response is the batch's own. Read `status` to see whether collection is
+     * still running.
+     *
+     * What you must not change under one `request_id` is the corridor's economics —
+     * accounts, assets, or amounts — which are rejected with 409
+     * IDEMPOTENCY_TERMS_MISMATCH rather than resolved onto the first batch. A genuinely
+     * different corridor needs a new `request_id`.
+     *
+     * Present on every response, `false` for a newly opened batch. A response without the
+     * field is from a gateway predating it, not a newly opened batch.
+     *
+     */
+    idempotent_replay: boolean;
     source?: OwnedAsset;
     destination?: Array<OwnedAsset>;
     fulfillment_amount?: string;
@@ -1120,6 +1229,23 @@ type QuoteRequestResponse = {
      * Collected quotes. Present when status is `ready` — an empty array if no settler bid.
      */
     quotes?: Array<Quote>;
+    /**
+     * How many agents the request was broadcast to, so silence is distinguishable from a
+     * decline without a second call. Same meaning and same absence rule as on the status
+     * endpoint: absent means unknown, never zero.
+     *
+     */
+    requested_count?: number;
+    /**
+     * Why the request drew few or no quotes, carried here so that a `ready` response with an
+     * empty `quotes` array explains itself rather than requiring a follow-up read.
+     *
+     * Same counting rules as the status endpoint: every declining agent counted exactly once
+     * under its most recent reason, empty when nobody declined, absent when the detail could not
+     * be read. Provisional while `status` is `collecting`, because agents are still responding.
+     *
+     */
+    decline_summary?: Array<DeclineSummaryEntry>;
 };
 /**
  * Collection-phase outcome of the create call:
@@ -1135,13 +1261,37 @@ type status5 = 'collecting' | 'ready';
  * Asynchronous (202) response to POST /v1/payments/quote-requests. Returns the batch handle
  * plus the echoed corridor; quotes are retrieved via the status endpoint.
  *
+ * The corridor echoed here describes the batch you actually receive. On an idempotent
+ * replay that is the ORIGINAL batch's corridor and window, which may differ from what you
+ * just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
+ *
  */
 type QuoteRequestAccepted = {
     quote_request_id: string;
     /**
-     * Always `collecting` — collection is in progress server-side.
+     * Always `collecting` — a constant on this response, not a report of the batch's state.
+     * On an idempotent replay the batch's window may already have closed; read
+     * GET /v1/payments/quote-requests/{quoteRequestId} for its actual state.
+     *
      */
     status: 'collecting';
+    /**
+     * Whether this response describes a batch that already existed, rather than one opened
+     * by this request. `true` means the `request_id` had been used before and you are being
+     * handed the ORIGINAL batch — no second batch was opened and no second broadcast went
+     * out to settlement agents.
+     *
+     * The idempotency contract is the same as on the synchronous (200) response: a
+     * re-submission may carry expired deadlines and is resolved onto the existing batch
+     * rather than rejected, the collection window is the batch's own and is not extended,
+     * and differing economics are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH rather than
+     * collapsed onto the first batch.
+     *
+     * Present on every response, `false` for a newly opened batch. A response without the
+     * field is from a gateway predating it, not a newly opened batch.
+     *
+     */
+    idempotent_replay: boolean;
     source?: OwnedAsset;
     destination?: Array<OwnedAsset>;
     fulfillment_amount?: string;
@@ -1150,7 +1300,10 @@ type QuoteRequestAccepted = {
     quote_deadline?: string;
 };
 /**
- * Always `collecting` — collection is in progress server-side.
+ * Always `collecting` — a constant on this response, not a report of the batch's state.
+ * On an idempotent replay the batch's window may already have closed; read
+ * GET /v1/payments/quote-requests/{quoteRequestId} for its actual state.
+ *
  */
 type status6 = 'collecting';
 /**
@@ -1184,6 +1337,42 @@ type QuoteRequestStatusResponse = {
      * Flat list of awarded (quote_id, payment_id) pairs. At most one entry under MVP single-award.
      */
     payments?: Array<AwardedPayment>;
+    /**
+     * How many agents the request was broadcast to. The only auction count that is not
+     * derivable from the rest of this response:
+     *
+     * - quoted = `quotes` length
+     * - declined = sum of `decline_summary[].count`
+     * - participated = quoted + declined
+     * - silent = `requested_count` - participated
+     *
+     * Silence and a decline are different signals, which is why the denominator is surfaced
+     * rather than left implicit.
+     *
+     * ABSENT when the number is unknown, which happens when the broadcast count was never
+     * recorded or when the auction detail could not be read. Absence means unknown, never zero,
+     * so `silent` is derivable only when this field is present.
+     *
+     */
+    requested_count?: number;
+    /**
+     * Why the request drew few or no quotes, so a caller can tell "nobody can fund this right
+     * now" from "my request was malformed".
+     *
+     * EXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most
+     * recent reason, so the counts sum to the number of agents that declined. An agent that
+     * declined more than once with different reasons is counted once, not once per reason.
+     *
+     * Empty means nobody declined. ABSENT means the auction detail could not be read, so the
+     * breakdown is unknown. While `status` is `collecting` it is provisional, because agents are
+     * still responding.
+     *
+     * The free-form decline detail is never relayed, because that detail carries an agent's
+     * balances and would let a caller map inventory by polling cheap quote-requests across
+     * corridors.
+     *
+     */
+    decline_summary?: Array<DeclineSummaryEntry>;
 };
 /**
  * Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
@@ -1201,6 +1390,45 @@ type QuoteRequestStatusResponse = {
  *
  */
 type status7 = 'collecting' | 'ready' | 'awarded' | 'expired';
+type DeclineSummaryEntry = {
+    reason: DeclineReason;
+    /**
+     * Agents whose most recent decline reason was this one. Counts agents, never rows, and an
+     * agent appears under one reason only.
+     *
+     */
+    count: number;
+    /**
+     * What would have to change for a settler giving this reason to bid, drawn from the same
+     * closed set as the `retry_classification` on an error response so a caller reads one
+     * vocabulary.
+     *
+     * It describes the decline only. The authoritative instruction for the payment is the
+     * `retry_classification` on its own error response: a payment can fail for a reason no
+     * settler named, and it can succeed while some settlers declined.
+     *
+     * Optional, and a pattern-constrained string for the same reason `DeclineReason` is.
+     *
+     */
+    retry_classification?: string;
+};
+/**
+ * A settler's reason for not bidding, projected from its internal reason code through
+ * the shared decline catalog (`apis/decline/v1/catalog.json`), which is the single
+ * source of truth for the reason set. Several internal codes may map to one public
+ * reason.
+ *
+ * Deliberately a pattern-constrained string rather than a closed enum. The set grows
+ * whenever a settler gains a cause worth naming, and a consumer whose generated client
+ * closes the set rejects the whole response on a value it has not seen. Treat an
+ * unrecognised value as `OTHER`.
+ *
+ * `OTHER` covers a reason whose detail is settler-authored free text, and any reason
+ * this gateway does not recognise. Both are counted so the summary stays exhaustive,
+ * without relaying text we neither author nor validate.
+ *
+ */
+type DeclineReason = string;
 /**
  * Request body for POST /v1/payments/awards. Carries the two originator-signed artifacts:
  * `sender_auth` (Permit2 deposit authorization) and a fully-formed `bid_award` declaration.
@@ -1306,6 +1534,82 @@ type AwardAccepted = {
  * Always `awarding` — settlement is in progress server-side.
  */
 type status9 = 'awarding';
+/**
+ * The addresses for one chain. Optional fields appear only where they apply to that
+ * chain; an absent optional field is not an error.
+ *
+ */
+type ChainDefaults$1 = {
+    /**
+     * CAIP-2 identifier of the chain these defaults describe, normalised to lower case.
+     */
+    chain_id: string;
+    /**
+     * The account named as the reserver in the deposit authorization. Sign against this exact value; a deposit reserved by anyone else is rejected.
+     */
+    quote_selector: string;
+    /**
+     * The escrow the deposit is made into, and the spender of the token approval. Empty when the chain is not fully configured.
+     */
+    escrow_contract: string;
+    /**
+     * The contract that pays the receiver. Read this from the DESTINATION chain's defaults, not the source chain's. Empty when the chain is not fully configured.
+     */
+    fulfillment_proxy: string;
+    /**
+     * The service that attests settlement, and the account it signs with.
+     */
+    fulfillment_verifier: {
+        /**
+         * The account named as the releaser in the deposit authorization. Sign against this exact value.
+         */
+        account: string;
+        /**
+         * Base URL of the fulfillment verifier serving this chain.
+         */
+        endpoint: string;
+    };
+    /**
+     * The Permit2 this chain's escrow verifies against, sent only when it is not the canonical deployment. When absent, use the canonical Permit2 address for the chain. EVM and Tron only.
+     */
+    permit2_contract?: string;
+    /**
+     * Which deposit witness this chain's escrow expects. `4` and above select the four-member witness, `3` the two-member one; absent means four. EVM and Tron only - on Solana this is carried by `svm_signature_domain_version`.
+     */
+    deposit_witness_version?: number;
+    /**
+     * Tokens this chain's escrow accepts for deposit. Absent when the gateway has no listing for the chain, which does not mean no token is accepted.
+     */
+    tokens?: Array<{
+        symbol: string;
+        /**
+         * Token contract address, in the chain's native address format.
+         */
+        address: string;
+        /**
+         * Decimal places, for converting a human amount to base units.
+         */
+        decimals: number;
+    }>;
+    /**
+     * Solana only. The cluster the escrow's signing domain is bound to, needed to build the deposit hash. Absent for EVM and Tron.
+     */
+    svm_signature_cluster_id?: string;
+    /**
+     * Solana only. Version of the escrow's signing domain. Absent for EVM and Tron.
+     */
+    svm_signature_domain_version?: number;
+};
+/**
+ * Either one chain's defaults or every chain keyed by CAIP-2 chain id, depending on whether `chain_id` was supplied. A top-level `chain_id` identifies the first.
+ */
+type GetDefaultsResult = ChainDefaults$1 | ChainDefaultsByChain;
+/**
+ * Defaults for every chain the gateway serves, keyed by CAIP-2 chain id. Each key repeats the `chain_id` of the value it maps to.
+ */
+type ChainDefaultsByChain = {
+    [key: string]: ChainDefaults$1;
+};
 type SubmitPaymentData = {
     requestBody: PaymentRequest;
 };
@@ -1362,6 +1666,13 @@ type AwardQuoteData = {
     wait?: boolean;
 };
 type AwardQuoteResponse = AwardResponse | AwardAccepted;
+type GetDefaultsData = {
+    /**
+     * CAIP-2 chain identifier. Omit it, or send it empty, to receive every chain the gateway serves, keyed by chain id.
+     */
+    chainId?: string;
+};
+type GetDefaultsResponse = GetDefaultsResult;
 type HealthCheckResponse = {
     status?: string;
 };
@@ -1403,7 +1714,7 @@ type $OpenApiTs = {
                  */
                 500: ErrorResponse;
                 /**
-                 * A dependency is temporarily unavailable
+                 * The request was not accepted: a dependency is temporarily unavailable, or this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the request is safe to retry.
                  */
                 503: ErrorResponse;
             };
@@ -1498,25 +1809,47 @@ type $OpenApiTs = {
                  */
                 200: AuthorizationResult;
                 /**
-                 * Invalid payment request
+                 * The request was rejected before authorization was attempted, so no
+                 * authorization outcome exists.
+                 *
                  */
                 400: ErrorResponse;
                 /**
-                 * Counterparty not found (no registration for the resolved DID)
+                 * The counterparty's proof was rejected (`PROOF_INVALID` or `PROOF_STALE`).
+                 * This is an authorization outcome, so the body is an `AuthorizationResult`
+                 * with `status: error`.
+                 *
                  */
-                404: ErrorResponse;
+                401: AuthorizationResult;
                 /**
-                 * Internal server error
+                 * Counterparty not found (no registration for the resolved DID). An
+                 * authorization outcome, so the body is an `AuthorizationResult` with
+                 * `status: error` and `error_code: COUNTERPARTY_NOT_FOUND`.
+                 *
                  */
-                500: ErrorResponse;
+                404: AuthorizationResult;
                 /**
-                 * Counterparty webhook error (HTTP error or connection failure)
+                 * Either shape, depending on where the failure happened. A failure before
+                 * authorization was attempted returns `ErrorResponse`. A failure carrying an
+                 * authorization outcome returns `AuthorizationResult` with `status: error`.
+                 *
                  */
-                502: ErrorResponse;
+                500: ErrorResponse | AuthorizationResult;
                 /**
-                 * Authorization timed out (counterparty did not respond)
+                 * Counterparty webhook error (HTTP error or connection failure). An
+                 * authorization outcome, so the body is an `AuthorizationResult` with
+                 * `status: error` and `error_code: WEBHOOK_ERROR` or
+                 * `WEBHOOK_CONNECTION_ERROR`.
+                 *
                  */
-                504: ErrorResponse;
+                502: AuthorizationResult;
+                /**
+                 * Authorization timed out (the counterparty did not respond). An
+                 * authorization outcome, so the body is an `AuthorizationResult` with
+                 * `status: timeout`.
+                 *
+                 */
+                504: AuthorizationResult;
             };
         };
     };
@@ -1535,13 +1868,30 @@ type $OpenApiTs = {
                  */
                 202: QuoteRequestAccepted;
                 /**
-                 * Invalid request
+                 * Invalid request. `QUOTE_DEADLINE_NOT_FUTURE` is the one worth planning for: a NEW
+                 * quote-request whose `quote_deadline` has already passed is refused, because there is
+                 * no window left to collect quotes in. It does not apply to a re-submission — an
+                 * already-used `request_id` resolves onto the batch that exists and its expired
+                 * deadline is ignored, which is what makes a retry recoverable.
+                 *
                  */
                 400: ErrorResponse;
+                /**
+                 * The `request_id` has already been used for a quote-request with different
+                 * economics (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a
+                 * retry is made safe, so it must identify one batch; use a distinct `request_id`
+                 * per quote-request.
+                 *
+                 */
+                409: ErrorResponse;
                 /**
                  * Internal server error
                  */
                 500: ErrorResponse;
+                /**
+                 * The request was not accepted: a dependency is temporarily unavailable, or this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the request is safe to retry.
+                 */
+                503: ErrorResponse;
             };
         };
     };
@@ -1596,6 +1946,29 @@ type $OpenApiTs = {
             };
         };
     };
+    '/v1/defaults': {
+        get: {
+            req: GetDefaultsData;
+            res: {
+                /**
+                 * Chain defaults. A single object when `chain_id` was supplied, otherwise an object keyed by CAIP-2 chain id.
+                 */
+                200: GetDefaultsResult;
+                /**
+                 * The `chain_id` is not a valid CAIP-2 chain identifier
+                 */
+                400: ErrorResponse;
+                /**
+                 * The requested chain is not served by this gateway, or - when `chain_id` was omitted - no chain could be resolved at all
+                 */
+                404: ErrorResponse;
+                /**
+                 * A dependency is temporarily unavailable
+                 */
+                503: ErrorResponse;
+            };
+        };
+    };
     '/health': {
         get: {
             res: {
@@ -1693,6 +2066,9 @@ declare class PaymentsService {
      *
      * The response includes everything needed to sign and submit a payment, except the signature itself.
      *
+     * Not available on every gateway or every source chain; where it is not, this
+     * returns `501`. Sign the returned request and submit it to `POST /v1/payments`.
+     *
      * @param data The data for the request.
      * @param data.requestBody
      * @returns PreparePaymentResponse Payment request prepared successfully
@@ -1743,6 +2119,31 @@ declare class QuoteRequestsService {
      * Collection continues server-side until the quote deadline regardless of the HTTP
      * connection, so quotes remain retrievable via the status endpoint in either mode.
      *
+     * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+     * and originator — the same key, and the same contract, as POST /v1/payments.
+     * Submitting the same `request_id` again returns the ORIGINAL batch instead of opening
+     * a second one, so a client whose request timed out or failed in transit can safely
+     * re-submit and recover its `quote_request_id`.
+     *
+     * Because a re-submission must be admissible on its own, some fields legitimately
+     * differ between attempts and are excluded from the comparison: `quote_deadline` and
+     * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+     * them) and the `proof` that covers them. An expired `quote_deadline` on a
+     * re-submission is NOT an error — the request is resolved onto the batch that already
+     * exists rather than used to open one. There is no `sender_auth` to re-sign here: this
+     * endpoint rejects it, because the spend authorization belongs to the award call.
+     *
+     * The collection window belongs to the BATCH, not to the request. Asking again with a
+     * later `quote_deadline` does not extend a window already open; `quote_deadline` in the
+     * response is the batch's own, and `status` says whether collection is still running.
+     *
+     * What must NOT differ is the corridor's economics — source account and asset,
+     * destination accounts and assets, `fulfillment_amount`, and `max_source_amount`.
+     * Re-using one `request_id` for a genuinely different corridor is a client bug that
+     * would otherwise be silently collapsed onto the first batch, returning quotes for a
+     * corridor that was never requested. It is rejected with `409` and
+     * `IDEMPOTENCY_TERMS_MISMATCH`. Use a distinct `request_id` per quote-request.
+     *
      * @param data The data for the request.
      * @param data.requestBody
      * @param data.wait Return a handle immediately (`false`, default) or hold the connection for collected quotes (`true`).
@@ -1803,6 +2204,29 @@ declare class QuoteRequestsService {
      */
     awardQuote(data: AwardQuoteData): CancelablePromise<AwardQuoteResponse>;
 }
+declare class ChainDefaultsService {
+    readonly httpRequest: BaseHttpRequest;
+    constructor(httpRequest: BaseHttpRequest);
+    /**
+     * Get chain defaults
+     * The addresses needed to build a payment on a chain: the escrow, the accounts named
+     * in the deposit authorization, and the fulfillment verifier. Fetch these rather than
+     * hardcoding them - they change when a chain's contracts are redeployed.
+     *
+     * With `chain_id`, returns that chain. Without it, or with an empty value, returns
+     * every chain the gateway serves, keyed by CAIP-2 chain id.
+     *
+     * A chain that is not fully configured is still returned when asked for by
+     * `chain_id`, with the missing address empty, but is left out of the full listing.
+     * Treat an empty address as a chain you cannot pay on.
+     *
+     * @param data The data for the request.
+     * @param data.chainId CAIP-2 chain identifier. Omit it, or send it empty, to receive every chain the gateway serves, keyed by chain id.
+     * @returns GetDefaultsResult Chain defaults. A single object when `chain_id` was supplied, otherwise an object keyed by CAIP-2 chain id.
+     * @throws ApiError
+     */
+    getDefaults(data?: GetDefaultsData): CancelablePromise<GetDefaultsResponse>;
+}
 declare class HealthService {
     readonly httpRequest: BaseHttpRequest;
     constructor(httpRequest: BaseHttpRequest);
@@ -1818,6 +2242,7 @@ declare class HealthService {
 type HttpRequestConstructor$1 = new (config: OpenAPIConfig) => BaseHttpRequest;
 declare class PaymentGatewayClient$1 {
     readonly authorizations: AuthorizationsService;
+    readonly chainDefaults: ChainDefaultsService;
     readonly health: HealthService;
     readonly payments: PaymentsService;
     readonly quoteRequests: QuoteRequestsService;
@@ -1826,7 +2251,30 @@ declare class PaymentGatewayClient$1 {
 }
 
 /**
- * Chain defaults returned by the payment gateway /defaults endpoint.
+ * Budget for a request the gateway answers as soon as it can. Generous on
+ * purpose: aborting a live submit loses track of a payment, while waiting only
+ * costs patience. Bounds socket inactivity, not total time, so a large healthy
+ * response is never cut off partway.
+ */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * Budget for a request the gateway holds open while it collects quotes or
+ * settles. Must clear the server's own cap (`payment_sync_wait_seconds` 30s,
+ * `quote_sync_wait_seconds` 5s, both deployment-configurable) with margin: the
+ * client's timer starts at connect, before the server arms its own, so an equal
+ * budget loses the race every time.
+ */
+declare const DEFAULT_SYNC_WAIT_TIMEOUT_MS = 120000;
+/** Per-client overrides for the two budgets above. */
+type RequestTimeouts = {
+    /** Requests answered as soon as possible. Defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Requests the gateway holds open. Defaults to {@link DEFAULT_SYNC_WAIT_TIMEOUT_MS}. */
+    syncWaitTimeoutMs?: number;
+};
+
+/**
+ * Chain defaults returned by the payment gateway /v1/defaults endpoint.
  */
 interface ChainDefaults {
     escrowContract: string;
@@ -1835,9 +2283,22 @@ interface ChainDefaults {
     fulfillmentVerifierEndpoint: string;
     fulfillmentProxy: string;
     permit2Contract?: string;
+    /**
+     * Which deposit witness the escrow deployed on this chain pins, surfaced by payment-gw
+     * `/v1/defaults` as `deposit_witness_version` (CORE-2033). EVM/Tron only — Solana carries the
+     * same fact in `svmSignatureDomainVersion` below.
+     *
+     * `4` and above select the CORE-2120 four-member witness
+     * (`depositRequestHash`, `destination`, `reserver`, `releaser`); `3` selects the two-member
+     * witness a not-yet-redeployed escrow pins. ABSENT means four — see the sender-auth package's
+     * `ChainDefaults.depositWitnessVersion` for why absence is the permissive default.
+     *
+     * Passed through to the sender_auth adapter verbatim; this type only has to carry it.
+     */
+    depositWitnessVersion?: number;
     /**
      * V3 Solana escrow domain-separation fields, surfaced by payment-gw
-     * `/defaults` for Solana source chains. Used to build the EscrowDomain that the
+     * `/v1/defaults` for Solana source chains. Used to build the EscrowDomain that the
      * V3 deposit hash binds to. Absent for EVM/Tron.
      */
     svmSignatureClusterId?: string;
@@ -1910,7 +2371,8 @@ interface TurnkeyConfig {
     /**
      * Chain-native address the signer is expected to resolve to. Verified against
      * the address Turnkey returns at initialize(); a mismatch fails fast rather
-     * than signing as the wrong depositor.
+     * than signing as the wrong depositor. Omit it to skip the check; an empty
+     * value is rejected rather than treated as omitted.
      */
     pinnedAddress?: string;
     /**
@@ -1920,7 +2382,10 @@ interface TurnkeyConfig {
     logger?: Logger;
     meter?: Meter;
 }
-/** Options selecting a sender-signing provider. Defaults to the private-key provider. */
+/**
+ * Options selecting a sender-signing provider. Defaults to the private-key provider.
+ * `pinnedAddress` behaves the same on both: omitted skips the sender check, empty is rejected.
+ */
 type SenderSignerOptions = {
     provider?: 'raw';
     privateKey: string;
@@ -1946,6 +2411,11 @@ declare class TurnkeySenderSigner implements SenderSigner {
     private readonly chainPrefix;
     private readonly cfg;
     private readonly loader;
+    /**
+     * Validated at construction and read from here rather than from `cfg`, so a caller that
+     * later blanks the config object it passed cannot erase the pin before it is forwarded.
+     */
+    private readonly pinnedAddress;
     constructor(chainPrefix: string, cfg: TurnkeyConfig, loader?: () => Promise<TurnkeyImplModule>);
     sign(signedMessage: SignedMessage): Promise<SenderSignature>;
 }
@@ -1962,7 +2432,88 @@ declare function createSenderSigner(sourceChainId: string, opts: SenderSignerOpt
  * query. The Turnkey impl is loaded lazily so a plain SDK import stays free of
  * @solana/web3.js.
  */
-declare function resolveTurnkeyAddresses(cfg: TurnkeyConfig): Promise<Record<string, string>>;
+declare function resolveTurnkeyAddresses(cfg: Omit<TurnkeyConfig, 'pinnedAddress'>): Promise<Record<string, string>>;
+
+/**
+ * CAIP-19 asset identifier parsing, backing the caller-facing entry points.
+ *
+ * Every caller-facing entry point parses here first. Downstream, the deposit builders read an
+ * identifier as raw string slicing (`asset.split('/')[1]!.split(':')[1]!`) and hand the result to
+ * `ethers`, which can only report a bad value as a TypeError or as `invalid address`, so the value
+ * has to be named and explained before it gets there. Parsing also canonicalizes the segments CAIP
+ * requires lowercase.
+ */
+/** An asset identifier split into its parts, canonicalized. */
+interface ParsedAssetIdentifier {
+    /** CAIP-2 chain id, namespace lowercased: `eip155:421614`. */
+    chainId: string;
+    /** Lowercased CAIP-2 namespace: `eip155`, `tron`, `solana`. */
+    namespace: string;
+    /**
+     * CAIP-2 chain reference, canonicalized per namespace, mirroring `manifest.CanonicalizeCAIP2`.
+     * A tron reference is an ASCII cluster name and folds to lowercase, so `TRON:MAINNET` routes
+     * instead of dying at a Permit2 lookup that resolves by exact chain id. A solana reference is
+     * preserved: it is base58, and its cluster name is UTF-8 encoded into the escrow's on-chain
+     * `cluster_id`, so folding it would change the signing domain.
+     */
+    reference: string;
+    /** Lowercased asset namespace: `erc20`, `trc20`, `token`, … */
+    assetNamespace: string;
+    /** Token address, exactly as the caller wrote it. */
+    tokenAddress: string;
+    /** CAIP-19 token id, for the asset types that carry one. */
+    tokenId?: string;
+    /**
+     * The identifier with the namespaces lowercased and a tron reference folded with them. The
+     * PaymentRequest schema pins `asset_identifier` to lowercase namespaces, so this is the spelling
+     * that goes on the wire and into the deposit builders.
+     *
+     * Aligned with `manifest.CanonicalizeCAIP2`, not with `blockchain.AssetIdentifier.String()`,
+     * which preserves the asset namespace this lowercases. Aligning to `String()` is not an option:
+     * the schema pattern rejects an uppercase asset namespace, so Go's own `ComputeRequestHash`
+     * refuses to hash one.
+     *
+     * Not a commitment preimage. `ComputeRequestHash` covers this string verbatim, so the spelling is
+     * the request's identity, but anything that hashes a CAIP-19 across independent producers has to
+     * derive it from one shared implementation rather than from here, since the escrow's destination
+     * commitment composes and folds the string on different rules.
+     */
+    normalized: string;
+}
+/**
+ * Parse and validate a CAIP-19 asset identifier.
+ *
+ * The two namespaces are lowercased, and a tron chain reference with them. A solana reference, the
+ * token address and the token id are returned as written, so a case-sensitive base58 value
+ * survives. Their case still matters:
+ * `ComputeRequestHash` covers the spelling verbatim, so two spellings of one asset give two
+ * different `request_hash` values while leaving the deposit digest identical.
+ */
+declare function parseAssetIdentifier(value: unknown): ParsedAssetIdentifier;
+/**
+ * The CAIP-2 chain id with its namespace lowercased, for callers that only need to route on the
+ * chain. Applies the same validation, so a malformed identifier fails with the same message.
+ */
+declare function assetChainId(value: unknown): string;
+
+/**
+ * The frozen rejection taxonomy. These strings are part of the cross-language contract: Go must
+ * reject the same input with the same reason.
+ *
+ * The union is derived from this array rather than declared beside it, so a reason cannot be added
+ * to the type without appearing here, and the coverage test that demands a vector per reason reads
+ * the same source. An array declared separately from the union would not be checked against it: a
+ * `Reason[]` may omit members freely.
+ */
+declare const REASONS: readonly ["EMPTY", "SURROUNDING_WHITESPACE", "UNSUPPORTED_NAMESPACE", "UNPARSEABLE", "ZERO"];
+type Reason = (typeof REASONS)[number];
+declare class InvalidAccountError extends Error {
+    readonly reason: Reason;
+    readonly network: string;
+    readonly account: string;
+    readonly detail: string;
+    constructor(reason: Reason, network: string, account: string, detail?: string);
+}
 
 declare const $AuthorizationResult: {
     readonly type: "object";
@@ -1972,7 +2523,7 @@ declare const $AuthorizationResult: {
         readonly payment_id: {
             readonly type: "string";
             readonly description: "Correlation key for this authorization";
-            readonly example: "0x1234abcd";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
         readonly counterparty_did: {
             readonly type: "string";
@@ -1992,9 +2543,9 @@ declare const $AuthorizationResult: {
         };
         readonly error_code: {
             readonly type: "string";
-            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 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 raised by this gateway itself (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': "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 '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 the gateway 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";
@@ -2007,13 +2558,13 @@ declare const $AuthorizationResult: {
     };
 };
 declare const $PaymentRequest: {
-    readonly type: "object";
     readonly description: "Structured payment request with sender authorization and optional W3C Verifiable Credentials";
+    readonly type: "object";
     readonly required: readonly ["version", "request_id", "source", "destination", "fulfillment_amount", "sender_auth", "quote_deadline", "fulfillment_deadline"];
     readonly properties: {
         readonly version: {
             readonly type: "string";
-            readonly description: "Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's\nparent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the\nbindings' Version constant; the canonical bumps on each additive minor evolution.\n";
+            readonly description: "Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the bindings' Version constant; the canonical bumps on each additive minor evolution.";
             readonly pattern: "^1\\.[0-9]+$";
             readonly example: "1.0";
         };
@@ -2027,37 +2578,38 @@ declare const $PaymentRequest: {
         };
         readonly destination: {
             readonly type: "array";
-            readonly description: "Array of destination assets for the settlement agent to choose from (at least one required)";
+            readonly description: "Array of destination assets for the settlement agent to choose from (at least one required, at most 16).\nThe ceiling bounds the fan-out one request can buy: every consumer iterates this list.";
             readonly minItems: 1;
+            readonly maxItems: 16;
             readonly items: {
                 readonly $ref: "#/components/schemas/OwnedAsset";
             };
         };
         readonly fulfillment_amount: {
             readonly type: "string";
-            readonly description: "The exact amount to be received at the destination (in the smallest unit, e.g., wei for ETH, cents for USD).\n";
+            readonly description: "The exact amount to be received at the destination (in the smallest unit, e.g., wei for ETH, cents for USD).";
             readonly example: "1000000";
         };
         readonly max_source_amount: {
             readonly type: "string";
-            readonly description: "The maximum amount willing to be spent from the source (in the smallest unit).\n";
+            readonly description: "The maximum amount willing to be spent from the source (in the smallest unit).";
             readonly example: "1000000";
         };
         readonly quote_deadline: {
             readonly type: "string";
             readonly format: "date-time";
-            readonly description: "Required. The deadline for receiving price quotes from settlement providers. After this\npoint no new quotes are accepted. The gateway injects no default and validates the value\nis in the future. The originator must supply it, and a request that omits it or supplies\na past value is rejected with 400.\n";
+            readonly description: "Required. The deadline for receiving price quotes from settlement providers. After this\npoint no new quotes are accepted. The gateway injects no default and validates the value\nis in the future. The originator must supply it, and a request that omits it or supplies\na past value is rejected with 400.";
             readonly example: "2024-12-25T10:30:00Z";
         };
         readonly fulfillment_deadline: {
             readonly type: "string";
             readonly format: "date-time";
-            readonly description: "Required. The final deadline for completing the payment. If not completed by this time the\npayment is cancelled and eligible for a refund. The gateway injects no default and validates\nthe value is in the future. The originator must supply it, and a request that omits it or\nsupplies a past value is rejected with 400.\n";
+            readonly description: "Required. The final deadline for completing the payment. If not completed by this time the\npayment is cancelled and eligible for a refund. The gateway injects no default and validates\nthe value is in the future. The originator must supply it, and a request that omits it or\nsupplies a past value is rejected with 400.";
             readonly example: "2024-12-25T11:00:00Z";
         };
         readonly settler_auth_required: {
             readonly type: "object";
-            readonly description: "Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.\n";
+            readonly description: "Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.";
             readonly additionalProperties: {
                 readonly type: "boolean";
             };
@@ -2070,12 +2622,12 @@ declare const $PaymentRequest: {
         };
         readonly quote_selector: {
             readonly type: "string";
-            readonly description: "Wallet address or public key of a trusted service that will automatically select \nthe best exchange rate for your payment. Leave empty to use the default selector.\n";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly description: "Wallet address or public key of a trusted service that will automatically select\nthe best exchange rate for your payment. Leave empty to use the default selector.";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly fulfillment_verifier: {
             readonly type: "object";
-            readonly description: "Third-party service that will independently verify your payment was delivered.\nLeave empty to use the default verifier.\n";
+            readonly description: "Third-party service that will independently verify your payment was delivered.\nLeave empty to use the default verifier.";
             readonly required: readonly ["account", "endpoint"];
             readonly properties: {
                 readonly account: {
@@ -2086,48 +2638,48 @@ declare const $PaymentRequest: {
                 readonly endpoint: {
                     readonly type: "string";
                     readonly format: "uri";
-                    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 description: "Origin of the fulfillment verifier service, with no path — the caller\nappends the verifier's own API paths. The gateway's `/v1/defaults` response\nsupplies the default fulfillment verifier for each chain.";
                     readonly example: "https://veri-fill.production-testnet.atum.xyz";
                 };
             };
         };
         readonly escrow_contract_address: {
             readonly type: "string";
-            readonly description: "Escrow contract address, used to protect source funds until proof of fulfillment has been verified. Leave empty to use the default.\n";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly description: "Escrow contract address, used to protect source funds until proof of fulfillment has been verified. Leave empty to use the default.";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly fulfillment_proxy: {
             readonly type: "string";
-            readonly description: "Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.\n";
+            readonly description: "Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.";
             readonly example: "0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F";
         };
         readonly settler_requirements: {
             readonly type: "object";
-            readonly description: "Optional settler filtering requirements.\nIf whitelist is present, only whitelisted settlers may win.\nIf blacklist is present, blacklisted settlers are excluded.\nBoth can be specified together; blacklist takes precedence\n(a settler in both lists is rejected).\n";
+            readonly description: "Optional settler filtering requirements. If whitelist is present, only whitelisted settlers may win. If blacklist is present, blacklisted settlers are excluded. Both can be specified; blacklist takes precedence (a settler in both lists is rejected).";
             readonly properties: {
                 readonly whitelist: {
                     readonly type: "array";
-                    readonly description: "List of settler DIDs permitted to fulfill this request.\nIf present, only these settlers may win.\nUse W3C DID format.\n";
+                    readonly uniqueItems: true;
                     readonly minItems: 1;
                     readonly maxItems: 100;
-                    readonly uniqueItems: true;
+                    readonly description: "List of settler DIDs permitted to fulfill this request. If present and non-empty, only these settlers may win. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).";
                     readonly items: {
                         readonly type: "string";
                         readonly pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$";
                     };
-                    readonly example: readonly ["did:pkh:eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f4136"];
+                    readonly example: readonly ["did:pkh:eip155:1:0x742D35cC6634c0532925a3b844Bc9e7595F41360"];
                 };
                 readonly blacklist: {
                     readonly type: "array";
-                    readonly description: "List of settler DIDs excluded from fulfilling this request.\nUse W3C DID format.\n";
+                    readonly uniqueItems: true;
                     readonly minItems: 1;
                     readonly maxItems: 100;
-                    readonly uniqueItems: true;
+                    readonly description: "List of settler DIDs excluded from fulfilling this request. If present and non-empty, these settlers are rejected. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).";
                     readonly items: {
                         readonly type: "string";
                         readonly pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$";
                     };
-                    readonly example: readonly ["did:pkh:eip155:1:0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4432F"];
+                    readonly example: readonly ["did:pkh:eip155:1:0x892bb2E4F6b14a2B5b82bA8D33e5925d42d4432f"];
                 };
             };
         };
@@ -2190,31 +2742,33 @@ declare const $FulfillmentConfirmation: {
 };
 declare const $OwnedAsset: {
     readonly type: "object";
-    readonly description: "Represents a cryptocurrency or token in a specific wallet.\nThis tells the system what asset you're sending/receiving and which wallet to use.\n";
+    readonly description: "Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.";
     readonly required: readonly ["asset_identifier", "account"];
     readonly properties: {
         readonly asset_identifier: {
             readonly type: "string";
-            readonly description: "A unique identifier for the asset using CAIP-19 format.\nCAIP-19 is a standard way to identify blockchain assets: {chain_id}/{asset_namespace}:{asset_reference}\nExamples:\n- Ethereum USDC: \"eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\"\n- Arbitrum USDC: \"eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n- Solana USDC: \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\"\n- Tron USDT: \"tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\"\n";
+            readonly description: "A unique identifier for the asset using CAIP-19 format.\nCAIP-19 is a standard way to identify blockchain assets: {chain_id}/{asset_namespace}:{asset_reference}\nExamples:\n- Ethereum USDC: \"eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\"\n- Arbitrum USDC: \"eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n- Solana USDC: \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\"\n- Tron USDT: \"tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\"";
             readonly pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+/[a-z0-9-]{3,8}:[-.%a-zA-Z0-9]{1,128}(/[-.%a-zA-Z0-9]{1,78})?$";
             readonly example: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
         };
         readonly account: {
             readonly type: "string";
-            readonly description: "The wallet address that owns this asset.\nFormat depends on the blockchain:\n- Ethereum/EVM: 0x-prefixed hex address (42 characters)\n- Solana: Base58 encoded address\n- Tron: T-prefixed Base58 address\n";
+            readonly description: "The wallet address that owns this asset.\nFormat depends on the blockchain:\n- Ethereum/EVM: 0x-prefixed hex address (42 characters)\n- Solana: Base58 encoded address\n- Tron: T-prefixed Base58 address\n\nA destination account is checked at ingress and must be payable on the chain named by\nits `asset_identifier`: it parses for that chain, carries a valid EIP-55 checksum when\nmixed-case, has no surrounding whitespace, and is not the zero address. A receiver that\nfails any of these is refused with `INVALID_DESTINATION_ACCOUNT`, before any funds move.";
             readonly minLength: 1;
             readonly maxLength: 128;
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
     };
 };
 declare const $SenderAuth: {
     readonly type: "object";
-    readonly description: "Authorization from the asset owner to execute the payment. The exact format depends on \nthe source blockchain's authorization mechanism.\n";
+    readonly description: "Authorization from the asset owner to execute the payment. The exact format depends on the source blockchain's authorization mechanism.";
     readonly required: readonly ["message_scheme", "signed_messages"];
     readonly properties: {
         readonly verifiable_credential: {
             readonly $ref: "#/components/schemas/VerifiableCredentialAuth";
+            readonly deprecated: true;
+            readonly description: "DEPRECATED: inner-document credential carrier. Credentials MUST ride ONLY in the holder-signed PaymentRequestEnvelope (PRE); the inner PaymentRequest carries no credential and its Data Integrity signature EXCLUDES this field (stripped before canonicalization on both producer and verifier). Populated only for one back-compat rollout cycle, then removed.";
         };
         readonly message_scheme: {
             readonly $ref: "#/components/schemas/SenderAuthMessageScheme";
@@ -2231,34 +2785,42 @@ declare const $SenderAuth: {
 };
 declare const $SenderAuthMessageScheme: {
     readonly type: "string";
-    readonly description: "The signature method used for authorizing this payment:\n- `EVM_PERMIT2`: Gasless token approvals for Ethereum/EVM chains\n- `SOLANA`: Standard Solana transaction signatures\n- `TRON`: Tron transaction signatures\n";
+    readonly description: "The signature method used for authorizing this payment:\n- `EVM_PERMIT2`: Gasless token approvals for Ethereum/EVM chains\n- `EVM_PERMIT2_ESCROW`: Gasless approvals with escrow support\n- `SOLANA`: Standard Solana transaction signatures\n- `TRON`: Tron transaction signatures";
     readonly enum: readonly ["EVM_PERMIT2", "EVM_PERMIT2_ESCROW", "SOLANA", "TRON"];
 };
 declare const $SignedMessage: {
     readonly type: "object";
-    readonly description: "A message that has been cryptographically signed to prove authorization.\nThe signature proves you control the wallet that's sending funds.\n";
+    readonly description: "A message that has been cryptographically signed to prove authorization. The signature proves you control the wallet that's sending funds.";
     readonly required: readonly ["message", "signature"];
     readonly properties: {
         readonly message: {
             readonly type: "string";
-            readonly description: "The data that was signed. Format depends on the blockchain:\n- EVM: Hex-encoded message hash (with 0x prefix)\n- Solana: Base64 encoded message\n- Tron: Hex-encoded message hash (possibly without 0x prefix)\n";
+            readonly description: "The data that was signed. Format depends on the blockchain:\n- EVM: Hex-encoded message hash (with 0x prefix)\n- Solana: Hex-encoded message hash (with 0x prefix)\n- Tron: Hex-encoded message hash (possibly without 0x prefix)";
             readonly example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
         };
         readonly message_prehash: {
             readonly type: "string";
-            readonly description: "Optional: If 'message' contains a hash, this field contains the original data\nbefore it was hashed. Useful for verification and debugging.\n";
+            readonly description: "Optional: If 'message' contains a hash, this field contains the original data before it was hashed. Useful for verification and debugging.";
             readonly example: "{\"permit\":{\"token\":\"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\",\"amount\":\"1000000\"}}";
         };
         readonly signature: {
             readonly type: "string";
-            readonly description: "The cryptographic signature proving you authorized this message.\nFormat varies by blockchain (hex for EVM/Tron, base58 for Solana).\n";
+            readonly description: "The cryptographic signature proving you authorized this message. Hex-encoded with a 0x prefix on every supported chain. The signer's own public key is base58 on Solana, but the signature itself is not.";
             readonly example: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab1c";
         };
+        readonly payload: {
+            readonly type: "object";
+            readonly description: "Optional chain-specific payload containing additional signing context (e.g., delegate_signer for Solana). Preserved through the pipeline for downstream consumers.";
+            readonly additionalProperties: true;
+            readonly example: {
+                readonly delegate_signer: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin";
+            };
+        };
     };
 };
 declare const $VerifiableCredentialAuth: {
     readonly type: "object";
-    readonly description: "Optional identity verification using cryptographic credentials.\nRequired when regulatory compliance or KYC verification is needed for the payment.\n";
+    readonly description: "Optional identity verification using cryptographic credentials.\n\nDEPRECATED. Credentials are moving to a holder-signed W3C VerifiablePresentation that\ntravels alongside a request rather than inside it. That envelope is not part of this\nHTTP contract, so there is nothing here to move them to yet: treat this as a legacy\ncarrier, and do not build a new integration on it.";
     readonly required: readonly ["verifiable_credential", "verification_method_id", "signature"];
     readonly properties: {
         readonly verifiable_credential: {
@@ -2324,7 +2886,7 @@ declare const $VerifiableCredential: {
         };
         readonly credentialStatus: {
             readonly type: "object";
-            readonly description: "Information for credential revocation checking";
+            readonly description: "Information for credential revocation checking. Not consulted by the verifier today.";
             readonly additionalProperties: true;
         };
         readonly proof: {
@@ -2336,13 +2898,13 @@ declare const $VerifiableCredential: {
 };
 declare const $PaymentResponse: {
     readonly type: "object";
-    readonly description: "Response from submitting a payment request. If settlement completes inside the\ngateway's synchronous window, the response includes a fulfillment_confirmation with\nfull settlement details. Otherwise you receive a payment_id plus the payment's\ncurrent `status`, and can poll /v1/payments/{paymentId}/status for updates.\n\nRead `status` before deciding what to do next: a `pending` payment is in flight and\nmust NOT be re-submitted under a new request_id (that would be a second payment),\nwhereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME\nrequest_id resolves to the same terminal payment, so a genuine re-attempt needs a\nnew request_id.\n";
+    readonly description: "Response from submitting a payment request. If settlement completes inside the\ngateway's synchronous window, the response includes a fulfillment_confirmation with\nfull settlement details. Otherwise you receive a payment_id plus the payment's\ncurrent `status`, and can poll /v1/payments/{paymentId}/status for updates.\n\nRead `status` before deciding what to do next: a `pending` payment is in flight and\nmust NOT be re-submitted under a new request_id (that would be a second payment),\nwhereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME\nrequest_id resolves to the same terminal payment, so a genuine re-attempt needs a\nnew request_id.\n\n**A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When\nsettlement lands inside the window you get `status: completed`, a full\n`fulfillment_confirmation`, and — since a quote necessarily was awarded to get there —\n`quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to\nverify: recompute `quote_hash` over the returned quote and compare it against the on-chain\ncommitment from this response alone.\n";
     readonly required: readonly ["payment_id", "status", "idempotent_replay"];
     readonly properties: {
         readonly payment_id: {
             readonly type: "string";
             readonly description: "Unique ID for tracking this payment. Save this to check status later.\n";
-            readonly example: "550e8400-e29b-41d4-a716-446655440000";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
         readonly status: {
             readonly type: "string";
@@ -2354,6 +2916,16 @@ declare const $PaymentResponse: {
             readonly description: "Whether this response describes a payment that already existed, rather than one\ncreated by this request. `true` means the request_id had been used before and you\nare being handed the ORIGINAL payment — no second payment was created and nothing\nadditional was charged.\n\n**Re-attempting a payment.** Re-submit the same request and you get the same payment\nback. You may re-send the original bytes unchanged: the deadlines will have expired by\nthen — `quote_deadline` bounds the auction and is short, while this endpoint may hold a\nsubmission for up to 30 seconds — and an expired deadline on a re-submission is not an\nerror, because the request is resolved onto the payment that already exists rather than\nused to create one.\n\nRe-signing with fresh deadlines is equally fine and returns the same payment. What you\nmust NOT change is the request_id, and what you must not change under it is the\npayment's economics — source, destination, fulfillment_amount, max_source_amount — which\nare rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are\nexempt precisely so that a re-attempt is possible.\n\nA genuinely new payment needs a NEW request_id. In particular a `failed` payment is\nterminal: re-submitting its request_id keeps returning that dead payment, so recovering\nmeans starting a new one under a new key.\n\nPresent on every response, `false` for a newly created payment. A response without\nthe field is from a gateway predating it, not a newly created payment.\n\nThis is the field to read when reconciling a suspected double charge: two\nsubmissions where the second reports `true` are one payment, whereas two both\nreporting `false` are two. It says nothing about how far the payment has got —\nread `status` for that.\n";
             readonly example: false;
         };
+        readonly quote_id: {
+            readonly type: "string";
+            readonly description: "The winning quote's ID. Present when `status` is `completed` — a payment cannot settle\nwithout an award — and absent on a `pending` response, where no quote has been selected\nyet. Same value and meaning as on GET /v1/payments/{paymentId}/status.\n";
+            readonly example: "0x9a3b...e8d4";
+        };
+        readonly fulfillment_quote: {
+            readonly type: "object";
+            readonly description: "The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an\nopaque signed document — the PREIMAGE of the `quote_hash` committed on-chain. Same\nvalue, semantics and canonicalization caveats as on\nGET /v1/payments/{paymentId}/status; see that field for how to verify it.\n\nPresent when `status` is `completed`. It may be absent even then, if the stored quote\nis unreadable: the award is reported through `quote_id` regardless, so a present\n`quote_id` with no `fulfillment_quote` means \"verification preimage unavailable\" and\nnever \"no quote was awarded\". A consumer that requires the preimage should fall back to\nthe status endpoint rather than treat the payment as unverified.\n";
+            readonly 'x-go-type': "json.RawMessage";
+        };
         readonly fulfillment_confirmation: {
             readonly $ref: "#/components/schemas/FulfillmentConfirmation";
         };
@@ -2368,7 +2940,7 @@ declare const $GetPaymentStatusResponse: {
         readonly payment_id: {
             readonly type: "string";
             readonly description: "The payment ID you're checking status for.\n";
-            readonly example: "550e8400-e29b-41d4-a716-446655440000";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
         readonly status: {
             readonly type: "string";
@@ -2380,12 +2952,34 @@ declare const $GetPaymentStatusResponse: {
             readonly format: "date-time";
             readonly description: "When the status was last updated";
         };
+        readonly quote_id: {
+            readonly type: "string";
+            readonly description: "The winning quote's ID. Present once a quote has been awarded for this payment;\nabsent while the payment is still collecting or awarding. Cross-references the\n`quote_id` returned by GET /v1/payments/quote-requests/{quoteRequestId}.\n";
+            readonly example: "0x9a3b...e8d4";
+        };
+        readonly fulfillment_quote: {
+            readonly type: "object";
+            readonly description: "The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an\nopaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at\nhttps://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has\nbeen awarded — including after the payment completes and `fulfillment_confirmation` is\npopulated, since that is precisely when a consumer verifies.\n\nThis is the PREIMAGE of the `quote_hash` committed on-chain in the escrow deposit and\nreserve witnesses. On-chain we commit only the hash, so a quote-selector consumer\nrecomputes quote_hash over these bytes and compares it against the on-chain commitment\nto confirm the payment settled against the quote it selected (\"trust but verify\"), and\nverifies the settler signature over the same bytes.\n\nquote_hash is canonicalization-based (URDNA2015), so it is stable across JSON\nkey-order/whitespace normalization and across JSON string-escaping differences. The\nreturned bytes are hash-equivalent to, but not necessarily byte-identical with, what\nthe settler emitted (quotes are stored as JSONB, which normalizes on write). The\ngateway still never re-serializes the quote through a typed struct (that renormalizes\ntimestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw\nJSON passthrough.\n";
+            readonly 'x-go-type': "json.RawMessage";
+        };
         readonly fulfillment_confirmation: {
             readonly $ref: "#/components/schemas/FulfillmentConfirmation";
         };
         readonly error: {
             readonly $ref: "#/components/schemas/PaymentError";
         };
+        readonly requested_count: {
+            readonly type: "integer";
+            readonly description: "How many settler agents this payment's auction was broadcast to. Absent means\nunknown, never zero.\n";
+            readonly example: 8;
+        };
+        readonly decline_summary: {
+            readonly type: "array";
+            readonly description: "Why the payment drew few or no quotes. Read from the same settler reports as the\nquote-request endpoints, keyed by this payment, so a payment that failed on an expired\nquote deadline can say WHY nobody funded it instead of only that nobody did.\n\nEvery declining agent is counted exactly once under its most recent reason. Empty means\nno agent declined against this payment, absent means the breakdown could not be read. A\npayment awarded out of a quote-request batch was bid on at quote time, so its declines\nare keyed to that batch and are read from the batch's status endpoint rather than here.\nAs on the quote-request endpoints, the free-form decline detail is never relayed.\n";
+            readonly items: {
+                readonly $ref: "#/components/schemas/DeclineSummaryEntry";
+            };
+        };
     };
 };
 declare const $PaymentError: {
@@ -2395,7 +2989,7 @@ declare const $PaymentError: {
     readonly properties: {
         readonly code: {
             readonly type: "string";
-            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 description: "Public error category in SCREAMING_SNAKE_CASE.\nCommon codes:\n- `SETTLEMENT_FAILED`: The settlement could not be completed\n- `NO_QUOTES_RECEIVED`: No quotes arrived within the auction window\n- `INTERNAL_ERROR`: An unexpected error occurred\n";
             readonly example: "SETTLEMENT_FAILED";
         };
         readonly message: {
@@ -2406,7 +3000,7 @@ declare const $PaymentError: {
         readonly domain: {
             readonly type: "string";
             readonly description: "Service domain where the error originated.\n";
-            readonly enum: readonly ["PAYMENT_GATEWAY", "SOLVER_GATEWAY", "SETTLER_AGENT", "WALLET_ORCHESTRATION", "VERIFICATION_SERVICE", "BLOCKCHAIN", "EXTERNAL_SERVICE"];
+            readonly enum: readonly ["PAYMENT_GATEWAY", "SETTLER_GATEWAY", "SETTLER_AGENT", "WALLET_ORCHESTRATION", "VERIFICATION_SERVICE", "BLOCKCHAIN", "EXTERNAL_SERVICE"];
             readonly example: "PAYMENT_GATEWAY";
         };
         readonly blockchain_context: {
@@ -2473,7 +3067,7 @@ declare const $PreparePaymentRequest: {
         readonly source_account: {
             readonly type: "string";
             readonly description: "Wallet address that will send the payment";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly destination_asset: {
             readonly type: "string";
@@ -2588,7 +3182,7 @@ declare const $PaymentSummary: {
         };
         readonly source_account: {
             readonly type: "string";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly dest_asset: {
             readonly type: "string";
@@ -2700,7 +3294,7 @@ 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 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.\n\nA panic is caught by shared middleware that responds `{\"error\": \"Internal server error occurred\"}` instead, so a 500 is not guaranteed to carry this shape.";
     readonly required: readonly ["code", "message"];
     readonly properties: {
         readonly code: {
@@ -2720,6 +3314,11 @@ declare const $ErrorResponse: {
             readonly description: "Correlation id to quote to support to locate the internal error record.";
             readonly example: "req_123456789";
         };
+        readonly payment_id: {
+            readonly type: "string";
+            readonly description: "The payment this error was raised against. Absent when the error is not about a specific payment.";
+            readonly example: "0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c";
+        };
         readonly docs_url: {
             readonly type: "string";
             readonly format: "uri";
@@ -2730,6 +3329,11 @@ declare const $ErrorResponse: {
             readonly description: "Originating service domain.";
             readonly example: "PAYMENT_GATEWAY";
         };
+        readonly retry_classification: {
+            readonly type: "string";
+            readonly description: "What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.";
+            readonly example: "RECONCILE_THEN_DECIDE";
+        };
     };
 };
 declare const $CreateQuoteRequest: {
@@ -2753,8 +3357,9 @@ declare const $CreateQuoteRequest: {
         };
         readonly destination: {
             readonly type: "array";
-            readonly description: "Array of destination assets for the settlement agent to choose from (at least one required).";
+            readonly description: "Array of destination assets for the settlement agent to choose from (at least one required, at most 16).\nThe ceiling bounds the fan-out one request can buy: every consumer iterates this list.\n";
             readonly minItems: 1;
+            readonly maxItems: 16;
             readonly items: {
                 readonly $ref: "#/components/schemas/OwnedAsset";
             };
@@ -2794,7 +3399,7 @@ declare const $CreateQuoteRequest: {
         readonly quote_selector: {
             readonly type: "string";
             readonly description: "Wallet address or public key of a trusted service that auto-selects the best rate.\nLeave empty to use the default selector.\n";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly fulfillment_verifier: {
             readonly type: "object";
@@ -2809,7 +3414,7 @@ declare const $CreateQuoteRequest: {
                 readonly endpoint: {
                     readonly type: "string";
                     readonly format: "uri";
-                    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 description: "Origin of the fulfillment verifier service, with no path — the caller\nappends the verifier's own API paths. The gateway's `/v1/defaults` response\nsupplies the default fulfillment verifier for each chain.\n";
                     readonly example: "https://veri-fill.production-testnet.atum.xyz";
                 };
             };
@@ -2817,7 +3422,7 @@ declare const $CreateQuoteRequest: {
         readonly escrow_contract_address: {
             readonly type: "string";
             readonly description: "Optional escrow contract address. Leave empty to use the default.";
-            readonly example: "0x742d35Cc6634C0532925a3b844Bc9e7595f4136";
+            readonly example: "0x742D35cC6634c0532925a3b844Bc9e7595F41360";
         };
         readonly fulfillment_proxy: {
             readonly type: "string";
@@ -2838,7 +3443,7 @@ declare const $CreateQuoteRequest: {
                         readonly type: "string";
                         readonly pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$";
                     };
-                    readonly example: readonly ["did:pkh:eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f4136"];
+                    readonly example: readonly ["did:pkh:eip155:1:0x742D35cC6634c0532925a3b844Bc9e7595F41360"];
                 };
                 readonly blacklist: {
                     readonly type: "array";
@@ -2850,7 +3455,7 @@ declare const $CreateQuoteRequest: {
                         readonly type: "string";
                         readonly pattern: "^did:[a-z][a-z0-9]*:[a-zA-Z0-9._:%-]+$";
                     };
-                    readonly example: readonly ["did:pkh:eip155:1:0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4432F"];
+                    readonly example: readonly ["did:pkh:eip155:1:0x892bb2E4F6b14a2B5b82bA8D33e5925d42d4432f"];
                 };
             };
         };
@@ -2875,37 +3480,37 @@ declare const $CreateQuoteRequest: {
 };
 declare const $DataIntegrityProof: {
     readonly type: "object";
-    readonly description: "W3C Data Integrity proof conforming to the Data Integrity 1.0 specification.";
+    readonly description: "W3C Data Integrity proof conforming to the Data Integrity 1.0 specification. Which of jws or proofValue is required depends on the cryptosuite named in type, and that pairing is checked where the proof is verified rather than by this schema, so a document can satisfy the schema and still be refused at verification.";
     readonly required: readonly ["type", "created", "verificationMethod", "proofPurpose"];
     readonly properties: {
         readonly type: {
             readonly type: "string";
-            readonly description: "Proof type identifier (e.g. EcdsaSecp256k1RecoverySignature2020).";
+            readonly description: "Proof type identifier. ECDSA-secp256k1 (recoverable, EVM-compatible) for did:pkh:eip155:* signers; Ed25519 for did:pkh:solana:* signers.";
             readonly example: "EcdsaSecp256k1RecoverySignature2020";
         };
         readonly created: {
             readonly type: "string";
             readonly format: "date-time";
-            readonly description: "ISO 8601 timestamp when the proof was created.";
+            readonly description: "ISO 8601 timestamp when the proof was created. Canonicalize the value exactly as it appears in the raw JSON: parsing it into a date-time and re-serializing can change the spelling (Z versus +00:00), and a different spelling canonicalizes to different bytes, so the signature no longer verifies.";
             readonly example: "2026-04-29T12:00:00Z";
         };
         readonly verificationMethod: {
             readonly type: "string";
-            readonly description: "DID URL identifying the verification method.";
+            readonly description: "DID URL identifying the verification method, e.g., 'did:pkh:eip155:1:0x...#blockchainAccountId' for ECDSA or 'did:pkh:solana:<chain>:<addr>#SolanaMethod2021' for Ed25519.";
             readonly example: "did:pkh:eip155:42161:0xabc...#blockchainAccountId";
         };
         readonly proofPurpose: {
             readonly type: "string";
-            readonly description: "Purpose of the proof (e.g. assertionMethod, authentication).";
+            readonly description: "Purpose of the proof (e.g., assertionMethod, authentication).";
             readonly example: "assertionMethod";
         };
         readonly jws: {
             readonly type: "string";
-            readonly description: "Detached JWS signature (header..signature format for ES256K-R).";
+            readonly description: "Detached JWS signature in <base64url(header)>..<base64url(sig)> form, header {alg:ES256K-R, b64:false, crit:[b64]}. Required at runtime for EcdsaSecp256k1RecoverySignature2020.";
         };
         readonly proofValue: {
             readonly type: "string";
-            readonly description: "Alternative to jws: base-encoded proof value.";
+            readonly description: "Multibase-encoded raw signature bytes. Required at runtime for Ed25519Signature2020; mutually exclusive with jws in practice.";
         };
     };
 };
@@ -2944,7 +3549,7 @@ declare const $AwardedQuote: {
             readonly type: "string";
             readonly nullable: true;
             readonly description: "payment_id if this quote was awarded; null otherwise. Under MVP single-award, at most\none quote per batch carries a non-null value.\n";
-            readonly example: "py_9876fedc-ba98-7654-3210-fedcba987654";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
     };
 };
@@ -2959,14 +3564,14 @@ declare const $AwardedPayment: {
         };
         readonly payment_id: {
             readonly type: "string";
-            readonly example: "py_9876fedc-ba98-7654-3210-fedcba987654";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
     };
 };
 declare const $QuoteRequestResponse: {
     readonly type: "object";
-    readonly description: "Synchronous response to POST /v1/payments/quote-requests. Self-contained — the corridor\nfields are echoed at the response root so a drop-recovery client can build the award call\nwithout retaining the original request body.\n";
-    readonly required: readonly ["quote_request_id", "status"];
+    readonly description: "Synchronous response to POST /v1/payments/quote-requests. Self-contained — the corridor\nfields are echoed at the response root so a drop-recovery client can build the award call\nwithout retaining the original request body.\n\nThe corridor echoed here describes the batch you actually receive. On an idempotent\nreplay that is the ORIGINAL batch's corridor and window, which may differ from what you\njust sent in the ways a retry is allowed to differ (the deadlines, and address casing).\n";
+    readonly required: readonly ["quote_request_id", "status", "idempotent_replay"];
     readonly properties: {
         readonly quote_request_id: {
             readonly type: "string";
@@ -2979,6 +3584,10 @@ declare const $QuoteRequestResponse: {
             readonly description: "Collection-phase outcome of the create call:\n- `ready` — collection complete; `quotes` populated. If no settler bid, this is still\n  `ready` with an empty `quotes` array (a successful \"no quotes available\" result —\n  distinct from `expired`, which only applies to collected quotes that later lapse).\n- `collecting` — the sync wait cap fired before the quote deadline; poll the status endpoint for quotes.\nThe `awarded` and `expired` lifecycle states are observed only via the status endpoint, not here.\n";
             readonly example: "ready";
         };
+        readonly idempotent_replay: {
+            readonly type: "boolean";
+            readonly description: "Whether this response describes a batch that already existed, rather than one opened\nby this request. `true` means the `request_id` had been used before and you are being\nhanded the ORIGINAL batch — no second batch was opened and no second broadcast went\nout to settlement agents.\n\n**Re-attempting a quote-request.** Re-submit the same request and you get the same\nbatch back. You may re-send the original bytes unchanged: `quote_deadline` bounds the\ncollection window and is short, so it will usually have expired by the time you\nretry, and an expired deadline on a re-submission is not an error — the request is\nresolved onto the batch that already exists rather than used to open one.\nRe-signing with fresh deadlines is equally fine and returns the same batch.\n\nThe window is NOT extended either way: it belongs to the batch, and `quote_deadline`\nin this response is the batch's own. Read `status` to see whether collection is\nstill running.\n\nWhat you must not change under one `request_id` is the corridor's economics —\naccounts, assets, or amounts — which are rejected with 409\nIDEMPOTENCY_TERMS_MISMATCH rather than resolved onto the first batch. A genuinely\ndifferent corridor needs a new `request_id`.\n\nPresent on every response, `false` for a newly opened batch. A response without the\nfield is from a gateway predating it, not a newly opened batch.\n";
+        };
         readonly source: {
             readonly $ref: "#/components/schemas/OwnedAsset";
         };
@@ -3013,12 +3622,24 @@ declare const $QuoteRequestResponse: {
                 readonly $ref: "#/components/schemas/Quote";
             };
         };
+        readonly requested_count: {
+            readonly type: "integer";
+            readonly description: "How many agents the request was broadcast to, so silence is distinguishable from a\ndecline without a second call. Same meaning and same absence rule as on the status\nendpoint: absent means unknown, never zero.\n";
+            readonly example: 8;
+        };
+        readonly decline_summary: {
+            readonly type: "array";
+            readonly description: "Why the request drew few or no quotes, carried here so that a `ready` response with an\nempty `quotes` array explains itself rather than requiring a follow-up read.\n\nSame counting rules as the status endpoint: every declining agent counted exactly once\nunder its most recent reason, empty when nobody declined, absent when the detail could not\nbe read. Provisional while `status` is `collecting`, because agents are still responding.\n";
+            readonly items: {
+                readonly $ref: "#/components/schemas/DeclineSummaryEntry";
+            };
+        };
     };
 };
 declare const $QuoteRequestAccepted: {
     readonly type: "object";
-    readonly description: "Asynchronous (202) response to POST /v1/payments/quote-requests. Returns the batch handle\nplus the echoed corridor; quotes are retrieved via the status endpoint.\n";
-    readonly required: readonly ["quote_request_id", "status"];
+    readonly description: "Asynchronous (202) response to POST /v1/payments/quote-requests. Returns the batch handle\nplus the echoed corridor; quotes are retrieved via the status endpoint.\n\nThe corridor echoed here describes the batch you actually receive. On an idempotent\nreplay that is the ORIGINAL batch's corridor and window, which may differ from what you\njust sent in the ways a retry is allowed to differ (the deadlines, and address casing).\n";
+    readonly required: readonly ["quote_request_id", "status", "idempotent_replay"];
     readonly properties: {
         readonly quote_request_id: {
             readonly type: "string";
@@ -3027,9 +3648,13 @@ declare const $QuoteRequestAccepted: {
         readonly status: {
             readonly type: "string";
             readonly enum: readonly ["collecting"];
-            readonly description: "Always `collecting` — collection is in progress server-side.";
+            readonly description: "Always `collecting` — a constant on this response, not a report of the batch's state.\nOn an idempotent replay the batch's window may already have closed; read\nGET /v1/payments/quote-requests/{quoteRequestId} for its actual state.\n";
             readonly example: "collecting";
         };
+        readonly idempotent_replay: {
+            readonly type: "boolean";
+            readonly description: "Whether this response describes a batch that already existed, rather than one opened\nby this request. `true` means the `request_id` had been used before and you are being\nhanded the ORIGINAL batch — no second batch was opened and no second broadcast went\nout to settlement agents.\n\nThe idempotency contract is the same as on the synchronous (200) response: a\nre-submission may carry expired deadlines and is resolved onto the existing batch\nrather than rejected, the collection window is the batch's own and is not extended,\nand differing economics are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH rather than\ncollapsed onto the first batch.\n\nPresent on every response, `false` for a newly opened batch. A response without the\nfield is from a gateway predating it, not a newly opened batch.\n";
+        };
         readonly source: {
             readonly $ref: "#/components/schemas/OwnedAsset";
         };
@@ -3088,8 +3713,46 @@ declare const $QuoteRequestStatusResponse: {
                 readonly $ref: "#/components/schemas/AwardedPayment";
             };
         };
+        readonly requested_count: {
+            readonly type: "integer";
+            readonly description: "How many agents the request was broadcast to. The only auction count that is not\nderivable from the rest of this response:\n\n- quoted = `quotes` length\n- declined = sum of `decline_summary[].count`\n- participated = quoted + declined\n- silent = `requested_count` - participated\n\nSilence and a decline are different signals, which is why the denominator is surfaced\nrather than left implicit.\n\nABSENT when the number is unknown, which happens when the broadcast count was never\nrecorded or when the auction detail could not be read. Absence means unknown, never zero,\nso `silent` is derivable only when this field is present.\n";
+            readonly example: 8;
+        };
+        readonly decline_summary: {
+            readonly type: "array";
+            readonly description: "Why the request drew few or no quotes, so a caller can tell \"nobody can fund this right\nnow\" from \"my request was malformed\".\n\nEXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most\nrecent reason, so the counts sum to the number of agents that declined. An agent that\ndeclined more than once with different reasons is counted once, not once per reason.\n\nEmpty means nobody declined. ABSENT means the auction detail could not be read, so the\nbreakdown is unknown. While `status` is `collecting` it is provisional, because agents are\nstill responding.\n\nThe free-form decline detail is never relayed, because that detail carries an agent's\nbalances and would let a caller map inventory by polling cheap quote-requests across\ncorridors.\n";
+            readonly items: {
+                readonly $ref: "#/components/schemas/DeclineSummaryEntry";
+            };
+        };
     };
 };
+declare const $DeclineSummaryEntry: {
+    readonly type: "object";
+    readonly required: readonly ["reason", "count"];
+    readonly properties: {
+        readonly reason: {
+            readonly $ref: "#/components/schemas/DeclineReason";
+        };
+        readonly count: {
+            readonly type: "integer";
+            readonly description: "Agents whose most recent decline reason was this one. Counts agents, never rows, and an\nagent appears under one reason only.\n";
+            readonly example: 4;
+        };
+        readonly retry_classification: {
+            readonly type: "string";
+            readonly description: "What would have to change for a settler giving this reason to bid, drawn from the same\nclosed set as the `retry_classification` on an error response so a caller reads one\nvocabulary.\n\nIt describes the decline only. The authoritative instruction for the payment is the\n`retry_classification` on its own error response: a payment can fail for a reason no\nsettler named, and it can succeed while some settlers declined.\n\nOptional, and a pattern-constrained string for the same reason `DeclineReason` is.\n";
+            readonly pattern: "^[A-Z][A-Z0-9_]*$";
+            readonly example: "RETRY_AFTER_DELAY";
+        };
+    };
+};
+declare const $DeclineReason: {
+    readonly type: "string";
+    readonly description: "A settler's reason for not bidding, projected from its internal reason code through\nthe shared decline catalog (`apis/decline/v1/catalog.json`), which is the single\nsource of truth for the reason set. Several internal codes may map to one public\nreason.\n\nDeliberately a pattern-constrained string rather than a closed enum. The set grows\nwhenever a settler gains a cause worth naming, and a consumer whose generated client\ncloses the set rejects the whole response on a value it has not seen. Treat an\nunrecognised value as `OTHER`.\n\n`OTHER` covers a reason whose detail is settler-authored free text, and any reason\nthis gateway does not recognise. Both are counted so the summary stays exhaustive,\nwithout relaying text we neither author nor validate.\n";
+    readonly pattern: "^[A-Z][A-Z0-9_]*$";
+    readonly example: "INSUFFICIENT_LIQUIDITY";
+};
 declare const $AwardRequest: {
     readonly type: "object";
     readonly description: "Request body for POST /v1/payments/awards. Carries the two originator-signed artifacts:\n`sender_auth` (Permit2 deposit authorization) and a fully-formed `bid_award` declaration.\nThe awarded quote is derived server-side from bid_award.fulfillment_quote_json — no\nexplicit quote_id on the wire.\n";
@@ -3152,7 +3815,7 @@ declare const $AwardResponse: {
     readonly properties: {
         readonly payment_id: {
             readonly type: "string";
-            readonly example: "py_9876fedc-ba98-7654-3210-fedcba987654";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
         readonly status: {
             readonly type: "string";
@@ -3172,7 +3835,7 @@ declare const $AwardAccepted: {
     readonly properties: {
         readonly payment_id: {
             readonly type: "string";
-            readonly example: "py_9876fedc-ba98-7654-3210-fedcba987654";
+            readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
         };
         readonly status: {
             readonly type: "string";
@@ -3182,6 +3845,125 @@ declare const $AwardAccepted: {
         };
     };
 };
+declare const $ChainDefaults: {
+    readonly type: "object";
+    readonly description: "The addresses for one chain. Optional fields appear only where they apply to that\nchain; an absent optional field is not an error.\n";
+    readonly required: readonly ["chain_id", "quote_selector", "escrow_contract", "fulfillment_proxy", "fulfillment_verifier"];
+    readonly properties: {
+        readonly chain_id: {
+            readonly type: "string";
+            readonly description: "CAIP-2 identifier of the chain these defaults describe, normalised to lower case.";
+            readonly example: "eip155:84532";
+        };
+        readonly quote_selector: {
+            readonly type: "string";
+            readonly description: "The account named as the reserver in the deposit authorization. Sign against this exact value; a deposit reserved by anyone else is rejected.";
+            readonly example: "0xd0f080E23F95571D26eEb1FAD24a5F3d66835195";
+        };
+        readonly escrow_contract: {
+            readonly type: "string";
+            readonly description: "The escrow the deposit is made into, and the spender of the token approval. Empty when the chain is not fully configured.";
+            readonly example: "0xa61a0C025943Aa79B73D8D07E3aDbEe1873738b4";
+        };
+        readonly fulfillment_proxy: {
+            readonly type: "string";
+            readonly description: "The contract that pays the receiver. Read this from the DESTINATION chain's defaults, not the source chain's. Empty when the chain is not fully configured.";
+            readonly example: "0x09A5a0d6955E5394A661Cd9E7007076fa63B4158";
+        };
+        readonly fulfillment_verifier: {
+            readonly type: "object";
+            readonly description: "The service that attests settlement, and the account it signs with.";
+            readonly required: readonly ["account", "endpoint"];
+            readonly properties: {
+                readonly account: {
+                    readonly type: "string";
+                    readonly description: "The account named as the releaser in the deposit authorization. Sign against this exact value.";
+                    readonly example: "0x27050EE47befC43F4dF7807a7AA8073039e5fa89";
+                };
+                readonly endpoint: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "Base URL of the fulfillment verifier serving this chain.";
+                    readonly example: "https://veri-fill.example.com";
+                };
+            };
+        };
+        readonly permit2_contract: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "The Permit2 this chain's escrow verifies against, sent only when it is not the canonical deployment. When absent, use the canonical Permit2 address for the chain. EVM and Tron only.";
+            readonly example: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+        };
+        readonly deposit_witness_version: {
+            readonly type: "integer";
+            readonly minimum: 3;
+            readonly description: "Which deposit witness this chain's escrow expects. `4` and above select the four-member witness, `3` the two-member one; absent means four. EVM and Tron only - on Solana this is carried by `svm_signature_domain_version`.";
+            readonly example: 4;
+        };
+        readonly tokens: {
+            readonly type: "array";
+            readonly description: "Tokens this chain's escrow accepts for deposit. Absent when the gateway has no listing for the chain, which does not mean no token is accepted.";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["symbol", "address", "decimals"];
+                readonly properties: {
+                    readonly symbol: {
+                        readonly type: "string";
+                        readonly example: "USDC";
+                    };
+                    readonly address: {
+                        readonly type: "string";
+                        readonly description: "Token contract address, in the chain's native address format.";
+                        readonly example: "0x036cbd53842c5426634e7929541ec2318f3dcf7e";
+                    };
+                    readonly decimals: {
+                        readonly type: "integer";
+                        readonly description: "Decimal places, for converting a human amount to base units.";
+                        readonly example: 6;
+                    };
+                };
+            };
+        };
+        readonly svm_signature_cluster_id: {
+            readonly type: "string";
+            readonly description: "Solana only. The cluster the escrow's signing domain is bound to, needed to build the deposit hash. Absent for EVM and Tron.";
+            readonly example: "devnet";
+        };
+        readonly svm_signature_domain_version: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Solana only. Version of the escrow's signing domain. Absent for EVM and Tron.";
+            readonly example: 2;
+        };
+    };
+};
+declare const $GetDefaultsResult: {
+    readonly description: "Either one chain's defaults or every chain keyed by CAIP-2 chain id, depending on whether `chain_id` was supplied. A top-level `chain_id` identifies the first.";
+    readonly oneOf: readonly [{
+        readonly $ref: "#/components/schemas/ChainDefaults";
+    }, {
+        readonly $ref: "#/components/schemas/ChainDefaultsByChain";
+    }];
+};
+declare const $ChainDefaultsByChain: {
+    readonly type: "object";
+    readonly description: "Defaults for every chain the gateway serves, keyed by CAIP-2 chain id. Each key repeats the `chain_id` of the value it maps to.";
+    readonly additionalProperties: {
+        readonly $ref: "#/components/schemas/ChainDefaults";
+    };
+    readonly example: {
+        readonly 'eip155:84532': {
+            readonly chain_id: "eip155:84532";
+            readonly quote_selector: "0xd0f080E23F95571D26eEb1FAD24a5F3d66835195";
+            readonly escrow_contract: "0xa61a0C025943Aa79B73D8D07E3aDbEe1873738b4";
+            readonly fulfillment_proxy: "0x09A5a0d6955E5394A661Cd9E7007076fa63B4158";
+            readonly fulfillment_verifier: {
+                readonly account: "0x27050EE47befC43F4dF7807a7AA8073039e5fa89";
+                readonly endpoint: "https://veri-fill.example.com";
+            };
+        };
+    };
+};
 
 type ApiResult<TData = any> = {
     readonly body: TData;
@@ -3200,6 +3982,20 @@ declare class ApiError extends Error {
     constructor(request: ApiRequestOptions, response: ApiResult, message: string);
 }
 
+/**
+ * The gateway accepted the request but did not answer inside the client's budget.
+ *
+ * Not an {@link ApiError}: there is no response, status or error body, so
+ * `isApiError` and `getErrorResponse` stay false for it. It carries no verdict on
+ * the request either, since a timed-out submit may still have been accepted.
+ */
+declare class GatewayTimeoutError extends Error {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl: string, timeoutMs: number);
+}
+/** Type guard for {@link GatewayTimeoutError}, the unresponsive-gateway case. */
+declare function isGatewayTimeoutError(err: unknown): err is GatewayTimeoutError;
 /**
  * Type guard for the SDK's transport-level error.
  *
@@ -3213,10 +4009,12 @@ declare function isApiError(err: unknown): err is ApiError;
  * 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.
+ * (`{ code, message, request_id?, payment_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`, quote `request_id` to support, and read
+ * `payment_id` to reconcile the payment a failed settlement was attempted under.
+ * It only ever exposes this outward-facing shape — never any internal error
+ * taxonomy.
  *
  * @example
  * try {
@@ -3232,6 +4030,275 @@ declare function isApiError(err: unknown): err is ApiError;
  */
 declare function getErrorResponse(err: unknown): ErrorResponse | undefined;
 
+/**
+ * Polling a submitted payment until it reaches a state it cannot leave.
+ *
+ * The gateway holds a submission for its own synchronous window before answering, so a payment that
+ * is still pending by the time the caller sees it settled more slowly than that window. A submission usually
+ * comes back pending, so following one is the ordinary path rather than an edge case.
+ *
+ * The wait budget is a client-side convenience, not a deadline with any meaning to the network.
+ * Nothing is affected by giving up: the payment continues, and re-submitting the same request id or
+ * asking for the payment's status picks up wherever it got to. In particular a settlement that
+ * stalls will never become terminal on its own, so no budget can promise a terminal answer — giving
+ * up while still pending is a normal ending, not a failure.
+ */
+/**
+ * True for the states a payment can never leave.
+ *
+ * An unrecognized or absent status is deliberately NOT terminal: a status this client does not
+ * know is treated as still in flight, so a gateway that adds one does not make a caller report a
+ * payment as finished on the strength of a value it cannot interpret.
+ */
+declare function isTerminalStatus(status: string | undefined): boolean;
+/**
+ * Default budget for {@link waitForTerminalStatus}, in milliseconds.
+ *
+ * The gateway has already held the submission for its own window by the time a caller sees a
+ * pending payment, so anything still pending is settling slowly. A minute past that covers the
+ * common case without holding a request handler open indefinitely.
+ */
+declare const DEFAULT_WAIT_BUDGET_MS: number;
+/** Gap between status checks. Short enough to feel responsive, long enough not to hammer. */
+declare const DEFAULT_POLL_INTERVAL_MS = 2000;
+/**
+ * All this module needs of a status response: something that reports a status. Deciding when to
+ * stop is the only thing it does, so it constrains the shape rather than defining it, and callers
+ * get their own richer type back unchanged.
+ */
+interface StatusSnapshot {
+    status?: string;
+}
+/** Outcome of a wait. */
+interface WaitOutcome<T extends StatusSnapshot> {
+    /** The last status successfully read, or undefined if no check ever succeeded. */
+    snapshot?: T;
+    /**
+     * Whether the wait ended without the payment reaching a terminal state — because the budget ran
+     * out, or because {@link WaitParams.signal} was aborted. False only when `snapshot` holds a
+     * terminal status, so it is safe to branch on: a payment is finished when this is false.
+     */
+    timedOut: boolean;
+    /** Whether {@link WaitParams.signal} ended the wait. Implies `timedOut`. */
+    aborted: boolean;
+    /** How many status checks failed outright (network or gateway errors). */
+    errorCount: number;
+}
+/** Everything the wait needs, with time and I/O injected so it can be tested without a clock. */
+interface WaitParams<T extends StatusSnapshot> {
+    /** Read the payment's current status. */
+    fetchStatus: () => Promise<T>;
+    /**
+     * How long to keep checking, in **milliseconds**; defaults to {@link DEFAULT_WAIT_BUDGET_MS}.
+     * A budget of zero or less checks nothing.
+     */
+    budgetMs?: number;
+    /** Gap between checks; defaults to {@link DEFAULT_POLL_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Monotonic-enough clock, in milliseconds; defaults to `Date.now`. */
+    now?: () => number;
+    /**
+     * Test seam for the delay. Replacing it opts out of abort-aware sleeping, so a wait then ends
+     * at the next check rather than immediately.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Called for each failed check, so a caller can report it without this module owning output. */
+    onError?: (error: unknown) => void;
+    /**
+     * Ends the wait early, for a caller that must stop on shutdown or when its request is cancelled.
+     * The outcome reports `aborted`, and carries the last status read.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Poll a payment's status until it is terminal, the budget runs out, or `signal` is aborted.
+ *
+ * A failed check does not end the wait: a blip while a payment is mid-settlement is exactly when
+ * giving up is least useful, so failures are counted, reported through `onError`, and polling
+ * continues until the budget is spent.
+ *
+ * @param params - the status reader, the budget, and injectable time
+ * @returns the last status read, whether the wait ended without a terminal status, whether
+ *          `signal` ended it, and how many checks failed
+ */
+declare function waitForTerminalStatus<T extends StatusSnapshot>(params: WaitParams<T>): Promise<WaitOutcome<T>>;
+
+/**
+ * Result of an {@link ensureSourceApproval} call.
+ */
+interface EnsureApprovalResult {
+    /** The existing allowance already covered the requirement; no transaction was sent. */
+    alreadySufficient: boolean;
+    /** The approval transaction hash, when one was sent. */
+    txHash?: string;
+    /**
+     * Set only when the token refused to overwrite a non-zero allowance and it had to be reset to
+     * zero first: the hash of that reset. Its absence means one transaction was sent, not two.
+     */
+    resetTxHash?: string;
+}
+/** What TronWeb reports about a broadcast transaction. Empty until it is confirmed. */
+interface TronTransactionInfo {
+    receipt?: {
+        result?: string;
+    };
+}
+/**
+ * The slice of a TronWeb instance this package needs.
+ *
+ * Declared structurally rather than imported from `tronweb` on purpose: the package then
+ * type-checks and builds with tronweb absent, and consumers that never pay from Tron do not
+ * carry an 11 MB dependency they cannot reach. The caller constructs the instance and passes
+ * it in, exactly as the EVM path takes a caller-constructed ethers signer.
+ */
+interface TronWebLike {
+    /**
+     * The ABI-and-address form, which builds the handle locally. The `contract().at(address)`
+     * form fetches the ABI from the node instead: a round trip per use, and an interface that
+     * depends on what the chain happens to report for that address.
+     *
+     * Returns `unknown` on purpose. TronWeb types this as a contract whose methods are produced
+     * dynamically from the ABI, so pinning it to {@link TronTokenContract} here would stop a real
+     * TronWeb instance assigning to this interface at all and force every caller to write a cast.
+     * The cast belongs in one place — next to the ABI we passed, which is what makes it true.
+     */
+    contract(abi: unknown, address: string): unknown;
+    trx: {
+        getTransactionInfo(txId: string): Promise<TronTransactionInfo>;
+    };
+    /**
+     * The account this instance signs as. Read to check it against `owner` before broadcasting,
+     * since an approval only ever applies to the account that sends it.
+     *
+     * Optional, and `false` is TronWeb's own "not set": both mean the instance cannot say which
+     * account it would use, and neither is treated as a mismatch.
+     */
+    defaultAddress?: {
+        base58?: string | false;
+    };
+}
+/** How long to wait for a broadcast approval to confirm before giving up, on either chain. */
+interface ConfirmationOptions {
+    /**
+     * Default 60_000. On timeout the approval is reported as unconfirmed rather than failed: it
+     * was broadcast and may still confirm, so the caller is told to check it before sending
+     * another one.
+     */
+    timeoutMs?: number;
+    /** Tron only: how often to poll for the receipt. Default 1_500, under Tron's ~3s block time. */
+    pollIntervalMs?: number;
+    /** Tron only: default 100_000_000 SUN. Tron charges the caller for contract execution. */
+    feeLimit?: number;
+}
+/**
+ * Inputs to {@link ensureSourceApproval} and {@link needsSourceApproval}.
+ *
+ * `signer` and `tronWeb` are both optional here because which one is required is decided by
+ * `network`, a runtime string that no type can constrain. Supplying the wrong one for the
+ * chain fails with a message naming the one that was needed.
+ */
+interface ApprovalParams {
+    /** CAIP-2 source chain id, e.g. `eip155:8453` or `tron:mainnet`. */
+    network: string;
+    /** Source token address. */
+    token: string;
+    /** The payer's account. */
+    owner: string;
+    /**
+     * The contract to approve. Defaults to the canonical Permit2 for the chain: the EVM
+     * deployment on `eip155:*`, and the pinned per-network address on `tron:*`.
+     */
+    spender?: string;
+    /**
+     * The minimum allowance this charge needs. Answers "is what I already have enough?".
+     * When omitted, only an unlimited approval counts as sufficient, so a smaller leftover
+     * allowance cannot be mistaken for enough and revert a larger later charge on-chain.
+     */
+    requiredAllowance?: bigint;
+    /**
+     * How much to approve when an approval IS sent. Defaults to unlimited, so later charges on
+     * the same token need no further transaction.
+     *
+     * On its own, a bounded amount is treated as its own requirement: an allowance still holding
+     * the full bound is left alone rather than re-approved. That is the right answer for a one-off
+     * approval, where nothing else in the call says what a later charge would need.
+     *
+     * Across repeated payments, PAIR IT WITH `requiredAllowance`. Permit2 decrements the allowance
+     * on every payment, so a bound measured against itself stops being sufficient the moment the
+     * first charge lands, and every later call sends another approval. `requiredAllowance` states
+     * what the NEXT charge needs, which is the question a partly spent bound can still answer yes
+     * to.
+     *
+     * Trade-off: a bounded approval limits what the escrow can ever move, but it is consumed as it
+     * is spent and eventually has to be granted again, whichever way it is used.
+     */
+    approvalAmount?: bigint;
+    /** An ethers signer connected to the source chain. Required for `eip155:*`. */
+    signer?: Signer;
+    /** A TronWeb instance configured for the source chain. Required for `tron:*`. */
+    tronWeb?: TronWebLike;
+    /** Broadcast and confirmation tuning. Applies to both chains. */
+    confirmation?: ConfirmationOptions;
+    /**
+     * Called with each transaction hash the moment it is broadcast, before the wait for it to
+     * confirm. Without this a caller has nothing to show for a transaction that is already
+     * spending their gas — and nothing to look up if the wait times out.
+     *
+     * `purpose` distinguishes the approval itself from the zero-reset some tokens demand first,
+     * so two hashes in one call read as one deliberate sequence rather than a double spend.
+     */
+    onSubmitted?: (txHash: string, purpose: "approval" | "reset") => void;
+}
+
+/** Whether an error came from a broadcast transaction that was never seen to confirm. */
+declare function isUnconfirmed(error: unknown): boolean;
+
+/**
+ * Payer-side Permit2 approval for the source token an escrow deposit moves.
+ *
+ * On EVM and Tron the escrow moves the source token through Permit2, so the payer must have
+ * approved Permit2 on that token BEFORE paying. Without it the payment is built, signed and
+ * accepted by the gateway, and then the deposit reverts on-chain at settlement — a late and
+ * misleading failure. Solana authorizes the transfer inside the signed deposit itself, so
+ * there is nothing to approve there.
+ *
+ * Worth arranging before the payment is signed: a deposit that reverts is a terminal
+ * settlement failure, and a terminal failure is bound to the request identifier that produced
+ * it, so re-attempting then needs a NEW identifier. Getting the allowance right up front keeps
+ * the identifier usable.
+ *
+ * This package reads chain state and broadcasts a transaction, which is why it is separate
+ * from the sender-auth SDK next door: that one is pure, offline and byte-parity-tested against
+ * Go. The caller supplies the connected signer, so this package never chooses an RPC endpoint.
+ */
+
+/**
+ * Whether a payment on these terms would need an approval transaction first.
+ *
+ * Read-only: it spends no gas and sends nothing, so it is safe to call on every payment as a
+ * preflight. Returns false on Solana, which needs no approval at all.
+ *
+ * @remarks
+ * Unlike a try-and-see, this reports the answer instead of acting on it — use it to tell a
+ * payer what is about to happen, or to check whether a wallet is ready before asking for a
+ * signature.
+ */
+declare function needsSourceApproval(params: ApprovalParams): Promise<boolean>;
+/**
+ * Ensure the payer has approved Permit2 to move the source token, so the escrow deposit does
+ * not revert at settlement. Reads the current allowance and sends an approval only if it falls
+ * short; the approval it sends is unlimited unless `approvalAmount` bounds it.
+ *
+ * Applies to EVM (`params.signer`) and Tron (`params.tronWeb`). On Solana it reports
+ * `alreadySufficient` without touching the chain.
+ *
+ * @remarks
+ * Not concurrency-safe: two overlapping calls for the same `(owner, token, spender)` may both
+ * read a short allowance and both send an approval. They target the same value, so this only
+ * wastes gas; serialize calls per token if that matters.
+ */
+declare function ensureSourceApproval(params: ApprovalParams): Promise<EnsureApprovalResult>;
+
 /**
  * EVM Permit2 PermitWitnessTransferFrom deposit prehash + EIP-712 digest.
  *
@@ -3483,11 +4550,16 @@ declare const MAX_VALID_SLOT: number;
  *
  * encodeU64LE, generateSolanaNonce (generateNonce), and MAX_VALID_SLOT are
  * imported from the shared @atum-labs/solana-escrow-encoding package and
- * re-exported here to preserve the public API. The V1 hashSolanaDeposit,
- * base58ToBytes, payment-id generation, and prehash creation stay local: the
- * package has no non-domain-separated V1 hash, and the local base58/hex helpers
- * carry the exact error messages the client tests assert. The V3 deposit hash
- * already delegates to the package (hashSolanaDepositV3 → computeDepositHash).
+ * re-exported here to preserve the public API. base58ToBytes, payment-id
+ * generation, and prehash creation stay local, because the local base58/hex
+ * helpers carry the exact error messages the client tests assert.
+ *
+ * NO DEPOSIT HASH IS COMPUTED HERE ANY MORE. hashSolanaDeposit computed the
+ * pre-domain-separation layout above and now throws (see its doc comment), and
+ * hashSolanaDepositV3 was deleted as an un-exported third copy of the package's
+ * own call. Build a deposit through the shared sender_auth adapter, which selects
+ * the preimage from the escrow domain version; reach for computeDepositHash /
+ * computeDepositHashV2 from the package if you need the raw primitive.
  *
  * The canonical reference is the @atum-labs/solana-escrow-encoding package in
  * this repo (contracts/svm/escrow-encoding), the TypeScript sibling of the
@@ -3496,7 +4568,10 @@ declare const MAX_VALID_SLOT: number;
 
 /** Replay horizon in seconds — deposit deadline must be within this window of issuedAt. */
 declare const REPLAY_HORIZON_SECS = 128;
-/** Total number of replay-protection buckets. */
+/**
+ * Widest bucket ID the replay nonce layout carries. Generated nonces draw from the smaller
+ * bounded set the escrow-encoding package defines, which keeps the replay_bucket PDAs reusable.
+ */
 declare const TOTAL_BUCKETS = 131072;
 /** Exact byte size of a serialized deposit message (7 + 32*5 + 8*3). */
 declare const DEPOSIT_MESSAGE_SIZE = 199;
@@ -3578,22 +4653,34 @@ interface SolanaDepositPrehash {
  */
 declare function createSolanaDepositPrehash(paymentId: string, params: SolanaDepositParams): SolanaDepositPrehash;
 /**
- * Computes the keccak256 deposit hash from a prehash structure.
+ * REMOVED — this function computed the PRE-DOMAIN-SEPARATION deposit hash, which no deployed
+ * escrow program accepts. It now throws rather than returning one.
  *
- * Formula: keccak256("deposit" || payment_id[32] || depositor[32] || mint[32] ||
- *                    amount[8,LE] || reserver[32] || releaser[32] ||
- *                    nonce[8,LE] || issued_at[8,LE] || deadline[8,LE])
+ * The layout it used, kept here as a record of the historical scheme:
  *
- * Total input: 199 bytes (7 + 32*5 + 8*3)
+ *   keccak256("deposit" || payment_id[32] || depositor[32] || mint[32] ||
+ *             amount[8,LE] || reserver[32] || releaser[32] ||
+ *             nonce[8,LE] || issued_at[8,LE] || deadline[8,LE])        = 199 bytes
  *
- * TODO: Replace with computeDepositHash from @atum-labs/solana-escrow-encoding once public.
- * The bindings version uses EscrowDepositParams with Pubkey objects instead of base58 strings,
- * so this function will need to convert from prehash strings to the bindings' types.
+ * Every current program prefixes the preimage with its domain —
+ * `"escrow" || signature_domain_version || cluster_id[32] || program_id[32]` — and from domain
+ * version 4 also binds `destination_hash`. So the 199-byte hash is not merely out of date, it is
+ * unverifiable everywhere: `escrow.rs`'s `require!(deposit_hash == message, InvalidData)` rejects
+ * it on every cluster.
  *
- * @param prehash The structured prehash from createSolanaDepositPrehash()
- * @returns 0x-prefixed hex string (32 bytes)
+ * WHY IT THROWS INSTEAD OF BEING DELETED OR LEFT ALONE. It was exported from this package's
+ * entry point, so removing the symbol outright is a hard break for any consumer that imports it,
+ * while leaving it was worse: it returned a well-formed 32-byte hash that fails on-chain with
+ * `InvalidData` and no indication why. Throwing turns an undiagnosable on-chain rejection into an
+ * error at the call site that names the replacement.
+ *
+ * Build deposit authorizations through the shared sender_auth adapter
+ * (`getChainAdapter(chainId).buildAuthMessage(...)`), which selects the correct preimage from the
+ * domain version it is given and is the same implementation the facilitator verifies against.
+ *
+ * @throws Always.
  */
-declare function hashSolanaDeposit(prehash: SolanaDepositPrehash): string;
+declare function hashSolanaDeposit(_prehash: SolanaDepositPrehash): never;
 /**
  * Generates a valid nonce for Solana replay protection (upper 32 bits: random
  * bucket, lower 8 bits: random slot 0..MAX_VALID_SLOT). Delegates to the shared
@@ -3621,6 +4708,11 @@ declare const PAYMENT_REQUEST_VERSION = "1.0";
  */
 declare function signPaymentRequest(request: PaymentRequest, signer: SenderSigner): Promise<PaymentRequest>;
 type HttpRequestConstructor = new (config: OpenAPIConfig) => BaseHttpRequest;
+/**
+ * Request-layer configuration plus this package's network timeouts. Omit the
+ * timeouts for the defaults; see {@link RequestTimeouts}.
+ */
+type PaymentGatewayClientConfig = Partial<OpenAPIConfig> & RequestTimeouts;
 declare const defaultGateway: string;
 /**
  * Default request-layer configuration, with `BASE` set to this package's default
@@ -3660,11 +4752,14 @@ declare const DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS = 10;
  * Extended PaymentGatewayClient with convenience methods
  */
 declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
-    private baseUrl;
-    constructor(config?: Partial<OpenAPIConfig>, HttpRequest?: HttpRequestConstructor);
+    constructor(config?: PaymentGatewayClientConfig, HttpRequest?: HttpRequestConstructor);
     /**
      * Fetches chain defaults from the payment gateway.
      *
+     * Goes through the generated typed client, so the request shares the payment calls'
+     * transport: one base URL, one timeout policy, and `/v1/defaults` is described by the
+     * OpenAPI contract rather than assembled by hand here.
+     *
      * @param chainId The CAIP-2 chain identifier (e.g., "eip155:42161")
      * @returns The chain defaults including escrow, quote selector, and fulfillment verifier
      */
@@ -3672,7 +4767,7 @@ 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`
+     * By default this resolves the corridor addresses from the gateway `/v1/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
@@ -3748,7 +4843,7 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
         solanaClockReader?: SolanaClusterUnixTimeReader;
         /**
          * Pre-resolved corridor addresses. Omit to fetch them from the gateway
-         * `/defaults`; supply to build offline. Each side is resolved independently —
+         * `/v1/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).
          */
@@ -3782,7 +4877,7 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
      * defaults and populates the SAME contract fields (`escrow_contract_address`,
      * `quote_selector`, `fulfillment_verifier`, `fulfillment_proxy`). These are not
      * optional in practice: the gateway requires `fulfillment_verifier` to build the
-     * QuoteRequested event it broadcasts to settlers, so the quote-request body
+     * request event it broadcasts to settlers, so the quote-request body
      * must carry the identical contract fields the payment flow does. The ONLY
      * field this drops relative to `preparePaymentRequest` is `sender_auth`, which
      * is supplied at award time (quote-time is unauthenticated — no signing, no
@@ -3798,8 +4893,12 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
         destinationAccount: string;
         destinationAsset: string;
         maxSourceAmount?: string;
-        requestId?: string;
-        requestIdPrefix?: string;
+        /**
+         * The request id. Reuse the SAME value to retry: the gateway returns the original batch
+         * (same `quote_request_id`) instead of opening a second one, and answers `409`
+         * IDEMPOTENCY_TERMS_MISMATCH if you reuse it for a different corridor.
+         */
+        requestId: string;
         settlerRequirements?: {
             whitelist?: string[];
             blacklist?: string[];
@@ -3809,4 +4908,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, 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 };
+export { $AuthorizationResult, $AwardAccepted, $AwardRequest, $AwardResponse, $AwardedPayment, $AwardedQuote, $BidAward, $ChainDefaults, $ChainDefaultsByChain, $CreateQuoteRequest, $DataIntegrityProof, $DeclineReason, $DeclineSummaryEntry, $ErrorResponse, $FulfillmentConfirmation, $GetDefaultsResult, $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 ApprovalParams, 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 ChainDefaultsByChain, ChainDefaultsService, type ChainDefaults$1 as ChainDefaultsWire, type ConfirmationOptions, type CreateQuoteRequest, type CreateQuoteRequestData, type CreateQuoteRequestResponse, DEFAULT_FULFILLMENT_DEADLINE_SECONDS, DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_QUOTE_DEADLINE_SECONDS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SYNC_WAIT_TIMEOUT_MS, DEFAULT_WAIT_BUDGET_MS, DEPOSIT_MESSAGE_SIZE, type DataIntegrityProof, type DeclineReason, type DeclineSummaryEntry, type EnsureApprovalResult, type ErrorResponse, type FulfillmentConfirmation, GatewayTimeoutError, type GetDefaultsData, type GetDefaultsResponse, type GetDefaultsResult, type GetPaymentStatusData, type GetPaymentStatusResponse, type GetPaymentStatusResponse2, type GetPaymentTimelineData, type GetPaymentTimelineResponse, type GetQuoteRequestStatusData, type GetQuoteRequestStatusResponse, type HealthCheckResponse, HealthService, Interceptors, InvalidAccountError, type Reason as InvalidAccountReason, MAX_VALID_SLOT, type OnCancel, OpenAPI, type OpenAPIConfig, type OwnedAsset, PAYMENT_REQUEST_VERSION, PERMIT2_CONTRACT_ADDRESS, type ParsedAssetIdentifier, type PaymentBlockchainContext, type PaymentError, PaymentGatewayClient, type PaymentGatewayClientConfig, 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 RequestTimeouts, 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 StatusSnapshot, type SubmitPaymentData, type SubmitPaymentResponse, TOTAL_BUCKETS, type TimelineError, type TimelineStep, type TronWebLike, type TurnkeyConfig, TurnkeySenderSigner, type TvmPermitWitnessTransferFromParams, type VerifiableCredential, type VerifiableCredentialAuth, type WaitOutcome, type WaitParams, assetChainId, base58ToBytes, base58ToHex, bytesToHex, createPermitWitnessTransferFromPrehash, createSenderSigner, createSolanaDepositPrehash, createTvmPermitWitnessTransferFromPrehash, defaultGateway, type domain, encodeU64LE, ensureSourceApproval, type error_code, generateSolanaNonce, generateSolanaPaymentId, getErrorResponse, hashPermitWitnessTransferFrom, hashRequestId, hashSolanaDeposit, hashTvmPermitWitnessTransferFrom, hexToBytes, isApiError, isGatewayTimeoutError, isTerminalStatus, isUnconfirmed, maskChainId, needsSourceApproval, normalizeAddress, parseAssetIdentifier, resolveTurnkeyAddresses, signPaymentRequest, type status, type status2, type status3, type status4, type status5, type status6, type status7, type status8, type status9, waitForTerminalStatus };