uvd-x402-sdk 2.77.0 → 2.79.0

package/README.md

@@ -1351,6 +1351,50 @@ const body = buildVerifyRequestV2(
 > error that names no field. If you see it, check the envelope shape first, not
 > the fields inside it.
 
+### The top-level `x402Version` names the ENVELOPE
+
+`VerifyRequest.x402Version` is typed `1`, not `1 | 2`: it says which of the two
+shapes above the body has, and `VerifyRequest` **is** the v1 shape. The payer's
+own version stays where the payer put it, in `paymentPayload.x402Version`, and
+the SDK never rewrites it.
+
+```typescript
+// A buyer that declares v2 while carrying plain network names — legal, and what
+// a 402 advertising CAIP-2 invites.
+const body = buildVerifyRequest({ x402Version: 2, scheme: 'exact', network: 'base', payload }, reqs);
+
+body.x402Version;                 // 1  — the envelope is v1
+body.paymentPayload.x402Version;  // 2  — the payer's marker, untouched
+```
+
+`resolveEnvelopeVersion` (and therefore the `'auto'` default) accepts a **v2
+payload** as well as a v1 header. A v2 payload has no top-level `network` at all
+— v2 moved the chain id into `accepted` — so `auto` reads it from there. Before
+**2.79.0** it read only the top level and threw
+`Cannot read properties of undefined` on exactly that shape, which is why
+integrators were pinning `x402Version` instead of using the default.
+
+A network with **no CAIP-2 form** cannot travel in a v2 body at all, so pinning
+version 2 on one throws instead of building it — `xrpl-mainnet` is the case: its
+v1 string *is* its network id. `auto` leaves those on v1, where they work, so
+you only reach the throw by pinning. It names the network and the escape, which
+the facilitator's `400` (`data did not match any variant of untagged enum`) does
+not.
+
+Until **2.79.0** the top level inherited `paymentHeader.x402Version`, so that
+call emitted a body declaring `2` around a `paymentRequirements` — a v1 shape.
+It was served correctly then and it is served correctly now: the facilitator's
+envelope enum is untagged and matches on shape. But the facilitator already
+reads that marker for one thing — choosing the hint in its `400`:
+
+> `This body declares `x402Version: 2`. x402 v2 is a JSON object with
+> `paymentPayload`, `resource` and `accepted`…`
+
+So the first time such a body failed for an unrelated reason, the diagnosis sent
+you to fix the wrong shape. If you were constructing a `VerifyRequest` by hand
+with a `1 | 2` variable, that no longer type-checks — write `1`, or use
+`buildVerifyRequestForVersion` and let it pick.
+
 ## Metrics and history (`getStats` / `getTransactions`)
 
 ```typescript

package/dist/backend/index.d.mts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.mjs';
-import { x as X402Header, Q as X402Version, G as X402PayloadData } from '../index-ZH10otHE.mjs';
+import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../index-ZH10otHE.mjs';
 
 /**
  * Reading a facilitator refusal as DATA instead of prose.
@@ -234,18 +234,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;
 }
@@ -527,6 +539,110 @@ declare function buildVerifyRequestV2(payload: X402PayloadData, resource: Resour
  */
 declare function buildSettleRequestV2(payload: X402PayloadData, resource: ResourceInfoV2, accepted: PaymentRequirementsV2): SettleRequestV2;
 declare function buildSettleRequest(paymentHeader: X402Header, requirements: PaymentRequirements): SettleRequest;
+/**
+ * Derive the v2 `resource` object from v1-shaped requirements.
+ *
+ * v2 moved `resource` / `description` / `mimeType` out of the requirements and
+ * into an object of their own, and the facilitator requires ALL THREE keys:
+ * measured 2026-09-03, a `resource` carrying only `url` is a 400.
+ *
+ * The `??` defaults are not decoration. `PaymentRequirements` types these as
+ * required, but a JavaScript caller can still hand over an object without them,
+ * and a missing key does not fail with "description is missing" -- it fails with
+ * `data did not match any variant of untagged enum VerifyRequestEnvelope`, which
+ * names no field. That error is what cost two teams a day.
+ */
+declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceInfoV2;
+/**
+ * Derive v2 `accepted` requirements from v1-shaped requirements.
+ *
+ * Two renames do the damage, and neither is reported by name when it is wrong:
+ * - `maxAmountRequired` is spelled `amount` in v2.
+ * - `network` must be CAIP-2; a plain name inside a v2 body is a 400.
+ *
+ * `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;
+/**
+ * Decide which envelope this (payment, requirements) pair has to travel in.
+ *
+ * `requested` wins when it names a version; `'auto'` (the default) reads the
+ * wire.
+ *
+ * **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.
+ *
+ * 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`               | 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.
+ *
+ * The v1 return is byte-for-byte what {@link buildVerifyRequest} produces, so
+ * pinning `1` is exactly today's behaviour.
+ *
+ * @example
+ * ```ts
+ * const version = resolveEnvelopeVersion(payment, requirements);
+ * const body = buildVerifyRequestForVersion(payment, requirements, version);
+ * ```
+ */
+declare function buildVerifyRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): VerifyRequest | VerifyRequestV2;
+/**
+ * Build a `/settle` body in whichever envelope `version` names.
+ *
+ * See {@link buildVerifyRequestForVersion} -- `/settle` takes the same body as
+ * `/verify` in both versions.
+ */
+declare function buildSettleRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): SettleRequest | SettleRequestV2;
 /**
  * Recommended CORS headers for x402 payment APIs
  *
@@ -585,6 +701,16 @@ interface FacilitatorClientOptions {
      * -- is never replayed here, at any setting.
      */
     retries?: number;
+    /**
+     * Which envelope to send to `/verify` and `/settle`. Default `'auto'`.
+     *
+     * `'auto'` reads the wire: CAIP-2 networks get the v2 envelope, plain names
+     * get v1. See {@link resolveEnvelopeVersion} for the measurements behind that
+     * rule. Pin `1` or `2` to take the decision yourself -- a pin is honoured
+     * even when it contradicts the wire, because choosing the version is the
+     * point of the option.
+     */
+    x402Version?: X402Version | 'auto';
 }
 /**
  * Client for interacting with the x402 facilitator API
@@ -611,6 +737,7 @@ declare class FacilitatorClient {
     private readonly timeout;
     private readonly explicitTimeout;
     private readonly retries;
+    private readonly x402Version;
     constructor(options?: FacilitatorClientOptions);
     /**
      * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -3134,4 +3261,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, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, supportsRelayedFeedback, 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 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 };

package/dist/backend/index.d.ts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.js';
-import { x as X402Header, Q as X402Version, G as X402PayloadData } from '../index-ZH10otHE.js';
+import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../index-ZH10otHE.js';
 
 /**
  * Reading a facilitator refusal as DATA instead of prose.
@@ -234,18 +234,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;
 }
@@ -527,6 +539,110 @@ declare function buildVerifyRequestV2(payload: X402PayloadData, resource: Resour
  */
 declare function buildSettleRequestV2(payload: X402PayloadData, resource: ResourceInfoV2, accepted: PaymentRequirementsV2): SettleRequestV2;
 declare function buildSettleRequest(paymentHeader: X402Header, requirements: PaymentRequirements): SettleRequest;
+/**
+ * Derive the v2 `resource` object from v1-shaped requirements.
+ *
+ * v2 moved `resource` / `description` / `mimeType` out of the requirements and
+ * into an object of their own, and the facilitator requires ALL THREE keys:
+ * measured 2026-09-03, a `resource` carrying only `url` is a 400.
+ *
+ * The `??` defaults are not decoration. `PaymentRequirements` types these as
+ * required, but a JavaScript caller can still hand over an object without them,
+ * and a missing key does not fail with "description is missing" -- it fails with
+ * `data did not match any variant of untagged enum VerifyRequestEnvelope`, which
+ * names no field. That error is what cost two teams a day.
+ */
+declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceInfoV2;
+/**
+ * Derive v2 `accepted` requirements from v1-shaped requirements.
+ *
+ * Two renames do the damage, and neither is reported by name when it is wrong:
+ * - `maxAmountRequired` is spelled `amount` in v2.
+ * - `network` must be CAIP-2; a plain name inside a v2 body is a 400.
+ *
+ * `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;
+/**
+ * Decide which envelope this (payment, requirements) pair has to travel in.
+ *
+ * `requested` wins when it names a version; `'auto'` (the default) reads the
+ * wire.
+ *
+ * **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.
+ *
+ * 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`               | 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.
+ *
+ * The v1 return is byte-for-byte what {@link buildVerifyRequest} produces, so
+ * pinning `1` is exactly today's behaviour.
+ *
+ * @example
+ * ```ts
+ * const version = resolveEnvelopeVersion(payment, requirements);
+ * const body = buildVerifyRequestForVersion(payment, requirements, version);
+ * ```
+ */
+declare function buildVerifyRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): VerifyRequest | VerifyRequestV2;
+/**
+ * Build a `/settle` body in whichever envelope `version` names.
+ *
+ * See {@link buildVerifyRequestForVersion} -- `/settle` takes the same body as
+ * `/verify` in both versions.
+ */
+declare function buildSettleRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): SettleRequest | SettleRequestV2;
 /**
  * Recommended CORS headers for x402 payment APIs
  *
@@ -585,6 +701,16 @@ interface FacilitatorClientOptions {
      * -- is never replayed here, at any setting.
      */
     retries?: number;
+    /**
+     * Which envelope to send to `/verify` and `/settle`. Default `'auto'`.
+     *
+     * `'auto'` reads the wire: CAIP-2 networks get the v2 envelope, plain names
+     * get v1. See {@link resolveEnvelopeVersion} for the measurements behind that
+     * rule. Pin `1` or `2` to take the decision yourself -- a pin is honoured
+     * even when it contradicts the wire, because choosing the version is the
+     * point of the option.
+     */
+    x402Version?: X402Version | 'auto';
 }
 /**
  * Client for interacting with the x402 facilitator API
@@ -611,6 +737,7 @@ declare class FacilitatorClient {
     private readonly timeout;
     private readonly explicitTimeout;
     private readonly retries;
+    private readonly x402Version;
     constructor(options?: FacilitatorClientOptions);
     /**
      * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -3134,4 +3261,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, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, supportsRelayedFeedback, 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 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 };

package/dist/backend/index.js

@@ -1261,7 +1261,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,11 +1300,73 @@ 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 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 {
+    url: requirements.resource,
+    description: requirements.description ?? DEFAULT_PAYMENT_DESCRIPTION,
+    mimeType: requirements.mimeType ?? DEFAULT_PAYMENT_MIME_TYPE
+  };
+}
+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,
+    asset: requirements.asset,
+    amount: requirements.maxAmountRequired,
+    payTo: requirements.payTo,
+    // Required by the facilitator: omitting it is a 400, measured the same day.
+    maxTimeoutSeconds: requirements.maxTimeoutSeconds ?? DEFAULT_PAYMENT_TIMEOUT_SECONDS,
+    ...requirements.extra !== void 0 ? { extra: requirements.extra } : {}
+  };
+}
+function resolveEnvelopeVersion(paymentHeader, requirements, requested = "auto") {
+  if (requested !== "auto") {
+    return requested;
+  }
+  return isCaip2Network(networkOfPayload(paymentHeader)) || isCaip2Network(requirements.network) ? 2 : 1;
+}
+function buildVerifyRequestForVersion(paymentHeader, requirements, version) {
+  if (version === 2) {
+    return buildVerifyRequestV2(
+      paymentHeader.payload,
+      toResourceInfoV2(requirements),
+      toPaymentRequirementsV2(requirements)
+    );
+  }
+  return buildVerifyRequest(paymentHeader, requirements);
+}
+function buildSettleRequestForVersion(paymentHeader, requirements, version) {
+  if (version === 2) {
+    return buildSettleRequestV2(
+      paymentHeader.payload,
+      toResourceInfoV2(requirements),
+      toPaymentRequirementsV2(requirements)
+    );
+  }
+  return buildSettleRequest(paymentHeader, requirements);
+}
 var X402_CORS_HEADERS = {
   "Access-Control-Allow-Headers": "Content-Type, X-PAYMENT, PAYMENT-SIGNATURE, Authorization",
   "Access-Control-Expose-Headers": "X-PAYMENT-RESPONSE, PAYMENT-RESPONSE, PAYMENT-REQUIRED",
@@ -1312,11 +1390,13 @@ var FacilitatorClient = class {
   timeout;
   explicitTimeout;
   retries;
+  x402Version;
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || "https://facilitator.ultravioletadao.xyz";
     this.explicitTimeout = options.timeout !== void 0;
     this.timeout = options.timeout || 3e4;
     this.retries = options.retries;
+    this.x402Version = options.x402Version ?? "auto";
   }
   /**
    * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -1342,7 +1422,11 @@ var FacilitatorClient = class {
    * @returns Verification result
    */
   async verify(paymentHeader, requirements) {
-    const body = buildVerifyRequest(paymentHeader, requirements);
+    const body = buildVerifyRequestForVersion(
+      paymentHeader,
+      requirements,
+      resolveEnvelopeVersion(paymentHeader, requirements, this.x402Version)
+    );
     try {
       const { response, error } = await facilitatorFetch(
         `${this.baseUrl}/verify`,
@@ -1381,7 +1465,11 @@ var FacilitatorClient = class {
    * @returns Settlement result with transaction hash
    */
   async settle(paymentHeader, requirements) {
-    const body = buildSettleRequest(paymentHeader, requirements);
+    const body = buildSettleRequestForVersion(
+      paymentHeader,
+      requirements,
+      resolveEnvelopeVersion(paymentHeader, requirements, this.x402Version)
+    );
     const settleTimeout = this.getTimeout(requirements.network);
     try {
       const { response, error } = await facilitatorFetch(
@@ -4719,8 +4807,10 @@ exports.ZERO_ADDRESS = ZERO_ADDRESS;
 exports.buildErc8004PaymentRequirements = buildErc8004PaymentRequirements;
 exports.buildPaymentRequirements = buildPaymentRequirements;
 exports.buildSettleRequest = buildSettleRequest;
+exports.buildSettleRequestForVersion = buildSettleRequestForVersion;
 exports.buildSettleRequestV2 = buildSettleRequestV2;
 exports.buildVerifyRequest = buildVerifyRequest;
+exports.buildVerifyRequestForVersion = buildVerifyRequestForVersion;
 exports.buildVerifyRequestV2 = buildVerifyRequestV2;
 exports.canRefundEscrow = canRefundEscrow;
 exports.canReleaseEscrow = canReleaseEscrow;
@@ -4744,7 +4834,10 @@ exports.isReplayableLeaseReason = isReplayableLeaseReason;
 exports.parsePaymentHeader = parsePaymentHeader;
 exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
 exports.readFacilitatorError = readFacilitatorError;
+exports.resolveEnvelopeVersion = resolveEnvelopeVersion;
 exports.supportsRelayedFeedback = supportsRelayedFeedback;
+exports.toPaymentRequirementsV2 = toPaymentRequirementsV2;
+exports.toResourceInfoV2 = toResourceInfoV2;
 exports.wireNetwork = wireNetwork;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map