@parallel-protocol/x402 0.7.1 → 0.8.0

package/README.md

@@ -24,11 +24,12 @@ Agent                        Merchant (this SDK)           Facilitator
   |                                |                             |
   |── GET /api/data ──────────────>|                             |
   |   payment-signature: <base64>  |── POST /x402/verify ───────>|
-  |                                |<─ { isValid: true } ────────|
+  |                                |<─ { isValid, settleToken } ─|
   |                                |                             |
   |                                | [handler runs]              |
   |                                |                             |
   |                                |── POST /x402/settle ───────>|
+  |                                |   (+ settleToken)           |
   |                                |<─ { txHash, route, ... } ───|
   |                                |                             |
   |<─ 200 + payment-response ──────|                             |
@@ -38,8 +39,10 @@ Agent                        Merchant (this SDK)           Facilitator
 **Key properties:**
 - 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.
-- If settlement fails (on-chain revert, facilitator timeout), the middleware returns `402` and discards the handler's response.
-- 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.)
+- 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.
+- 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.
 - CORS preflight (`OPTIONS`) is always passed through without challenge.
 
@@ -201,7 +204,7 @@ interface PaymentMiddlewareConfig {
 | `description` | `string` | No | Human-readable description of the resource, included in the 402 body. |
 | `scheme` | `"exact" \| "upto"` | No | `exact` (default) charges `price` as invoiced. `upto` invoices `price` as a **cap** the payer signs; the handler names the actual amount to charge and the rest is refunded on-chain — see [Metered routes](#metered-routes-upto). |
 | `meter` | `(ctx) => string \| bigint \| undefined` | No | `upto` routes only: reads the amount to charge from the handler's response, see [Reading the amount from the response](#reading-the-amount-from-the-response-meter). |
-| `maxTimeoutSeconds` | `number` | No | Settlement window the payer signs for (default 300). Metered routes announce how long their handler may take; the facilitator caps it at 3600 (one hour). Express, Hono and Next.js derive the handler timeout from it; Fastify does not time handlers out, set the server's `connectionTimeout` / `requestTimeout` yourself. |
+| `maxTimeoutSeconds` | `number` | No | Settlement window the payer signs for (default 300). Metered routes announce how long their handler may take; the facilitator caps it at 3600 (one hour). On metered routes, Express, Hono and Next.js derive the handler timeout from it, minus two minutes kept for the settlement and its retry: a 300 s window leaves the handler 180 s. Fastify does not time handlers out, set the server's `connectionTimeout` / `requestTimeout` yourself. |
 
 Route matching uses **longest prefix wins**: `/api/v1/users` will match a `/api/v1` route config before a `/api` one.
 
@@ -297,6 +300,7 @@ When no valid payment is present, the middleware returns HTTP 402 with a `paymen
 interface PaymentRequired {
   x402Version: 2;
   error?: string;           // present on re-challenge (e.g. "INVALID_SIGNATURE")
+  message?: string;         // the facilitator's text for `error`, when it sent one
   resource: {
     url: string;
     description?: string;
@@ -355,6 +359,7 @@ interface PaymentConfirmation {
   gasSponsored: boolean;
   networkId: string;    // "eip155:8453"
   amountSettled?: string;  // metered routes: what was actually charged (smallest unit)
+  alreadySettled?: true;   // the facilitator answered from a recorded outcome, this call broadcast nothing
 }
 ```
 
@@ -371,7 +376,7 @@ routes: {
   "/v1/chat/completions": {
     scheme: "upto",
     price: "2",                // the cap, in USDp
-    maxTimeoutSeconds: 600,    // the handler may take up to ~9 minutes
+    maxTimeoutSeconds: 600,    // the handler may take up to 8 minutes
     network: "base",
     payTo: "0xYourAddress",
   },
@@ -423,7 +428,7 @@ Instead of a header the handler sets, a route may carry a `meter` function that
 
 The response body is read only on routes that have a `meter` function, from a clone or from the buffered chunks the middleware already holds, so other routes are untouched. Reading it gets the handler's own time budget: a body that streams from a slow upstream and is not complete within the window is treated like a failing meter. Return a buffered body on metered routes. `meter` only applies to `upto` routes.
 
-Timing: the payer's authorization expires after `maxTimeoutSeconds`, and settlement needs a minute at most. On Express, Hono and Next.js the handler timeout is raised to `maxTimeoutSeconds − 60 s` for metered routes; Fastify handlers are never timed out by the middleware, so size the server's own `connectionTimeout` and `requestTimeout` to the window. A handler that finishes after the window is served but cannot be settled: the client gets 402 `PAYMENT_SETTLEMENT_FAILED` and the merchant has done the work for nothing — keep a margin.
+Timing: the payer's authorization expires after `maxTimeoutSeconds`, and settlement may take up to two minutes, an attempt of up to 60 s and one retry. On Express, Hono and Next.js the handler timeout is raised to `maxTimeoutSeconds − 120 s` for metered routes; Fastify handlers are never timed out by the middleware, so size the server's own `connectionTimeout` and `requestTimeout` to the window. A handler that finishes after the window is served but cannot be settled: the client gets 402 `PAYMENT_SETTLEMENT_FAILED` and the merchant has done the work for nothing — keep a margin.
 
 ---
 
@@ -689,7 +694,7 @@ if (result.type === "pass") {
 }
 ```
 
-`createPaymentGate` only verifies; it does not run the handler. Use `createPaymentMiddleware` if you want the full verify → run → settle flow managed automatically.
+`createPaymentGate` only verifies; it does not run the handler. Use `createPaymentMiddleware` if you want the full verify → run → settle flow managed automatically. The gate keeps the settle token the facilitator issued at verify and presents it in `result.settle()`, so a custom integration has nothing to carry. `settleVerified(result, options)` runs the same settlement the adapters use (one retry when the outcome is unknown, the settled amount checked on metered routes) and `settlementFailureResponse(outcome)` builds the 402 for a failed one.
 
 ---
 
@@ -711,21 +716,25 @@ const requirements: FacilitatorPaymentRequirements = {
   network: "base",                        // plain chain slug
 };
 
-// Phase 1: verify signature + reserve nonce (no on-chain tx)
-await client.verify(paymentHeader, requirements); // throws X402RuntimeError on failure
+// Phase 1: verify signature + reserve nonce (no on-chain tx). The facilitator
+// hands back the settle token this payment must be settled with.
+const { settleToken } = await client.verify(paymentHeader, requirements); // throws X402RuntimeError on failure
 
 // Phase 2: submit on-chain, return settlement result
-const result = await client.settle(paymentHeader, requirements);
+const result = await client.settle(paymentHeader, requirements, { settleToken });
 if (result.success) {
-  console.log(result.txHash);       // on-chain tx hash
-  console.log(result.route);        // "A", "B", ...
-  console.log(result.gasSponsored); // boolean
+  console.log(result.txHash);          // on-chain tx hash
+  console.log(result.route);           // "A", "B", ...
+  console.log(result.gasSponsored);    // boolean
+  console.log(result.alreadySettled);  // true when an earlier settle already did it
 } else {
-  console.error(result.error.code); // e.g. "SUBMISSION_FAILED"
+  console.error(result.error.code);    // e.g. "INSUFFICIENT_BALANCE"
+  console.error(result.error.message); // the facilitator's text
+  console.error(result.error.status);  // its HTTP status, result.error.retryAfter when it sent one
 }
 ```
 
-`verify` uses a 10-second timeout. `settle` uses a 60-second timeout to accommodate on-chain confirmation latency. `verify` throws on any failure; `settle` returns a `FacilitatorResponse` union on facilitator errors and throws `X402RuntimeError` on connectivity issues, an undecodable payment header, or a malformed facilitator response.
+`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` and its HTTP status in `.status`; a facilitator that issues no settle token is an invalid response. `settle` returns a `FacilitatorResponse` union on facilitator errors 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. 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.
 
 A single-call `client.pay(paymentHeader, requirements)` (`POST /x402/pay`) also exists — it verifies and settles in one round trip, without the two-phase guarantees the middleware relies on.
 
@@ -753,23 +762,47 @@ Refusals `chatCompletionCap` makes, all before payment:
 
 | `X402RuntimeError.code` | Meaning |
 |-------------------------|---------|
-| `FACILITATOR_UNAVAILABLE` | Facilitator timed out (10s on verify, 60s on settle) or was unreachable |
-| `FACILITATOR_INVALID_RESPONSE` | Facilitator returned an unexpected response shape |
+| `FACILITATOR_UNAVAILABLE` | Facilitator timed out on verify (10s) or was unreachable |
+| `SETTLE_TIMEOUT` | Facilitator did not answer a settle within 60s. The payment may still settle |
+| `FACILITATOR_INVALID_RESPONSE` | Facilitator returned an unexpected response shape, including a verify without a settle token |
 | `INVALID_PAYMENT` | `payment-signature` / `X-PAYMENT` header could not be base64-decoded |
 
 ### Propagated from the facilitator
 
-When the facilitator rejects a payment, its error code is forwarded as the `error` field on the re-issued 402 body. Common values:
+When the facilitator refuses a payment at verify, its code is forwarded as the `error` field on the re-issued 402 body and its text as `message`. Common values:
 
 | Code | Meaning |
 |------|---------|
+| `INVALID_PAYLOAD` | The payload does not have the shape of its route, or carries a field another route would read |
 | `INVALID_SIGNATURE` | EIP-712 signature recovery failed |
 | `INVALID_NONCE` | Nonce already used (replay detected) |
 | `PAYMENT_EXPIRED` | `validBefore` has passed |
-| `INSUFFICIENT_AMOUNT` | Signed amount < required amount |
+| `INSUFFICIENT_AMOUNT` | The amount the route guarantees the merchant is below the price |
+| `INSUFFICIENT_BALANCE` | The payer does not hold the signed amount (metered payments) |
+| `ASSET_MISMATCH` | The route does not deliver the token the merchant requires |
+| `RECIPIENT_MISMATCH` | The signed recipient is not the merchant's `payTo` |
 | `NETWORK_MISMATCH` | Payload chain ≠ route config chain |
+| `WINDOW_TOO_LONG` | A metered authorization valid for longer than the facilitator allows |
+| `PAYMENT_METHOD_NOT_SUPPORTED` | No route for this method or token on this chain |
 | `RATE_LIMIT_EXCEEDED` | Signer has exceeded the hourly transaction limit |
-| `PARALLELIZER_PAUSED` | On-chain router temporarily paused (swap routes only) |
+
+When the facilitator refuses at settle, the 402 body is `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }`, with the facilitator's `Retry-After` header copied when it sent one. `reason` values from the facilitator:
+
+| Reason | Meaning | What the agent should do |
+|--------|---------|--------------------------|
+| `INSUFFICIENT_BALANCE` | The payer no longer holds the signed amount | Fund the wallet, sign a new payment |
+| `AUTHORIZATION_USED` | The authorization nonce is consumed or cancelled on-chain, this facilitator did not settle it | Sign a new payment |
+| `PAYMENT_EXPIRED` | The authorization expired before settlement | Sign a new payment |
+| `PAYMENT_NOT_VERIFIED` | No verified payment for this authorization, or it already failed | Sign a new payment |
+| `SETTLE_IN_PROGRESS` | 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` | 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` | The facilitator or the chain is temporarily unable to settle | Retry later with a new payment, after `Retry-After` when given |
+| `TX_REVERTED`, `SUBMISSION_FAILED` | The chain refused for a reason the facilitator could not attribute | Sign a new payment |
+| `RECEIPT_UNAVAILABLE` | The transaction was sent but its confirmation could not be read | Do not sign another payment before checking with 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). 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.
+
+`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.
 
 ---
 

package/dist/{chunk-JPMK5YBU.cjs → chunk-KZZY5LS6.cjs}

@@ -4,7 +4,9 @@
 var X402_ERROR_CODES = {
   FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
   FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
-  INVALID_PAYMENT: "INVALID_PAYMENT"
+  INVALID_PAYMENT: "INVALID_PAYMENT",
+  /** The facilitator did not answer a settle within the client's timeout: the payment may still settle. */
+  SETTLE_TIMEOUT: "SETTLE_TIMEOUT"
 };
 var X402ConfigError = class extends Error {
   constructor(message, cause) {
@@ -14,12 +16,21 @@ var X402ConfigError = class extends Error {
   }
 };
 var X402RuntimeError = class extends Error {
-  constructor(code) {
+  constructor(code, extra) {
     super(code);
     this.code = code;
     this.name = "X402RuntimeError";
+    if (extra?.detail !== void 0) this.detail = extra.detail;
+    if (extra?.status !== void 0) this.status = extra.status;
+    if (extra?.retryAfter !== void 0) this.retryAfter = extra.retryAfter;
   }
   code;
+  /** The facilitator's message for this code, when it answered with one. */
+  detail;
+  /** The facilitator's HTTP status, when the error comes from its answer. */
+  status;
+  /** The facilitator's `Retry-After` header, when it sent one. */
+  retryAfter;
 };
 var X402PriceRejectedError = class extends Error {
   constructor(code, message, status = 400) {