uvd-x402-sdk 2.78.0 → 2.80.0

package/dist/backend/index.d.ts

@@ -45,8 +45,34 @@ import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../inde
  * sequence that once minted five duplicate agents — reconcile with
  * `GET /identity/{network}/owner/{recipient}` or `getRegisterStatus` instead.
  *
+ * # The two `502`s of `/settle`, which mean opposite things
+ *
+ * | body `error`               | `Retry-After` | did the money move? | retry?    |
+ * |----------------------------|---------------|---------------------|-----------|
+ * | `upstream_rpc_unavailable` | `30`          | no, never broadcast | **yes**   |
+ * | `settlement_unconfirmed`   | **absent**    | **maybe — mined?**  | **NEVER** |
+ *
+ * `settlement_unconfirmed` is answered after the transaction was broadcast and
+ * no receipt ever arrived, so it MAY be mined. Retrying re-signs a new
+ * authorization with a fresh nonce, which the chain accepts as a second,
+ * perfectly valid payment for the same purchase — the buyer pays twice, in
+ * exactly the case the facilitator emits it to prevent. The `transaction` hash
+ * and `paymentId` travel in the body so the caller can LOOK AT THE CHAIN; they
+ * are not an invitation to send it again.
+ *
+ * The status cannot tell the two apart, which is why this file used to get it
+ * wrong: every `502` was retryable, and until `settlement_unconfirmed` existed
+ * that was correct. **Branch on the body.**
+ *
+ * The general form of that rule — **a 5xx whose body carries a transaction hash
+ * was broadcast, whatever the error is called** — is adopted from the Python
+ * SDK, which has carried it as its anti-double-settle guard
+ * (`uvd_x402_sdk/client.py`, `_is_retryable_settle_error`) while this one had
+ * only the status to go on.
+ *
  * Source of the shape: x402-rs `src/handlers.rs` `writer_lease_unavailable()`
- * and `require_writer_lease()`.
+ * and `require_writer_lease()`; `SettlementUnconfirmedResponse` in
+ * `src/types.rs`, built in the `IntoResponse` of `FacilitatorLocalError`.
  */
 /**
  * A `reason` the facilitator attaches to a writer-lease 503.
@@ -72,6 +98,13 @@ declare const REPLAYABLE_LEASE_REASONS: readonly WriterLeaseReason[];
  * automatically. Resolve it by reading state, not by re-POSTing.
  */
 declare const AMBIGUOUS_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The facilitator's `error` code for a settle it broadcast and could not confirm.
+ *
+ * The transaction may be mined. This is the one upstream failure that must
+ * never be retried; reconcile with `transaction` / `paymentId` instead.
+ */
+declare const SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
 /**
  * Ceiling, in seconds, on how long an automatic retry will wait.
  *
@@ -98,6 +131,24 @@ interface FacilitatorErrorInfo {
     status: number;
     /** The facilitator's own `reason`, when the body carried one. */
     reason?: string;
+    /**
+     * The facilitator's machine-readable `error` code, verbatim.
+     *
+     * Some codes carry a `(ref: <uuid>)` suffix, so compare with care —
+     * {@link SETTLEMENT_UNCONFIRMED} is emitted bare. Branch on this rather than
+     * on the status: `/settle` has two `502`s that mean opposite things.
+     */
+    errorCode?: string;
+    /**
+     * The hash of a transaction that WAS broadcast, in that chain's own encoding.
+     *
+     * Present on {@link SETTLEMENT_UNCONFIRMED}. Not always `0x`-prefixed:
+     * Algorand prints base32 and Solana base58, and reformatting it makes it
+     * unpasteable in an explorer — which is the entire remedy on offer.
+     */
+    transaction?: string;
+    /** `keccak256(caip2 ‖ txHash)`, the same id a successful settle would print. */
+    paymentId?: string;
     /**
      * Seconds to wait before retrying, already clamped to
      * {@link MAX_RETRY_AFTER_SECONDS}. Absent when the answer is not retryable.
@@ -126,6 +177,15 @@ interface FacilitatorFailureFields {
     status?: number;
     /** The facilitator's `reason` for the refusal (see {@link WriterLeaseReason}). */
     reason?: string;
+    /** The facilitator's machine-readable `error` code (see {@link FacilitatorErrorInfo.errorCode}). */
+    errorCode?: string;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed. Look it up on
+     * chain; do NOT send the payment again. See {@link SETTLEMENT_UNCONFIRMED}.
+     */
+    transaction?: string;
+    /** The payment id for that transaction, identical to the one a settle prints. */
+    paymentId?: string;
     /** True when the same request may be sent again without re-signing anything. */
     retryable?: boolean;
     /** Seconds to wait before retrying, clamped to {@link MAX_RETRY_AFTER_SECONDS}. */
@@ -149,6 +209,41 @@ declare function parseRetryAfterSeconds(response: {
         get?: (name: string) => string | null;
     };
 }): number | undefined;
+/** Everything this SDK reads out of a facilitator error body. */
+interface ParsedFacilitatorErrorBody {
+    /** The `error` code, verbatim. */
+    errorCode?: string;
+    /** The writer-lease `reason`. */
+    reason?: string;
+    /** A broadcast transaction hash, in its own chain's encoding. */
+    transaction?: string;
+    /** The payment id for that hash. */
+    paymentId?: string;
+    /**
+     * The facilitator's OWN retry verdict, when it stated one.
+     *
+     * `undefined` on every body that does not carry the field — which is most of
+     * them, so absence means "the facilitator did not say", never "no".
+     */
+    retryable?: boolean;
+}
+/**
+ * Read a JSON error body, tolerating anything that is not one.
+ *
+ * Exported so {@link FacilitatorErrorInfo} and `Erc8004LookupError` read the
+ * SAME fields the same way. Two subtly different parses of the same body is how
+ * one code path stops honouring a `retryable: false` the other one honours.
+ */
+declare function parseFacilitatorErrorBody(body: string): ParsedFacilitatorErrorBody;
+/**
+ * This refusal reports a transaction that may already be mined.
+ *
+ * The caller's move is to look up `transaction` / `paymentId` on chain. Sending
+ * the payment again is the double-charge.
+ */
+declare function isSettlementUnconfirmed(failure: {
+    errorCode?: string;
+}): boolean;
 /**
  * Turn a non-2xx facilitator response into {@link FacilitatorErrorInfo}.
  *
@@ -234,18 +329,30 @@ interface PaymentRequirements {
     extra?: unknown;
 }
 /**
- * Verify request body for the facilitator /verify endpoint
+ * Verify request body for the facilitator /verify endpoint -- the **v1**
+ * envelope. {@link VerifyRequestV2} is the other one.
  */
 interface VerifyRequest {
-    x402Version: X402Version;
+    /**
+     * Always `1`: this marker names the ENVELOPE, and this envelope is v1.
+     *
+     * Narrowed from `X402Version` on 2026-09-04. A `VerifyRequest` carrying `2`
+     * was always an uninhabitable value -- a body declaring v2 while shaped as
+     * v1 -- and typing it as `1 | 2` is what let the payer's marker be copied in
+     * here. The payer's version lives in `paymentPayload.x402Version`, which is
+     * still the full union.
+     */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
 /**
- * Settle request body for the facilitator /settle endpoint
+ * Settle request body for the facilitator /settle endpoint -- the **v1**
+ * envelope. {@link SettleRequestV2} is the other one.
  */
 interface SettleRequest {
-    x402Version: X402Version;
+    /** Always `1` -- see {@link VerifyRequest.x402Version}. */
+    x402Version: 1;
     paymentPayload: X402Header;
     paymentRequirements: PaymentRequirements;
 }
@@ -551,6 +658,14 @@ declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceIn
  * `extra` is carried through when present -- it is where the EIP-712 domain
  * `name`/`version` live for tokens the facilitator does not know by address, so
  * dropping it breaks EURC and the bridged USDCs.
+ *
+ * @throws If `requirements.network` has NO CAIP-2 form. `chainToCAIP2` answers
+ * with the name unchanged when it does not know a chain, and XRPL maps to
+ * itself on purpose -- its v1 string IS its network id. Passing that through
+ * would put a plain name inside a v2 body, which is a measured 400 (the same
+ * `no variant matched` that names no field). Only reachable by PINNING version
+ * 2 on such a network; `auto` leaves them on v1, where they work. Failing here
+ * names the network and the fix, which a 400 from the facilitator does not.
  */
 declare function toPaymentRequirementsV2(requirements: PaymentRequirements): PaymentRequirementsV2;
 /**
@@ -561,24 +676,48 @@ declare function toPaymentRequirementsV2(requirements: PaymentRequirements): Pay
  *
  * **Auto keys off CAIP-2, NOT off `paymentHeader.x402Version`,** and that is a
  * measured decision rather than a stylistic one. The facilitator's envelope enum
- * is untagged: it matches on SHAPE and ignores the version marker. Measured
- * against production on 2026-09-03:
+ * is untagged: it matches on SHAPE and ignores the version marker.
+ *
+ * Re-measured against `https://facilitator.ultravioletadao.xyz/verify` on
+ * **2026-09-04** with a fabricated signature. The signature never verifies, so
+ * every row is an HTTP 400 and the STATUS discriminates nothing -- what does is
+ * the error code. `invalid_request_body` means the facilitator could not
+ * deserialize the body; `contract_call_failed` means it read the body, resolved
+ * the chain and got as far as the on-chain call, i.e. the envelope was fine.
  *
  * | payload network | requirements network | v1 envelope today |
  * |-----------------|----------------------|-------------------|
- * | `base`          | `base`               | **200**           |
- * | `base` (header says `x402Version: 2`) | `base` | **200**  |
- * | `eip155:8453`   | `base`               | 400               |
- * | `base`          | `eip155:8453`        | 400               |
- * | `eip155:8453`   | `eip155:8453`        | 400 (`unknown variant \`eip155:8453\``) |
- *
- * So a header that merely *declares* version 2 while carrying plain names is
- * being served correctly today. Upgrading it on the strength of the marker would
- * change a call that works -- the one thing this must not do. Every CAIP-2
- * combination, by contrast, is already a hard 400, so switching those to v2
- * cannot regress anyone: it can only turn a failure into a payment.
- */
-declare function resolveEnvelopeVersion(paymentHeader: X402Header, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
+ * | `base`          | `base`               | understood        |
+ * | `base` (header says `x402Version: 2`) | `base` | understood |
+ * | `eip155:8453`   | `base`               | understood        |
+ * | `base`          | `eip155:8453`        | understood        |
+ * | `eip155:8453`   | `eip155:8453`        | understood        |
+ *
+ * **The last three rows used to be a hard 400** (`unknown variant
+ * \`eip155:8453\``) when this function was written on 2026-09-03. The
+ * facilitator has since taught the v1 envelope to read CAIP-2, so the original
+ * argument for this rule -- "every CAIP-2 combination is already a 400, so
+ * upgrading them cannot regress anyone" -- **is no longer true**. The rule is
+ * unchanged; three other reasons hold it up:
+ *
+ * 1. A CAIP-2 network on the wire means the 402 that produced it advertised v2.
+ *    Answering in v2 is speaking the protocol the seller announced.
+ * 2. v2-with-CAIP-2 is the only shape BOTH generations of the facilitator
+ *    accept. v1-with-CAIP-2 is a hard 400 on any build older than 2026-09-04,
+ *    so choosing v1 there is what breaks against a self-hosted or pinned one.
+ * 3. The Python SDK resolves the identical rule, so the same wire produces the
+ *    same body in both SDKs -- pinned by phase 6 of `npm run test:xlang`.
+ *
+ * And the marker still decides nothing: row 2 above is served correctly today,
+ * so upgrading on the strength of it would change a call that works.
+ *
+ * The negative half of that measurement, without which "understood" proves
+ * nothing -- the same run, bodies broken on purpose, all three
+ * `invalid_request_body`: a v2 body carrying a plain network name, one with
+ * `resource` as a bare string, and one with `accepted` removed. A well-formed
+ * v2 body with CAIP-2 reached `contract_call_failed` like the rows above.
+ */
+declare function resolveEnvelopeVersion(paymentHeader: X402Header | PaymentPayloadV2, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
 /**
  * Build a `/verify` body in whichever envelope `version` names.
  *
@@ -2074,6 +2213,13 @@ declare class Erc8004LookupError extends Error {
      * `502` and `504` join `503` and `429` here: a gateway that answered on the
      * facilitator's behalf is exactly as silent about the agent's existence, and
      * reading either as absence has the same consequence -- a duplicate mint.
+     *
+     * **Except when the body says otherwise.** `POST /register` goes through the
+     * same EVM `send_transaction_from` as a settle, so it can answer
+     * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+     * a `502` where retrying is precisely the thing that mints the duplicate this
+     * class exists to prevent, so an explicit `retryable: false` wins over the
+     * status. See {@link SETTLEMENT_UNCONFIRMED}.
      */
     get retryable(): boolean;
     /**
@@ -2083,6 +2229,18 @@ declare class Erc8004LookupError extends Error {
      * request may be re-sent; see {@link isReplayableLeaseReason}.
      */
     get reason(): string | undefined;
+    /** The facilitator's machine-readable `error` code, when the body carried one. */
+    get errorCode(): string | undefined;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed.
+     *
+     * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+     * retrying: look it up on chain. An error that carries "do not retry" and no
+     * hash leaves the caller with nothing to act on.
+     */
+    get transaction(): string | undefined;
+    /** The payment id for {@link transaction}, identical to a successful settle's. */
+    get paymentId(): string | undefined;
     /**
      * The facilitator NAMED a reason proving it executed nothing.
      *
@@ -3217,4 +3375,4 @@ declare class AdvancedEscrowClient {
     private sendViaAdapter;
 }
 
-export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };
+export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type ParsedFacilitatorErrorBody, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, SETTLEMENT_UNCONFIRMED, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };

package/dist/backend/index.js

@@ -1108,6 +1108,7 @@ var REPLAYABLE_LEASE_REASONS = [
   "body_unreadable"
 ];
 var AMBIGUOUS_LEASE_REASONS = ["forward_failed"];
+var SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
 var MAX_RETRY_AFTER_SECONDS = 15;
 var DEFAULT_RETRY_AFTER_SECONDS = 5;
 var DEFAULT_FACILITATOR_RETRIES = 2;
@@ -1129,15 +1130,44 @@ function parseRetryAfterSeconds(response) {
   if (!Number.isFinite(seconds) || seconds < 0) return void 0;
   return Math.min(seconds, MAX_RETRY_AFTER_SECONDS);
 }
-function reasonFrom(body) {
+function stringField(source, key) {
+  const value = source[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function transactionHashIn(source) {
+  const tx = source.transaction;
+  if (tx && typeof tx === "object") {
+    const hash = tx.hash;
+    if (typeof hash === "string" && hash !== "") return hash;
+  }
+  if (typeof tx === "string" && tx !== "") return tx;
+  for (const key of ["txHash", "tx_hash", "transaction_hash"]) {
+    const value = stringField(source, key);
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function parseFacilitatorErrorBody(body) {
+  let parsed;
   try {
-    const parsed = JSON.parse(body);
-    if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
-      return parsed.reason;
-    }
+    parsed = JSON.parse(body);
   } catch {
+    return {};
   }
-  return void 0;
+  if (!parsed || typeof parsed !== "object") return {};
+  return {
+    errorCode: stringField(parsed, "error"),
+    reason: stringField(parsed, "reason"),
+    transaction: transactionHashIn(parsed),
+    paymentId: stringField(parsed, "paymentId"),
+    retryable: typeof parsed.retryable === "boolean" ? parsed.retryable : void 0
+  };
+}
+function isDeclaredUnretryable(parsed) {
+  return parsed.retryable === false || parsed.errorCode === SETTLEMENT_UNCONFIRMED || parsed.transaction !== void 0;
+}
+function isSettlementUnconfirmed(failure) {
+  return failure.errorCode === SETTLEMENT_UNCONFIRMED;
 }
 async function readFacilitatorError(response) {
   let body = "";
@@ -1147,14 +1177,19 @@ async function readFacilitatorError(response) {
     body = "";
   }
   const status = response.status;
-  const reason = reasonFrom(body);
-  const retryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const parsed = parseFacilitatorErrorBody(body);
+  const reason = parsed.reason;
+  const transportRetryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const retryable = transportRetryable && !isDeclaredUnretryable(parsed);
   const retryAfterSeconds = retryable ? parseRetryAfterSeconds(response) ?? DEFAULT_RETRY_AFTER_SECONDS : void 0;
-  const safeToReplay = status === 429 || status === 503 && isReplayableLeaseReason(reason);
+  const safeToReplay = retryable && (status === 429 || status === 503 && isReplayableLeaseReason(reason));
   return {
     error: `Facilitator error: ${status} - ${body}`,
     status,
     reason,
+    errorCode: parsed.errorCode,
+    transaction: parsed.transaction,
+    paymentId: parsed.paymentId,
     retryAfterSeconds,
     retryable,
     safeToReplay,
@@ -1167,6 +1202,11 @@ function failureFields(info) {
     retryable: info.retryable,
     safeToReplay: info.safeToReplay,
     ...info.reason !== void 0 ? { reason: info.reason } : {},
+    ...info.errorCode !== void 0 ? { errorCode: info.errorCode } : {},
+    // Without these the caller is told "do not retry" and given nothing to do
+    // instead — an error that swallows the hash is the same defect one layer up.
+    ...info.transaction !== void 0 ? { transaction: info.transaction } : {},
+    ...info.paymentId !== void 0 ? { paymentId: info.paymentId } : {},
     ...info.retryAfterSeconds !== void 0 ? { retryAfterSeconds: info.retryAfterSeconds } : {}
   };
 }
@@ -1174,6 +1214,9 @@ function carryFailureFields(source) {
   return {
     ...source.status !== void 0 ? { status: source.status } : {},
     ...source.reason !== void 0 ? { reason: source.reason } : {},
+    ...source.errorCode !== void 0 ? { errorCode: source.errorCode } : {},
+    ...source.transaction !== void 0 ? { transaction: source.transaction } : {},
+    ...source.paymentId !== void 0 ? { paymentId: source.paymentId } : {},
     ...source.retryable !== void 0 ? { retryable: source.retryable } : {},
     ...source.retryAfterSeconds !== void 0 ? { retryAfterSeconds: source.retryAfterSeconds } : {},
     ...source.safeToReplay !== void 0 ? { safeToReplay: source.safeToReplay } : {}
@@ -1261,7 +1304,23 @@ function buildPaymentRequirements(options) {
 }
 function buildVerifyRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // The literal `1` names THIS ENVELOPE, not the payer's header. Echoing
+    // `paymentHeader.x402Version` here -- what this did until 2026-09-04 --
+    // let a buyer who declared `2` produce a body that says "2" while carrying
+    // `paymentRequirements`, which is the v1 shape. The facilitator serves it
+    // anyway because its envelope enum is untagged and matches on shape, so
+    // nothing broke; but it ALREADY picks the hint in its 400 off this marker:
+    //
+    //   "This body declares `x402Version: 2`. x402 v2 is a JSON object with
+    //    `paymentPayload`, `resource` and `accepted`..."
+    //
+    // So the day that body fails for any other reason, the diagnosis sends the
+    // integrator to document the wrong shape. That inversion -- being told to
+    // fix the fields when the wrapper is what is wrong -- is what cost two
+    // teams a day. The payer's own marker survives untouched inside
+    // `paymentPayload`, where it belongs: it describes the payment, not the
+    // envelope carrying it.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
@@ -1284,13 +1343,21 @@ function buildSettleRequestV2(payload, resource, accepted) {
 }
 function buildSettleRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // `1` for the same reason as {@link buildVerifyRequest}: it names the
+    // envelope, and `/settle` takes the same body as `/verify`.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
 }
 function isCaip2Network(network) {
-  return network.includes(":");
+  return typeof network === "string" && network.includes(":");
+}
+function networkOfPayload(payload) {
+  const top = payload.network;
+  if (typeof top === "string") return top;
+  const accepted = payload.accepted;
+  return typeof accepted?.network === "string" ? accepted.network : void 0;
 }
 function toResourceInfoV2(requirements) {
   return {
@@ -1300,9 +1367,15 @@ function toResourceInfoV2(requirements) {
   };
 }
 function toPaymentRequirementsV2(requirements) {
+  const network = isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network);
+  if (!isCaip2Network(network)) {
+    throw new Error(
+      `Network '${requirements.network}' has no CAIP-2 form, so it cannot travel in the x402 v2 envelope. Use x402Version: 1 for this network.`
+    );
+  }
   return {
     scheme: requirements.scheme,
-    network: isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network),
+    network,
     asset: requirements.asset,
     amount: requirements.maxAmountRequired,
     payTo: requirements.payTo,
@@ -1315,7 +1388,7 @@ function resolveEnvelopeVersion(paymentHeader, requirements, requested = "auto")
   if (requested !== "auto") {
     return requested;
   }
-  return isCaip2Network(paymentHeader.network) || isCaip2Network(requirements.network) ? 2 : 1;
+  return isCaip2Network(networkOfPayload(paymentHeader)) || isCaip2Network(requirements.network) ? 2 : 1;
 }
 function buildVerifyRequestForVersion(paymentHeader, requirements, version) {
   if (version === 2) {
@@ -1988,16 +2061,23 @@ function createPaymentMiddleware(getRequirements, options = {}) {
           respondUnavailable(res, "Payment settlement unavailable", settleResult);
           return;
         }
-        res.status(500).json({
-          error: "Payment settlement failed",
-          reason: settleResult.error || "Unknown settlement error"
-        });
+        res.status(500).json(settlementFailureBody(settleResult, "Unknown settlement error"));
         return;
       }
     }
     next();
   };
 }
+function settlementFailureBody(failure, fallbackReason) {
+  return {
+    error: "Payment settlement failed",
+    reason: failure.error || fallbackReason,
+    retryable: false,
+    ...failure.errorCode !== void 0 ? { errorCode: failure.errorCode } : {},
+    ...failure.transaction !== void 0 ? { transaction: failure.transaction } : {},
+    ...failure.paymentId !== void 0 ? { paymentId: failure.paymentId } : {}
+  };
+}
 function honoUnavailable(c, message, failure) {
   const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
   c.header?.("Retry-After", String(seconds));
@@ -2072,10 +2152,7 @@ function createHonoMiddleware(options) {
         if (settleResult.retryable) {
           return honoUnavailable(c, "Payment settlement unavailable", settleResult);
         }
-        return c.json({
-          error: "Payment settlement failed",
-          reason: settleResult.error || "Unknown error"
-        }, 500);
+        return c.json(settlementFailureBody(settleResult, "Unknown error"), 500);
       }
     }
     await next();
@@ -2878,8 +2955,19 @@ var Erc8004LookupError = class extends Error {
    * `502` and `504` join `503` and `429` here: a gateway that answered on the
    * facilitator's behalf is exactly as silent about the agent's existence, and
    * reading either as absence has the same consequence -- a duplicate mint.
+   *
+   * **Except when the body says otherwise.** `POST /register` goes through the
+   * same EVM `send_transaction_from` as a settle, so it can answer
+   * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+   * a `502` where retrying is precisely the thing that mints the duplicate this
+   * class exists to prevent, so an explicit `retryable: false` wins over the
+   * status. See {@link SETTLEMENT_UNCONFIRMED}.
    */
   get retryable() {
+    const parsed = parseFacilitatorErrorBody(this.body);
+    if (parsed.retryable === false || parsed.errorCode === SETTLEMENT_UNCONFIRMED) {
+      return false;
+    }
     return this.status === 429 || this.status === 502 || this.status === 503 || this.status === 504;
   }
   /**
@@ -2889,14 +2977,25 @@ var Erc8004LookupError = class extends Error {
    * request may be re-sent; see {@link isReplayableLeaseReason}.
    */
   get reason() {
-    try {
-      const parsed = JSON.parse(this.body);
-      if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
-        return parsed.reason;
-      }
-    } catch {
-    }
-    return void 0;
+    return parseFacilitatorErrorBody(this.body).reason;
+  }
+  /** The facilitator's machine-readable `error` code, when the body carried one. */
+  get errorCode() {
+    return parseFacilitatorErrorBody(this.body).errorCode;
+  }
+  /**
+   * A transaction that WAS broadcast and could not be confirmed.
+   *
+   * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+   * retrying: look it up on chain. An error that carries "do not retry" and no
+   * hash leaves the caller with nothing to act on.
+   */
+  get transaction() {
+    return parseFacilitatorErrorBody(this.body).transaction;
+  }
+  /** The payment id for {@link transaction}, identical to a successful settle's. */
+  get paymentId() {
+    return parseFacilitatorErrorBody(this.body).paymentId;
   }
   /**
    * The facilitator NAMED a reason proving it executed nothing.
@@ -2906,7 +3005,7 @@ var Erc8004LookupError = class extends Error {
    * this is false is the sequence that minted five duplicate agents.
    */
   get safeToReplay() {
-    return this.status === 429 || this.status === 503 && isReplayableLeaseReason(this.reason);
+    return this.retryable && (this.status === 429 || this.status === 503 && isReplayableLeaseReason(this.reason));
   }
   /** Seconds to wait before retrying, clamped. Absent when not retryable. */
   get retryAfterSeconds() {
@@ -4767,6 +4866,7 @@ exports.PAYMENT_INFO_TYPEHASH = PAYMENT_INFO_TYPEHASH;
 exports.RELAYED_FEEDBACK_NETWORKS = RELAYED_FEEDBACK_NETWORKS;
 exports.REPLAYABLE_LEASE_REASONS = REPLAYABLE_LEASE_REASONS;
 exports.RegistrationPendingError = RegistrationPendingError;
+exports.SETTLEMENT_UNCONFIRMED = SETTLEMENT_UNCONFIRMED;
 exports.TIER_FILTERS = TIER_FILTERS;
 exports.TIER_TIMINGS = TIER_TIMINGS;
 exports.USDC_DOMAIN_NAME = USDC_DOMAIN_NAME;
@@ -4801,6 +4901,8 @@ exports.isEscrowExpired = isEscrowExpired;
 exports.isEscrowSupportedOnChain = isEscrowSupportedOnChain;
 exports.isRegisterJobTerminal = isRegisterJobTerminal;
 exports.isReplayableLeaseReason = isReplayableLeaseReason;
+exports.isSettlementUnconfirmed = isSettlementUnconfirmed;
+exports.parseFacilitatorErrorBody = parseFacilitatorErrorBody;
 exports.parsePaymentHeader = parsePaymentHeader;
 exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
 exports.readFacilitatorError = readFacilitatorError;