@parallel-protocol/x402 0.8.1 → 0.8.3

package/README.md

@@ -40,7 +40,7 @@ Agent                        Merchant (this SDK)           Facilitator
 - The handler only runs after the signature is verified.
 - The on-chain settlement happens after the handler produces a 2xx response — the agent is not charged on errors.
 - The settle is bound to the merchant that verified: `POST /x402/verify` hands the middleware a settle token that `POST /x402/settle` must present. The token stays in memory for the life of the request and never reaches the agent.
-- If settlement fails, the middleware discards the handler's response and returns `402` with `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }`: `reason` is the facilitator's code (`INSUFFICIENT_BALANCE`, `AUTHORIZATION_USED`, `PAYMENT_EXPIRED`, ...) or this SDK's (`SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`, `AMOUNT_MISMATCH`, `UNKNOWN`), `message` the facilitator's text or this SDK's, and the facilitator's `Retry-After` is copied when it sent one. A settle that timed out or could not reach the facilitator is retried once first: the same settle is idempotent, and the facilitator answers the recorded outcome if the first attempt went through.
+- If settlement fails, the middleware discards the handler's response and returns `402` with `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }`: `reason` is the facilitator's code (`INSUFFICIENT_BALANCE`, `AUTHORIZATION_USED`, `PAYMENT_EXPIRED`, ...) or this SDK's (`SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`, `AMOUNT_MISMATCH`, `UNKNOWN`), `message` the facilitator's text or this SDK's, and the facilitator's `Retry-After` is copied when it sent one. A settle that timed out or could not reach the facilitator is retried once first, with the same settle token: once the first attempt has finished, the facilitator answers its recorded outcome, and any other answer to the retry tells the agent to check with the merchant.
 - A metered settle must settle the amount the handler asked for: a confirmation for another amount is refused and the response discarded.
 - Handlers are bounded by a 30-second timeout on Express, Hono and Next.js — a slow handler returns `504` and the agent is not charged. (Fastify manages handler execution itself, so no timeout is applied there.) Metered routes get their announced window minus two minutes kept for the settlement and its retry.
 - On paid Fastify routes, writing to `reply.raw` (the SSE/streaming pattern) fails loudly instead of sending: a raw response skips the settlement hooks and would go out unpaid. Streaming is not supported on paid routes.
@@ -222,7 +222,7 @@ For the four natively supported networks, `acceptedTokens` defaults to `[USDp, U
 | `avalanche` | `0x9eE1963f05553eF838604Dd39403be21ceF26AA4` | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` | `0x9d92c21205383651610f90722131655a5b8ed3e0` |
 | `hyperevm` | `0xBE65F0F410A72BeC163dC65d46c83699e957D588` | `0xb88339cb7199b77e23db6e890353e22632ba630f` | `0x9B3a8f7CEC208e247d97dEE13313690977e24459` |
 
-For any other network (from the full Parallel 24-chain catalog), you must provide `acceptedTokens` explicitly, or the middleware throws `X402ConfigError` on the first request to that route. The facilitator advertises routes on the four networks above only, and the invoice of any other network names it `eip155:<slug>`, which `@parallel-protocol/x402-fetch` cannot pay.
+A route on any other chain of the Parallel catalog, such as Sonic, raises `X402ConfigError` at construction.
 
 You can also import the token list directly:
 
@@ -255,7 +255,7 @@ routes: {
 }
 ```
 
-**Accepting Parallelizer collateral payments:** Each supported network exposes additional collateral tokens whitelisted in the Parallelizer contract. They are available in `PARALLEL_TOKENS` but excluded from the defaults. Add them to `acceptedTokens` to let merchants receive them directly:
+**Accepting Parallelizer collateral payments:** Each supported network exposes additional collateral tokens whitelisted in the Parallelizer contract. They are available in `PARALLEL_TOKENS` but excluded from the defaults. Add them to `acceptedTokens` to receive them: the agent pays in USDp or sUSDp, and the Parallelizer swaps to the collateral in the same settlement (routes D, K and L):
 
 | Network | Token | Key | Yield-bearing |
 |---------|-------|-----|---------------|
@@ -347,6 +347,10 @@ const header = Buffer.from(JSON.stringify(signedPayload)).toString("base64");
 
 See [`@parallel-protocol/payment-core`](../payment-core) for EIP-3009 signing helpers.
 
+### Request header: `x402-client`
+
+A payer on `@parallel-protocol/x402-fetch` 0.5.0 or later also sends an `x402-client` header with the x402-fetch and CLI versions it runs, for example `x402-client: x402-fetch/0.5.0 cli/0.5.1`, and nothing else about the agent. Earlier releases and other clients send none. The middleware does not read it. Your handler can read it to spot a payer on outdated versions and tell it to update.
+
 ### 200 response: `payment-response`
 
 On success, the middleware sets a `payment-response` header with a base64-encoded settlement confirmation:
@@ -545,9 +549,9 @@ The facilitator supports 13 settlement routes. The route is selected automatical
 | **B** | `swapExactOutputWithAuthorization` | USDp | USDC (exact) | ~120K | Parallelizer swaps agent's USDp → exact USDC for merchant |
 | **C** | `depositWithAuthorization` | USDp | sUSDp | ~110K | Agent's USDp deposited into the savings vault, the merchant receives sUSDp shares |
 | **D** | `swapExactOutputWithAuthorization` | USDp | non-USDC backing collateral (exact) | ~120K | Same as B but for other Parallelizer collaterals |
-| **E** | `swapExactInputWithAuthorization` | USDC or a collateral (exact) | USDp (min) | ~120K | Agent pays an exact amount, the Parallelizer delivers at least the minimum USDp to the merchant |
-| **F** | `transferWithAuthorization` | USDC or a collateral | same token | ~65K | Direct EIP-3009 token push |
-| **G** | `swapExactInputWithAuthorization` | USDC or a collateral (exact) | sUSDp | ~200K | The token is swapped to USDp, then the USDp is deposited as sUSDp for the merchant (atomic multicall3) |
+| **E** | `swapExactInputWithAuthorization` | USDC (exact), on Base and Avalanche | USDp (min) | ~120K | Agent pays an exact amount, the Parallelizer delivers at least the minimum USDp to the merchant |
+| **F** | `transferWithAuthorization` | USDC | USDC | ~65K | Direct USDC transfer |
+| **G** | `swapExactInputWithAuthorization` | USDC (exact), on Base and Avalanche | sUSDp | ~200K | The USDC is swapped to USDp, then the USDp is deposited as sUSDp for the merchant (atomic multicall3) |
 | **H** | `redeemWithAuthorization` | sUSDp shares | USDp | ~130K | Agent burns sUSDp shares; merchant receives USDp assets |
 | **I** | `redeemWithAuthorization` + `swapExactOutputWithAuthorization` | sUSDp | USDC (exact) | ~180K | Agent redeems sUSDp → USDp, then swaps USDp → exact USDC for merchant (atomic multicall3) |
 | **J** | `transferWithAuthorization` | sUSDp | sUSDp | ~65K | Direct sUSDp share transfer |
@@ -557,9 +561,10 @@ The facilitator supports 13 settlement routes. The route is selected automatical
 
 **Chain requirements:**
 - Routes B, D, E, G, I, K, L require the **Parallelizer** to be deployed on the target chain (Ethereum, Base, Avalanche, HyperEVM).
-- Routes B and I swap to USDC, so they need USDC among the chain's collaterals, which is the case on Base and Avalanche.
+- Routes B and I swap to USDC, and routes E and G swap from it, so they need USDC among the chain's collaterals, which is the case on Base and Avalanche.
 - Routes C, G, H, I, J, K, L require **sUSDp** (savings module) to be deployed on the target chain.
-- Route A needs USDp on the chain. Routes E, F and G take as `tokenIn` the chain's USDC or one of its collaterals (see [Default tokens](#default-tokens)), and the token must support EIP-3009. Any other `tokenIn` is refused at verify, with `PAYMENT_METHOD_NOT_SUPPORTED` when it gets past the signature checks.
+- Agents pay with USDp, sUSDp or the chain's USDC. Route F takes the chain's USDC, routes E and G the chain's USDC where it is a collateral (Base and Avalanche). On these three routes any other `tokenIn` is refused at verify and at settle with `PAYMENT_METHOD_NOT_SUPPORTED`, before the signature is checked.
+- The facilitator settles on Ethereum, Base, Avalanche and HyperEVM. A payment on another chain is refused at verify and at settle with `NETWORK_MISMATCH`.
 - Route U needs the escrow contract, deployed on Base only. A metered payment on another chain is refused at verify with `PAYMENT_METHOD_NOT_SUPPORTED`.
 - Gas sponsorship is decided by the facilitator per payment and reported as `gasSponsored` in the settlement receipt.
 - The facilitator's `GET /capabilities?chain=<slug>` lists the routes available on a chain right now, with the gas estimates above and the burn fees.
@@ -755,7 +760,7 @@ if (result.success) {
 }
 ```
 
-The constructor throws `X402ConfigError` when the URL is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, and the client keeps the address it checked. No call follows a redirect. `verify` uses a 10-second timeout. `settle` uses a 60-second timeout to accommodate on-chain confirmation latency. `verify` throws on any failure, with the facilitator's message in `.detail`, its HTTP status in `.status` and its `Retry-After` in `.retryAfter`. A facilitator that issues no settle token is an invalid response. `settle` returns a `FacilitatorResponse` union on facilitator errors, with the facilitator's status and `Retry-After` on `error`, and throws `X402RuntimeError` on connectivity issues (`SETTLE_TIMEOUT` when the 60 seconds ran out, the payment may still settle), an undecodable payment header, or a malformed facilitator response. A settle refused with a status below 500 and no `error` field comes back as `SUBMISSION_FAILED`, one at 500 or above with no `error` field throws `FACILITATOR_UNAVAILABLE`. The settle token is a secret for the life of the request: keep it in memory, never log it, never send it to the payer.
+The constructor throws `X402ConfigError` when the URL is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, and the client keeps the address it checked. No call follows a redirect. `verify` uses a 10-second timeout. `settle` uses a 60-second timeout to accommodate on-chain confirmation latency. `verify` throws on any failure, with the facilitator's message in `.detail`, its HTTP status in `.status` and its `Retry-After` in `.retryAfter`. A facilitator that issues no settle token is an invalid response. `settle` returns a `FacilitatorResponse` union on facilitator errors, with the facilitator's status and `Retry-After` on `error`, and throws `X402RuntimeError` on connectivity issues (`SETTLE_TIMEOUT` when the 60 seconds ran out, the payment may still settle), an undecodable payment header, or a malformed facilitator response. A settle answered with an error that carries no `error` field throws `FACILITATOR_UNAVAILABLE` with that status: the answer comes from something in front of the facilitator, and the payment may still settle. The settle token is a secret for the life of the request: keep it in memory, never log it, never send it to the payer.
 
 For a metered payment, the requirements also carry `scheme: "upto"` and `maxTimeoutSeconds`, and `settle` takes the amount to charge, in the token's smallest unit, next to the settle token: `{ settleToken, amount }`.
 
@@ -779,7 +784,7 @@ What the middleware answers on a paid route instead of the handler's response:
 
 | Error class | When |
 |-------------|------|
-| `X402ConfigError` | Invalid config at construction, the message naming the first field at fault: a bad `payTo`, a facilitator URL that is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, empty `routes`, a malformed or non-positive `price`, a `meter` on a route that is not `upto`, or an `upto` route with `maxTimeoutSeconds` above 3600 or a token other than USDp. Then, on a request to a route: an unknown network with no `acceptedTokens`, an accepted token whose decimals are neither in the catalog nor set via `decimals`, a price finer than the token's precision, or a price function that throws or returns something that is not a price |
+| `X402ConfigError` | Invalid config at construction, the message naming the first field at fault: a bad `payTo`, a facilitator URL that is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, empty `routes`, a `network` of the catalog other than `ethereum`, `base`, `avalanche` or `hyperevm`, a malformed or non-positive `price`, a `meter` on a route that is not `upto`, or an `upto` route with `maxTimeoutSeconds` above 3600 or a token other than USDp. Then, on a request to a route: an unknown network with no `acceptedTokens`, an accepted token whose decimals are neither in the catalog nor set via `decimals`, a price finer than the token's precision, or a price function that throws or returns something that is not a price |
 | `X402RuntimeError` | Runtime failure; `.code` is one of the SDK codes below, or a facilitator error code propagated verbatim (see next table) |
 | `X402PriceRejectedError` | Thrown by a price function to refuse a request before anything is invoiced; the client gets `.status` (400 by default) with `{ error: .code, message }`. `isPriceRejection(err)` recognises one by shape. |
 
@@ -807,12 +812,12 @@ The SDK raises it when the facilitator gave no usable answer:
 - It could not be reached: a DNS, connection or TLS failure.
 - It answered with a redirect, which the SDK never follows. The error's `status` is the redirect's, and the configured `url` is then usually not the facilitator's own https address.
 - It did not answer a `verify` within 10 seconds. A `settle` that runs out of its 60 seconds raises `SETTLE_TIMEOUT` instead.
-- It answered a `verify` with an error that carries no `error` field, such as an error page from a gateway in front of it, or a `settle` with a 5xx error that carries no `error` field.
+- It answered with an error that carries no `error` field, such as an error page from a gateway or a firewall in front of it. The error's `status` is that answer's.
 - It answered with a success status but a body that is not JSON, or that was cut off.
 
 At `verify`, nothing was settled. The middleware answers the agent 402 with a new invoice and `error: "FACILITATOR_UNAVAILABLE"`, and the agent can pay again later.
 
-At `settle`, the outcome is unknown, since the facilitator may have settled before its answer was lost. The middleware retries the settle once with the same settle token, which returns the recorded outcome if there is one. If the retry raises it too, the response is not served, and the agent gets a 402 `{ error: "PAYMENT_SETTLEMENT_FAILED", reason: "FACILITATOR_UNAVAILABLE" }` whose message tells it not to sign another payment before checking with the merchant. A retry that fails another way reports that reason instead.
+At `settle`, the outcome is unknown, since the facilitator may have settled before its answer was lost. The middleware retries the settle once with the same settle token, which returns the recorded outcome once the first attempt has finished. If the retry raises it too, the response is not served, and the agent gets a 402 `{ error: "PAYMENT_SETTLEMENT_FAILED", reason: "FACILITATOR_UNAVAILABLE" }` whose message tells it not to sign another payment before checking with the merchant. A retry that fails another way reports that reason instead.
 
 ### Propagated from the facilitator
 
@@ -822,7 +827,7 @@ When the facilitator refuses a payment at verify, its code is forwarded as the `
 |------|--------------------|---------|--------------------------|
 | `INVALID_PAYLOAD` | 400 | The payload does not have the shape of its route, carries a field another route would read, or uses a method of the other scheme | Sign a payment that matches one of the `accepts` entries |
 | `INVALID_SIGNATURE` | 400 | EIP-712 signature recovery failed | Sign again |
-| `INVALID_NONCE` | 409 | Nonce already used (replay detected) | Sign a new payment with a fresh nonce |
+| `INVALID_NONCE` | 409 | Nonce already used: the same payment reached the facilitator before, and may have settled | Do not sign another payment before checking with the merchant |
 | `PAYMENT_EXPIRED` | 402 | `validBefore` has passed | Sign a new payment |
 | `INSUFFICIENT_AMOUNT` | 402 | The amount the route guarantees the merchant is below the price, or the authorization is for zero | Sign for the invoiced `amount` |
 | `INSUFFICIENT_BALANCE` | 402 | The payer does not hold the signed amount (metered payments) | Fund the wallet, sign a new payment |
@@ -833,6 +838,8 @@ When the facilitator refuses a payment at verify, its code is forwarded as the `
 | `PAYMENT_METHOD_NOT_SUPPORTED` | 400 | No route for this method or token on this chain, including a metered payment on a chain without the escrow | Pay with another method or token |
 | `COLLATERAL_NOT_SUPPORTED` | 400 | The swap delivers a token that is not a collateral of the chain | Pay for another of the `accepts` assets: the merchant lists one the facilitator does not deliver |
 | `RATE_LIMIT_EXCEEDED` | 429 | The payer passed 1,000 verifies in the current UTC hour | Pay again after `Retry-After`, which points to the next hour |
+| `PARALLELIZER_PAUSED` | 503 | The Parallelizer has closed the swap the payment needs, or its state could not be read. Nothing was taken | Pay with another token, or pay again later |
+| `SAVINGS_PAUSED` | 503 | The sUSDp savings vault the payment deposits into or redeems from is paused, or its state could not be read. Nothing was taken | Pay with another token, or pay again later |
 | `SERVICE_UNAVAILABLE` | 503 | The facilitator could not read the chain or its own store | Pay again after a short wait |
 
 An `error` that is not a code (capitals, digits and underscores) is not forwarded: the 402 carries `error: "FACILITATOR_INVALID_RESPONSE"` with the facilitator's message instead. The facilitator answers this way with `Bad Request` to a payment payload that does not match its request schema, and with `Too Many Requests` from its per-IP limit (see [Rate limits](#rate-limits)).
@@ -842,19 +849,22 @@ When the facilitator refuses at settle, the 402 body is `{ error: "PAYMENT_SETTL
 | Reason | Facilitator status | Meaning | What the agent should do |
 |--------|--------------------|---------|--------------------------|
 | `INSUFFICIENT_BALANCE` | 402 | The payer no longer holds the signed amount | Fund the wallet, sign a new payment |
-| `AUTHORIZATION_USED` | 409 | The authorization nonce is consumed or cancelled on-chain, this facilitator did not settle it | Sign a new payment |
+| `AUTHORIZATION_USED` | 409 | The authorization is already consumed or cancelled on-chain. It may have paid the merchant | Do not sign another payment before checking with the merchant |
 | `PAYMENT_EXPIRED` | 402 | The authorization expired before settlement | Sign a new payment |
-| `PAYMENT_NOT_VERIFIED` | 402 | No verified payment for this authorization, or it already failed | Sign a new payment |
+| `PAYMENT_NOT_VERIFIED` | 402 | No verified payment for this authorization, or an earlier settle of it failed. After `AUTHORIZATION_USED`, `RECEIPT_UNAVAILABLE` or `SUBMISSION_FAILED`, a repeated settle gets that code again instead. The merchant may have been paid, or may still be | Do not sign another payment before checking with the merchant |
 | `SETTLE_IN_PROGRESS` | 409 | Another settle of the same payment is still running | Do not sign another payment before checking with the merchant |
 | `SETTLE_TOKEN_INVALID`, `SETTLE_TOKEN_REQUIRED` | 403 | The merchant did not present the settle token verify issued: a merchant client issue, not the payer's, and nothing was settled | Do not sign another payment before checking with the merchant |
-| `RELAYER_UNAVAILABLE`, `PARALLELIZER_PAUSED`, `SERVICE_UNAVAILABLE` | 503 | The facilitator or the chain is temporarily unable to settle | Retry later with a new payment, after `Retry-After` when given |
+| `RELAYER_UNAVAILABLE` | 503 | The facilitator is temporarily unable to settle. The payment was not taken, and the facilitator will not settle it | Retry later with a new payment, after `Retry-After` when given |
+| `PARALLELIZER_PAUSED`, `SAVINGS_PAUSED`, `SERVICE_UNAVAILABLE` | 503 | The swap or the savings vault the payment needs is paused, or its state could not be read, or the facilitator or the chain is temporarily unable to settle. This settle sent nothing, but the payment may still settle until its authorization expires, and an earlier attempt may already have settled it | Do not sign another payment before checking with the merchant |
 | `TX_REVERTED` | 500 | The transaction reverted for a reason the facilitator could not attribute | Sign a new payment |
-| `SUBMISSION_FAILED` | 500 | The submission failed. When the message says the outcome is unknown, a transaction may have been sent, and the payment may have settled or may still settle | Sign a new payment, unless the message says the outcome is unknown: then check with the merchant first |
+| `SWAP_PRICE_MOVED` | 402 | The Parallelizer refused the swap: its price or fee moved, between signing and settlement, beyond the margin signed with the payment. The payment was not taken, and the facilitator will not settle it | Sign a new payment |
+| `SWAP_UNAVAILABLE` | 503 | The Parallelizer refused the swap because it cannot make it now: the swap closed since the facilitator checked it, a cap or a maximum fee is reached, the amount exceeds what it can release, or a price feed is stale. The payment was not taken, and the facilitator will not settle it | Pay with another token, or later with a new payment |
+| `SUBMISSION_FAILED` | 500 | The settle failed. When the message says the outcome is unknown, a transaction may have been sent, or the facilitator could not read whether the authorization was used, and the payment may have settled or may still settle | Do not sign another payment before checking with the merchant. x402-fetch says so for this reason whatever the message. A client that reads the 402 itself may sign a new payment when the message says no transaction was submitted |
 | `RECEIPT_UNAVAILABLE` | 500 | The transaction was sent but its confirmation could not be read | Do not sign another payment before checking with the merchant |
 | `INVALID_PAYLOAD`, `NETWORK_MISMATCH`, `PAYMENT_METHOD_NOT_SUPPORTED` | 400 | The settle request does not match the payment that was verified, or a metered amount is missing, malformed or above the signed cap. Nothing was settled | Sign a new payment |
 | `INSUFFICIENT_AMOUNT` | 402 | A metered amount of zero, or an authorization for zero. Nothing was settled | Sign a new payment |
 
-Reasons from this SDK: `SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE` and `FACILITATOR_INVALID_RESPONSE` (the settle may still have gone through, do not pay again before checking with the merchant), `AMOUNT_MISMATCH` (the facilitator settled another amount than the one asked, money moved, the response was not served, do not pay again before checking), `UNKNOWN` (anything that is not a code, such as the `Too Many Requests` of the facilitator's per-IP limit). For `SETTLE_IN_PROGRESS`, `RECEIPT_UNAVAILABLE`, `SETTLE_TOKEN_INVALID` and `SETTLE_TOKEN_REQUIRED` the message is this SDK's as well, since the facilitator's text addresses the merchant.
+Reasons from this SDK: `SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE` and `FACILITATOR_INVALID_RESPONSE` (the settle may still have gone through, do not pay again before checking with the merchant), `AMOUNT_MISMATCH` (the facilitator settled another amount than the one asked, money moved, the response was not served, do not pay again before checking), `UNKNOWN` (anything that is not a code, such as the `Too Many Requests` of the facilitator's per-IP limit: the payment may have settled, do not pay again before checking). For `SETTLE_IN_PROGRESS`, `RECEIPT_UNAVAILABLE`, `SETTLE_TOKEN_INVALID` and `SETTLE_TOKEN_REQUIRED` the message is this SDK's as well, since the facilitator's text addresses the merchant. The message is this SDK's too for `AUTHORIZATION_USED`, `PAYMENT_NOT_VERIFIED`, `PARALLELIZER_PAUSED`, `SAVINGS_PAUSED` and `SERVICE_UNAVAILABLE`: the payment may have settled or may still settle, so the message tells the agent to check with the merchant before paying again.
 
 `AMOUNT_MISMATCH` is also the one reason that points at the facilitator rather than at the request: it confirmed a settlement of another amount than the one the route asked for, so money moved. Alert on it, for example on 402 responses whose `reason` is `AMOUNT_MISMATCH`, rather than treating it as a routine refusal.
 
@@ -865,7 +875,7 @@ The facilitator counts the requests of each IP address that calls it, which is t
 | Limit | Facilitator answer | What the agent gets | What the agent should do |
 |-------|--------------------|---------------------|--------------------------|
 | Verifies per IP | 429 `{ error: "Too Many Requests", message }`, the message naming the time left in the minute (`Rate limit exceeded, retry in 42 seconds`, for instance), with `Retry-After` in seconds | 402 with a new invoice, `error: "FACILITATOR_INVALID_RESPONSE"`, the facilitator's message and its `Retry-After`. Nothing was verified | Send the payment again after `Retry-After` |
-| Settles per IP | The same 429 | 402 `{ error: "PAYMENT_SETTLEMENT_FAILED", reason: "UNKNOWN", message: "The payment could not be settled." }` with the facilitator's `Retry-After`. The handler's response is discarded, the settle is not retried, and nothing was settled | The agent cannot tell this `UNKNOWN` from another one, and x402-fetch reports that the payment may still settle: check with the merchant, then sign a new payment after `Retry-After` |
+| Settles per IP | The same 429 | 402 `{ error: "PAYMENT_SETTLEMENT_FAILED", reason: "UNKNOWN", message }` with the facilitator's `Retry-After`. The handler's response is discarded and the settle is not retried. This settle did nothing, but when the limit answers the SDK's retry of a settle that timed out, the first attempt may have settled | The message says the payment may have settled: check with the merchant, then sign a new payment after `Retry-After` |
 | Verifies per payer | 429 `RATE_LIMIT_EXCEEDED`, with `Retry-After` until the next UTC hour | 402 with a new invoice, `error: "RATE_LIMIT_EXCEEDED"`, the facilitator's message and its `Retry-After` | Pay again after `Retry-After` |
 
 The `error` of the per-IP answer is not a code, which is why the middleware reports `FACILITATOR_INVALID_RESPONSE` at verify and `UNKNOWN` at settle. A direct caller of `FacilitatorClient` sees it as it is: `verify` throws an `X402RuntimeError` whose `.code` is `"Too Many Requests"`, with `.status` 429 and `.retryAfter`, and `settle` returns it as a failure with the same code.

package/dist/{chunk-GXPUE3ES.js → chunk-G7HSURPM.js}

@@ -1,5 +1,5 @@
 import { X402_ERROR_CODES, X402ConfigError, X402RuntimeError, isPriceRejection } from './chunk-QAECRSWF.js';
-import { getTokenDecimals as getTokenDecimals$1 } from '@parallel-protocol/chains';
+import { isKnownChain, isActiveParallelizerChain, ACTIVE_PARALLELIZER_CHAINS, getTokenDecimals as getTokenDecimals$1 } from '@parallel-protocol/chains';
 import { z } from 'zod';
 
 var PARALLEL_TOKENS = {
@@ -155,6 +155,12 @@ var routeConfigSchema = z.object({
     "meter must be a function of the response"
   ).optional()
 }).refine(
+  (route) => !isKnownChain(route.network) || isActiveParallelizerChain(route.network),
+  {
+    message: `network must be one of the chains the facilitator settles on: ${ACTIVE_PARALLELIZER_CHAINS.join(", ")}`,
+    path: ["network"]
+  }
+).refine(
   (route) => route.meter === void 0 || route.scheme === "upto",
   "meter only applies to upto routes"
 ).refine(
@@ -325,14 +331,16 @@ var FacilitatorClient = class {
       throwIfRedirect(response);
       if (!response.ok) {
         const body = await readErrorBody(response);
-        if (body.error === void 0 && response.status >= 500) {
-          throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+        if (body.error === void 0) {
+          throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
+            status: response.status
+          });
         }
         const retryAfter = retryAfterOf(response);
         return {
           success: false,
           error: {
-            code: body.error ?? "SUBMISSION_FAILED",
+            code: body.error,
             message: body.message ?? "Settlement failed",
             status: response.status,
             ...retryAfter !== void 0 && { retryAfter }
@@ -772,8 +780,9 @@ function createPaymentGate(config) {
     };
   };
 }
-var UNKNOWN_SETTLEMENT_MESSAGE = "The payment could not be settled.";
+var DEFAULT_SETTLEMENT_MESSAGE = "The payment could not be settled.";
 var MERCHANT_SETTLEMENT_MESSAGE = "The merchant could not complete the settlement of this payment. The payment was not taken: do not sign another payment for this request before checking with the merchant.";
+var UNAVAILABLE_SETTLEMENT_MESSAGE = "The facilitator could not settle the payment for now. It may still settle until its authorization expires, or an earlier attempt may already have settled it: do not sign another payment for this request before checking with the merchant.";
 var AGENT_MESSAGES = {
   [X402_ERROR_CODES.SETTLE_TIMEOUT]: "The facilitator did not confirm the settlement in time. The payment may still settle: do not sign another payment for this request before checking with the merchant.",
   [X402_ERROR_CODES.FACILITATOR_UNAVAILABLE]: "The facilitator could not be reached to settle the payment. It may still have settled: do not sign another payment for this request before checking with the merchant.",
@@ -782,15 +791,20 @@ var AGENT_MESSAGES = {
   RECEIPT_UNAVAILABLE: "The facilitator sent the transaction but could not read its confirmation. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
   SETTLE_TOKEN_INVALID: MERCHANT_SETTLEMENT_MESSAGE,
   SETTLE_TOKEN_REQUIRED: MERCHANT_SETTLEMENT_MESSAGE,
+  AUTHORIZATION_USED: "The payment's authorization was already consumed or cancelled on-chain. It may have paid the merchant: do not sign another payment for this request before checking with the merchant.",
+  PAYMENT_NOT_VERIFIED: "The facilitator holds no payment it can settle for this request. An earlier attempt may have paid the merchant, or may still settle: do not sign another payment for this request before checking with the merchant.",
+  PARALLELIZER_PAUSED: UNAVAILABLE_SETTLEMENT_MESSAGE,
+  SAVINGS_PAUSED: UNAVAILABLE_SETTLEMENT_MESSAGE,
+  SERVICE_UNAVAILABLE: UNAVAILABLE_SETTLEMENT_MESSAGE,
   AMOUNT_MISMATCH: "The facilitator settled a different amount than this request asked for. The response was not served: do not sign another payment for this request before checking with the merchant.",
-  UNKNOWN: UNKNOWN_SETTLEMENT_MESSAGE
+  UNKNOWN: "The facilitator gave no reason for this failure, and the payment may have settled: do not sign another payment for this request before checking with the merchant."
 };
 function settlementFailure(code, failure) {
   const reason = shapedCode(code) ?? "UNKNOWN";
   return {
     settled: false,
     reason,
-    message: AGENT_MESSAGES[reason] ?? boundedMessage(failure?.message) ?? UNKNOWN_SETTLEMENT_MESSAGE,
+    message: AGENT_MESSAGES[reason] ?? boundedMessage(failure?.message) ?? DEFAULT_SETTLEMENT_MESSAGE,
     ...failure?.retryAfter !== void 0 && {
       retryAfter: failure.retryAfter
     }

package/dist/{chunk-SNW5Z5HB.cjs → chunk-TH77IB3T.cjs}

@@ -157,6 +157,12 @@ var routeConfigSchema = zod.z.object({
     "meter must be a function of the response"
   ).optional()
 }).refine(
+  (route) => !chains.isKnownChain(route.network) || chains.isActiveParallelizerChain(route.network),
+  {
+    message: `network must be one of the chains the facilitator settles on: ${chains.ACTIVE_PARALLELIZER_CHAINS.join(", ")}`,
+    path: ["network"]
+  }
+).refine(
   (route) => route.meter === void 0 || route.scheme === "upto",
   "meter only applies to upto routes"
 ).refine(
@@ -327,14 +333,16 @@ var FacilitatorClient = class {
       throwIfRedirect(response);
       if (!response.ok) {
         const body = await readErrorBody(response);
-        if (body.error === void 0 && response.status >= 500) {
-          throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+        if (body.error === void 0) {
+          throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
+            status: response.status
+          });
         }
         const retryAfter = retryAfterOf(response);
         return {
           success: false,
           error: {
-            code: body.error ?? "SUBMISSION_FAILED",
+            code: body.error,
             message: body.message ?? "Settlement failed",
             status: response.status,
             ...retryAfter !== void 0 && { retryAfter }
@@ -774,8 +782,9 @@ function createPaymentGate(config) {
     };
   };
 }
-var UNKNOWN_SETTLEMENT_MESSAGE = "The payment could not be settled.";
+var DEFAULT_SETTLEMENT_MESSAGE = "The payment could not be settled.";
 var MERCHANT_SETTLEMENT_MESSAGE = "The merchant could not complete the settlement of this payment. The payment was not taken: do not sign another payment for this request before checking with the merchant.";
+var UNAVAILABLE_SETTLEMENT_MESSAGE = "The facilitator could not settle the payment for now. It may still settle until its authorization expires, or an earlier attempt may already have settled it: do not sign another payment for this request before checking with the merchant.";
 var AGENT_MESSAGES = {
   [chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT]: "The facilitator did not confirm the settlement in time. The payment may still settle: do not sign another payment for this request before checking with the merchant.",
   [chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE]: "The facilitator could not be reached to settle the payment. It may still have settled: do not sign another payment for this request before checking with the merchant.",
@@ -784,15 +793,20 @@ var AGENT_MESSAGES = {
   RECEIPT_UNAVAILABLE: "The facilitator sent the transaction but could not read its confirmation. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
   SETTLE_TOKEN_INVALID: MERCHANT_SETTLEMENT_MESSAGE,
   SETTLE_TOKEN_REQUIRED: MERCHANT_SETTLEMENT_MESSAGE,
+  AUTHORIZATION_USED: "The payment's authorization was already consumed or cancelled on-chain. It may have paid the merchant: do not sign another payment for this request before checking with the merchant.",
+  PAYMENT_NOT_VERIFIED: "The facilitator holds no payment it can settle for this request. An earlier attempt may have paid the merchant, or may still settle: do not sign another payment for this request before checking with the merchant.",
+  PARALLELIZER_PAUSED: UNAVAILABLE_SETTLEMENT_MESSAGE,
+  SAVINGS_PAUSED: UNAVAILABLE_SETTLEMENT_MESSAGE,
+  SERVICE_UNAVAILABLE: UNAVAILABLE_SETTLEMENT_MESSAGE,
   AMOUNT_MISMATCH: "The facilitator settled a different amount than this request asked for. The response was not served: do not sign another payment for this request before checking with the merchant.",
-  UNKNOWN: UNKNOWN_SETTLEMENT_MESSAGE
+  UNKNOWN: "The facilitator gave no reason for this failure, and the payment may have settled: do not sign another payment for this request before checking with the merchant."
 };
 function settlementFailure(code, failure) {
   const reason = shapedCode(code) ?? "UNKNOWN";
   return {
     settled: false,
     reason,
-    message: AGENT_MESSAGES[reason] ?? boundedMessage(failure?.message) ?? UNKNOWN_SETTLEMENT_MESSAGE,
+    message: AGENT_MESSAGES[reason] ?? boundedMessage(failure?.message) ?? DEFAULT_SETTLEMENT_MESSAGE,
     ...failure?.retryAfter !== void 0 && {
       retryAfter: failure.retryAfter
     }

package/dist/express.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+var chunkTH77IB3T_cjs = require('./chunk-TH77IB3T.cjs');
 require('./chunk-KZZY5LS6.cjs');
 
 // src/express/adapter.ts
@@ -108,8 +108,8 @@ var ExpressAdapter = class {
       return originalEnd(...args);
     });
     next();
-    const outcome = await chunkSNW5Z5HB_cjs.raceTimeout(endPromise, options?.timeoutMs);
-    if (outcome === chunkSNW5Z5HB_cjs.HANDLER_TIMEOUT) {
+    const outcome = await chunkTH77IB3T_cjs.raceTimeout(endPromise, options?.timeoutMs);
+    if (outcome === chunkTH77IB3T_cjs.HANDLER_TIMEOUT) {
       discarded = true;
       return {
         status: 504,
@@ -146,7 +146,7 @@ var ExpressAdapter = class {
           const chunk = chunkBytes(args);
           if (chunk) bytes.push(chunk);
         }
-        return chunkSNW5Z5HB_cjs.parseJsonBody(
+        return chunkTH77IB3T_cjs.parseJsonBody(
           contentType,
           Buffer.concat(bytes).toString("utf8")
         );
@@ -170,7 +170,7 @@ var ExpressAdapter = class {
 
 // src/express/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkSNW5Z5HB_cjs.createPaymentMiddleware(config);
+  const middleware = chunkTH77IB3T_cjs.createPaymentMiddleware(config);
   return async (req, res, next) => {
     const result = await middleware(new ExpressAdapter(req, res, next));
     if ("pass" in result) {

package/dist/express.js

@@ -1,4 +1,4 @@
-import { raceTimeout, HANDLER_TIMEOUT, parseJsonBody, createPaymentMiddleware } from './chunk-GXPUE3ES.js';
+import { raceTimeout, HANDLER_TIMEOUT, parseJsonBody, createPaymentMiddleware } from './chunk-G7HSURPM.js';
 import './chunk-QAECRSWF.js';
 
 // src/express/adapter.ts

package/dist/fastify.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+var chunkTH77IB3T_cjs = require('./chunk-TH77IB3T.cjs');
 require('./chunk-KZZY5LS6.cjs');
 var fp = require('fastify-plugin');
 
@@ -37,7 +37,7 @@ var FastifyAdapter = class {
 // src/fastify/index.ts
 function payloadJson(contentType, payload) {
   const text = typeof payload === "string" ? payload : payload instanceof Uint8Array ? Buffer.from(payload).toString("utf8") : void 0;
-  return chunkSNW5Z5HB_cjs.parseJsonBody(contentType, text);
+  return chunkTH77IB3T_cjs.parseJsonBody(contentType, text);
 }
 function refuse(reply, result) {
   const json = JSON.stringify(result.body);
@@ -54,11 +54,11 @@ function headerValue(value) {
 }
 function paymentMiddleware(config) {
   return fp__default.default(async (fastify) => {
-    const gate = chunkSNW5Z5HB_cjs.createPaymentGate(config);
+    const gate = chunkTH77IB3T_cjs.createPaymentGate(config);
     const verifiedMap = /* @__PURE__ */ new WeakMap();
     const rawWriters = /* @__PURE__ */ new WeakMap();
     const needsBody = (req) => {
-      const route = chunkSNW5Z5HB_cjs.matchRoute(
+      const route = chunkTH77IB3T_cjs.matchRoute(
         new FastifyAdapter(req).getPath(),
         config.routes
       );
@@ -111,29 +111,29 @@ function paymentMiddleware(config) {
       if (!verified) return payload;
       let raw;
       if (verified.scheme === "upto") {
-        raw = headerValue(reply.getHeader(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER));
-        reply.removeHeader(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER);
+        raw = headerValue(reply.getHeader(chunkTH77IB3T_cjs.SETTLE_AMOUNT_HEADER));
+        reply.removeHeader(chunkTH77IB3T_cjs.SETTLE_AMOUNT_HEADER);
       }
       if (reply.statusCode < 200 || reply.statusCode >= 300) {
         return payload;
       }
       let settleOptions;
       if (verified.scheme === "upto") {
-        const resolved = await chunkSNW5Z5HB_cjs.resolveCharge(verified, raw, {
+        const resolved = await chunkTH77IB3T_cjs.resolveCharge(verified, raw, {
           status: reply.statusCode,
           header: (name) => headerValue(reply.getHeader(name)),
           body: async () => payloadJson(headerValue(reply.getHeader("content-type")), payload)
         });
         if (resolved.kind === "invalid") {
-          return refuse(reply, chunkSNW5Z5HB_cjs.invalidSettleAmountResponse(resolved.reason));
+          return refuse(reply, chunkTH77IB3T_cjs.invalidSettleAmountResponse(resolved.reason));
         }
         if (resolved.kind === "skip") return payload;
         settleOptions = { amount: resolved.amount };
       }
-      const outcome = await chunkSNW5Z5HB_cjs.settleVerified(verified, settleOptions);
+      const outcome = await chunkTH77IB3T_cjs.settleVerified(verified, settleOptions);
       if (!outcome.settled)
-        return refuse(reply, chunkSNW5Z5HB_cjs.settlementFailureResponse(outcome));
-      reply.header("payment-response", chunkSNW5Z5HB_cjs.encodeBase64(outcome.confirmation));
+        return refuse(reply, chunkTH77IB3T_cjs.settlementFailureResponse(outcome));
+      reply.header("payment-response", chunkTH77IB3T_cjs.encodeBase64(outcome.confirmation));
       reply.header("access-control-expose-headers", "payment-response");
       return payload;
     });

package/dist/fastify.js

@@ -1,4 +1,4 @@
-import { createPaymentGate, SETTLE_AMOUNT_HEADER, resolveCharge, invalidSettleAmountResponse, settleVerified, settlementFailureResponse, encodeBase64, matchRoute, parseJsonBody } from './chunk-GXPUE3ES.js';
+import { createPaymentGate, SETTLE_AMOUNT_HEADER, resolveCharge, invalidSettleAmountResponse, settleVerified, settlementFailureResponse, encodeBase64, matchRoute, parseJsonBody } from './chunk-G7HSURPM.js';
 import './chunk-QAECRSWF.js';
 import fp from 'fastify-plugin';
 

package/dist/hono.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+var chunkTH77IB3T_cjs = require('./chunk-TH77IB3T.cjs');
 require('./chunk-KZZY5LS6.cjs');
 
 // src/hono/adapter.ts
@@ -30,7 +30,7 @@ var HonoAdapter = class {
   // Hono caches the parsed body on the request, so the handler can still read
   // it after the price function did.
   async getBody() {
-    if (!chunkSNW5Z5HB_cjs.isJsonContentType(this.c.req.header("content-type"))) return void 0;
+    if (!chunkTH77IB3T_cjs.isJsonContentType(this.c.req.header("content-type"))) return void 0;
     try {
       return await this.c.req.json();
     } catch {
@@ -38,8 +38,8 @@ var HonoAdapter = class {
     }
   }
   async runHandler(options) {
-    const outcome = await chunkSNW5Z5HB_cjs.raceTimeout(this.next(), options?.timeoutMs);
-    if (outcome === chunkSNW5Z5HB_cjs.HANDLER_TIMEOUT) {
+    const outcome = await chunkTH77IB3T_cjs.raceTimeout(this.next(), options?.timeoutMs);
+    if (outcome === chunkTH77IB3T_cjs.HANDLER_TIMEOUT) {
       return {
         status: 504,
         setResponseHeader: () => {
@@ -64,7 +64,7 @@ var HonoAdapter = class {
       getResponseHeader: (name) => res.headers.get(name) ?? void 0,
       removeResponseHeader: (name) => res.headers.delete(name),
       // Read from a clone: the response body streams once, to the client.
-      getResponseBody: () => chunkSNW5Z5HB_cjs.jsonFromResponse(res),
+      getResponseBody: () => chunkTH77IB3T_cjs.jsonFromResponse(res),
       sendResponse: () => {
       },
       // The response is replaced: release its body (and whatever upstream
@@ -79,7 +79,7 @@ var HonoAdapter = class {
 
 // src/hono/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkSNW5Z5HB_cjs.createPaymentMiddleware(config);
+  const middleware = chunkTH77IB3T_cjs.createPaymentMiddleware(config);
   return async (c, next) => {
     const result = await middleware(new HonoAdapter(c, next));
     if ("pass" in result) {

package/dist/hono.js

@@ -1,4 +1,4 @@
-import { isJsonContentType, raceTimeout, HANDLER_TIMEOUT, jsonFromResponse, createPaymentMiddleware } from './chunk-GXPUE3ES.js';
+import { isJsonContentType, raceTimeout, HANDLER_TIMEOUT, jsonFromResponse, createPaymentMiddleware } from './chunk-G7HSURPM.js';
 import './chunk-QAECRSWF.js';
 
 // src/hono/adapter.ts

package/dist/index.cjs

@@ -1,65 +1,65 @@
 'use strict';
 
-var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+var chunkTH77IB3T_cjs = require('./chunk-TH77IB3T.cjs');
 var chunkKZZY5LS6_cjs = require('./chunk-KZZY5LS6.cjs');
 
 
 
 Object.defineProperty(exports, "FacilitatorClient", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.FacilitatorClient; }
+  get: function () { return chunkTH77IB3T_cjs.FacilitatorClient; }
 });
 Object.defineProperty(exports, "PARALLEL_TOKENS", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.PARALLEL_TOKENS; }
+  get: function () { return chunkTH77IB3T_cjs.PARALLEL_TOKENS; }
 });
 Object.defineProperty(exports, "SETTLE_AMOUNT_HEADER", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER; }
+  get: function () { return chunkTH77IB3T_cjs.SETTLE_AMOUNT_HEADER; }
 });
 Object.defineProperty(exports, "createPaymentGate", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.createPaymentGate; }
+  get: function () { return chunkTH77IB3T_cjs.createPaymentGate; }
 });
 Object.defineProperty(exports, "createPaymentMiddleware", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.createPaymentMiddleware; }
+  get: function () { return chunkTH77IB3T_cjs.createPaymentMiddleware; }
 });
 Object.defineProperty(exports, "encodeBase64", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.encodeBase64; }
+  get: function () { return chunkTH77IB3T_cjs.encodeBase64; }
 });
 Object.defineProperty(exports, "getDefaultAcceptedTokens", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.getDefaultAcceptedTokens; }
+  get: function () { return chunkTH77IB3T_cjs.getDefaultAcceptedTokens; }
 });
 Object.defineProperty(exports, "parsePrice", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.parsePrice; }
+  get: function () { return chunkTH77IB3T_cjs.parsePrice; }
 });
 Object.defineProperty(exports, "resolveCharge", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.resolveCharge; }
+  get: function () { return chunkTH77IB3T_cjs.resolveCharge; }
 });
 Object.defineProperty(exports, "resolveSettleAmount", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.resolveSettleAmount; }
+  get: function () { return chunkTH77IB3T_cjs.resolveSettleAmount; }
 });
 Object.defineProperty(exports, "settleVerified", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.settleVerified; }
+  get: function () { return chunkTH77IB3T_cjs.settleVerified; }
 });
 Object.defineProperty(exports, "settlementFailureResponse", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.settlementFailureResponse; }
+  get: function () { return chunkTH77IB3T_cjs.settlementFailureResponse; }
 });
 Object.defineProperty(exports, "toEip155Network", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.toEip155Network; }
+  get: function () { return chunkTH77IB3T_cjs.toEip155Network; }
 });
 Object.defineProperty(exports, "validateAddress", {
   enumerable: true,
-  get: function () { return chunkSNW5Z5HB_cjs.validateAddress; }
+  get: function () { return chunkTH77IB3T_cjs.validateAddress; }
 });
 Object.defineProperty(exports, "X402ConfigError", {
   enumerable: true,

package/dist/index.js

@@ -1,2 +1,2 @@
-export { FacilitatorClient, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveCharge, resolveSettleAmount, settleVerified, settlementFailureResponse, toEip155Network, validateAddress } from './chunk-GXPUE3ES.js';
+export { FacilitatorClient, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveCharge, resolveSettleAmount, settleVerified, settlementFailureResponse, toEip155Network, validateAddress } from './chunk-G7HSURPM.js';
 export { X402ConfigError, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, isPriceRejection } from './chunk-QAECRSWF.js';

package/dist/next.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+var chunkTH77IB3T_cjs = require('./chunk-TH77IB3T.cjs');
 require('./chunk-KZZY5LS6.cjs');
 var server = require('next/server');
 
@@ -25,7 +25,7 @@ var NextAdapter = class {
   // Read from a clone: a request body is a stream that can be consumed once,
   // and the handler still needs the original.
   async getBody() {
-    if (!chunkSNW5Z5HB_cjs.isJsonContentType(this.req.headers.get("content-type") ?? void 0))
+    if (!chunkTH77IB3T_cjs.isJsonContentType(this.req.headers.get("content-type") ?? void 0))
       return void 0;
     try {
       return await this.req.clone().json();
@@ -43,7 +43,7 @@ function fromResult(result) {
   });
 }
 function withPayment(config, handler) {
-  const gate = chunkSNW5Z5HB_cjs.createPaymentGate(config);
+  const gate = chunkTH77IB3T_cjs.createPaymentGate(config);
   return async (req) => {
     const gateResult = await gate(new NextAdapter(req));
     if (gateResult.type === "pass") {
@@ -52,11 +52,11 @@ function withPayment(config, handler) {
     if (gateResult.type === "error") return fromResult(gateResult.result);
     let response;
     try {
-      const outcome = await chunkSNW5Z5HB_cjs.raceTimeout(
+      const outcome = await chunkTH77IB3T_cjs.raceTimeout(
         handler(req),
         gateResult.handlerTimeoutMs
       );
-      if (outcome === chunkSNW5Z5HB_cjs.HANDLER_TIMEOUT) {
+      if (outcome === chunkTH77IB3T_cjs.HANDLER_TIMEOUT) {
         return new server.NextResponse(null, { status: 504 });
       }
       response = outcome;
@@ -65,10 +65,10 @@ function withPayment(config, handler) {
     }
     let raw;
     if (gateResult.scheme === "upto") {
-      raw = response.headers.get(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER) ?? void 0;
+      raw = response.headers.get(chunkTH77IB3T_cjs.SETTLE_AMOUNT_HEADER) ?? void 0;
       if (raw !== void 0) {
         const headers = new Headers(response.headers);
-        headers.delete(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER);
+        headers.delete(chunkTH77IB3T_cjs.SETTLE_AMOUNT_HEADER);
         response = new server.NextResponse(response.body, {
           status: response.status,
           headers
@@ -79,24 +79,24 @@ function withPayment(config, handler) {
       let settleOptions;
       if (gateResult.scheme === "upto") {
         const handled = response;
-        const resolved = await chunkSNW5Z5HB_cjs.resolveCharge(gateResult, raw, {
+        const resolved = await chunkTH77IB3T_cjs.resolveCharge(gateResult, raw, {
           status: handled.status,
           header: (name) => handled.headers.get(name) ?? void 0,
           // Read from a clone: the body streams once, to the client.
-          body: () => chunkSNW5Z5HB_cjs.jsonFromResponse(handled)
+          body: () => chunkTH77IB3T_cjs.jsonFromResponse(handled)
         });
         if (resolved.kind === "invalid") {
           handled.body?.cancel().catch(() => {
           });
-          return fromResult(chunkSNW5Z5HB_cjs.invalidSettleAmountResponse(resolved.reason));
+          return fromResult(chunkTH77IB3T_cjs.invalidSettleAmountResponse(resolved.reason));
         }
         if (resolved.kind === "skip") return response;
         settleOptions = { amount: resolved.amount };
       }
-      const outcome = await chunkSNW5Z5HB_cjs.settleVerified(gateResult, settleOptions);
+      const outcome = await chunkTH77IB3T_cjs.settleVerified(gateResult, settleOptions);
       if (outcome.settled) {
         const headers = new Headers(response.headers);
-        headers.set("payment-response", chunkSNW5Z5HB_cjs.encodeBase64(outcome.confirmation));
+        headers.set("payment-response", chunkTH77IB3T_cjs.encodeBase64(outcome.confirmation));
         headers.set("access-control-expose-headers", "payment-response");
         return new server.NextResponse(response.body, {
           status: response.status,
@@ -105,7 +105,7 @@ function withPayment(config, handler) {
       }
       response.body?.cancel().catch(() => {
       });
-      return fromResult(chunkSNW5Z5HB_cjs.settlementFailureResponse(outcome));
+      return fromResult(chunkTH77IB3T_cjs.settlementFailureResponse(outcome));
     }
     return response;
   };

package/dist/next.js

@@ -1,4 +1,4 @@
-import { isJsonContentType, createPaymentGate, raceTimeout, HANDLER_TIMEOUT, SETTLE_AMOUNT_HEADER, resolveCharge, jsonFromResponse, invalidSettleAmountResponse, settleVerified, encodeBase64, settlementFailureResponse } from './chunk-GXPUE3ES.js';
+import { isJsonContentType, createPaymentGate, raceTimeout, HANDLER_TIMEOUT, SETTLE_AMOUNT_HEADER, resolveCharge, jsonFromResponse, invalidSettleAmountResponse, settleVerified, encodeBase64, settlementFailureResponse } from './chunk-G7HSURPM.js';
 import './chunk-QAECRSWF.js';
 import { NextResponse } from 'next/server';
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parallel-protocol/x402",
-	"version": "0.8.1",
+	"version": "0.8.3",
 	"description": "Parallel Protocol x402 payment middleware — Express, Next.js, Fastify, Hono",
 	"author": "Parallel Protocol <contact@parallel.best>",
 	"repository": {
@@ -133,7 +133,7 @@
 		"vitest": "^4.0.14"
 	},
 	"dependencies": {
-		"@parallel-protocol/chains": "^0.5.0",
+		"@parallel-protocol/chains": "^0.5.1",
 		"fastify-plugin": "^6.0.0",
 		"zod": "^4.4.3"
 	},