@parallel-protocol/x402 0.7.1 → 0.8.1

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.
 
@@ -101,9 +104,10 @@ app.get("/api/data", (req, res) => {
 ```typescript
 // app/api/data/route.ts
 import { NextResponse } from "next/server";
+import type { PaymentMiddlewareConfig } from "@parallel-protocol/x402";
 import { withPayment } from "@parallel-protocol/x402/next";
 
-const config = {
+const config: PaymentMiddlewareConfig = {
   facilitator: { url: "https://agents.parallel.best" },
   routes: {
     "/api/data": {
@@ -186,7 +190,7 @@ interface PaymentMiddlewareConfig {
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `url` | `string` | Yes | Base URL of the Parallel facilitator (e.g. `https://agents.parallel.best`). The SDK internally appends `/x402/verify` and `/x402/settle` to this value. |
+| `url` | `string` | Yes | Base URL of the Parallel facilitator (e.g. `https://agents.parallel.best`). The SDK internally appends `/x402/verify` and `/x402/settle` to this value. It must use https: plain http is accepted only for `localhost`, `127.0.0.1` and `[::1]`. A trailing slash is ignored. The SDK calls this address only and never follows a redirect, which fails the call with `FACILITATOR_UNAVAILABLE`. |
 | `apiKey` | `string` | No | Optional API key, sent as the `X-API-Key` header on facilitator requests. |
 
 ### `RouteConfig`
@@ -194,14 +198,14 @@ interface PaymentMiddlewareConfig {
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `price` | `string \| bigint \| (ctx) => string \| bigint` | Yes | Amount required. A string like `"0.01"` is parsed with each accepted token's own decimals (or with `decimals` when set explicitly). Pass a `bigint` to skip parsing. A function prices each request from its content, see [Per-request pricing](#per-request-pricing). |
-| `decimals` | `number` | No | Override for the decimals used to parse a string price. By default each accepted token is priced with its own decimals from the `@parallel-protocol/chains` catalog — a `"0.01"` price is correct whether paid in USDp (18) or USDC (6), no configuration. Only needed for a custom token outside the catalog; without it, an unknown token raises `X402ConfigError` rather than being silently guessed. |
+| `decimals` | `number` | No | Override for the decimals used to parse a string price. By default each accepted token is priced with its own decimals from the `@parallel-protocol/chains` catalog, so a `"0.01"` price is correct whether paid in USDp (18) or USDC (6), with no configuration. Only needed for a custom token outside the catalog: without it, an unknown token raises `X402ConfigError` rather than being silently guessed. When set, it applies to every token of the route. |
 | `network` | `string` | Yes | Chain slug: `"ethereum"`, `"base"`, `"avalanche"`, `"hyperevm"`. |
 | `payTo` | `Address` | Yes | The merchant's receiving address. |
 | `acceptedTokens` | `Address[]` | No | List of accepted token addresses. Defaults to `[USDp, USDC, sUSDp]` for known networks (see [Default tokens](#default-tokens)). On an `upto` route it defaults to USDp alone, and any other token is rejected at construction: metered payments are USDp only. |
 | `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 announced to the payer (default 300). `@parallel-protocol/x402-fetch` signs for it on `upto` routes, and for five minutes on `exact` routes. Metered routes announce how long their handler may take. On an `upto` route it is 3600 (one hour) at most: a larger value raises `X402ConfigError` at construction, and the facilitator refuses an authorization valid for longer with `WINDOW_TOO_LONG`. 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, and a handler always gets at least 30 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.
 
@@ -218,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 25-chain catalog), you must provide `acceptedTokens` explicitly — the middleware throws `X402ConfigError` on the first request to that route otherwise.
+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.
 
 You can also import the token list directly:
 
@@ -232,7 +236,7 @@ const defaults = getDefaultAcceptedTokens("base");
 // ["0x76A9...", "0x8335...", "0x472e..."]  (USDp + USDC + sUSDp)
 ```
 
-**sUSDp** is included in the defaults (routes H, I, J, K, L are enabled out of the box). To opt out and accept only USDp and USDC, pass `acceptedTokens` explicitly:
+**sUSDp** is included in the defaults, so the merchant can be paid in sUSDp: routes C, G and J deliver it. Routes H, I, K and L, where the agent pays with sUSDp, deliver USDp, USDC or a collateral and do not need it. To opt out and accept only USDp and USDC, pass `acceptedTokens` explicitly:
 
 ```typescript
 import { PARALLEL_TOKENS } from "@parallel-protocol/x402";
@@ -245,7 +249,7 @@ routes: {
     acceptedTokens: [
       PARALLEL_TOKENS.base.usdp,
       PARALLEL_TOKENS.base.usdc,
-      // sUSDp omitted → routes H, I, J, K, L disabled for this route
+      // sUSDp omitted: routes C, G and J disabled for this route
     ],
   },
 }
@@ -276,14 +280,14 @@ routes: {
     acceptedTokens: [
       PARALLEL_TOKENS.ethereum.usdp,
       PARALLEL_TOKENS.ethereum.usdc,
-      PARALLEL_TOKENS.ethereum.sUSDe,   // opt-in → agents can pay with sUSDe
-      PARALLEL_TOKENS.ethereum.sfrxUSD, // opt-in → agents can pay with sfrxUSD
+      PARALLEL_TOKENS.ethereum.sUSDe,   // opt-in: the merchant can be paid in sUSDe
+      PARALLEL_TOKENS.ethereum.sfrxUSD, // opt-in: the merchant can be paid in sfrxUSD
     ],
   },
 }
 ```
 
-> Note: the facilitator validates that `tokenOut` is a whitelisted collateral on the target chain. If you add an address that is not in the Parallelizer's collateral list, payments to that route will be rejected at settlement.
+> Note: the facilitator only delivers the chain's USDp, sUSDp and USDC and the collaterals in the table above. A payment that would deliver any other token is refused at verify, before the handler runs: a swap to such a token gets `COLLATERAL_NOT_SUPPORTED`. Listing such a token in `acceptedTokens` invites payments the facilitator refuses.
 
 ---
 
@@ -297,6 +301,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;
@@ -322,7 +327,7 @@ The agent attaches a `payment-signature` (or `X-PAYMENT`) header with a **base64
 // Minimal Route A payload (USDp transfer)
 const signedPayload = {
   scheme: "exact",
-  network: "base",
+  network: "base",                 // the chain slug, not the eip155 form of the 402
   method: "transferWithAuthorization",
   payload: {
     signature: "0x...",
@@ -355,6 +360,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
 }
 ```
 
@@ -364,14 +370,14 @@ The `access-control-expose-headers` header is set automatically so browsers can
 
 ## Metered routes (`upto`)
 
-Some resources only know their cost after the work is done — an LLM completion is priced by the tokens it generates. A route declared with `scheme: "upto"` invoices `price` as a **cap**: the payer signs an authorization for that cap, the handler serves the request and names the amount it actually charges, and the facilitator settles that amount through Parallel's escrow contract, refunding the remainder to the payer in the same transaction. Metered payments are made in USDp: `acceptedTokens` defaults to the network's USDp and may not list any other token.
+Some resources only know their cost after the work is done: an LLM completion is priced by the tokens it generates. A route declared with `scheme: "upto"` invoices `price` as a **cap**: the payer signs an authorization for that cap, the handler serves the request and names the amount it actually charges, and the facilitator settles that amount through Parallel's escrow contract, refunding the remainder to the payer in the same transaction. Metered payments are made in USDp: `acceptedTokens` defaults to the network's USDp and may not list any other token. They settle only on chains where the escrow is deployed, which today is Base alone (`UPTO_CHAINS` in `@parallel-protocol/chains`). On another chain the facilitator refuses the payment at verify with `PAYMENT_METHOD_NOT_SUPPORTED`.
 
 ```typescript
 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",
   },
@@ -390,7 +396,7 @@ fastify.post("/v1/chat/completions", async (request, reply) => {
 });
 ```
 
-The middleware strips the header before the response leaves, whatever the status code: a handler that prices the request and then fails never tells the client what it was about to charge. The value must follow the same format as `price` (a plain decimal such as `"0.0137"`, no leading zeros on the integer part, no exponent, no unit) and must not carry more decimals than the token has. Rules on a `2xx` response:
+The middleware strips the header before the response leaves, whatever the status code: a handler that prices the request and then fails never tells the client what it was about to charge. The value must follow the same format as `price` (a plain decimal such as `"0.0137"`: digits with an optional fractional part, no sign, no exponent, no unit) and must not carry more decimals than the token has. Rules on a `2xx` response:
 
 | Header value | What happens |
 |---|---|
@@ -423,7 +429,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 has done the work, but the payment can no longer settle: the client gets 402 `PAYMENT_SETTLEMENT_FAILED` with reason `PAYMENT_EXPIRED`, and the merchant is not paid. Keep a margin.
 
 ---
 
@@ -456,7 +462,7 @@ The function gets `{ method, path, url, header(name), body }`. `body` is the req
 
 The function runs twice per paid request: on the unpaid request, to build the 402, and on the paid retry, to size what the facilitator verifies. It must therefore be **pure**: same request, same price, no clock and no randomness. A retry whose body changed in between is priced again, and refused by the facilitator if the signed amount no longer covers the new price. It may be `async`.
 
-A function that throws or returns something that is not a price is a merchant bug: the request fails with `X402ConfigError` rather than being served for free or mispriced. To refuse a request the route will not serve (an unsupported option, a resource that does not exist) throw `X402PriceRejectedError(code, message, status = 400)` instead: the client gets that status with `{ error: code, message }`, and nothing is invoiced or signed.
+A function that throws or returns something that is not a price is a merchant bug: the request fails with `X402ConfigError` rather than being served for free or mispriced. To refuse a request the route will not serve (an unsupported option, a resource that does not exist) throw `X402PriceRejectedError(code, message, status = 400)` instead: the client gets that status with `{ error: code, message }`, and nothing is invoiced or signed. A status outside 400 to 599 is sent as 400.
 
 ---
 
@@ -502,13 +508,13 @@ app.post("/v1/chat/completions", async (request, reply) => {
 });
 ```
 
-The same handler on the other frameworks: Express `res.status(upstream.status).json(upstream.body)`, Hono `c.json(upstream.body, upstream.status)`, Next.js `NextResponse.json(upstream.body, { status: upstream.status })`.
+The same handler on the other frameworks: Express `res.status(upstream.status).json(upstream.body)`, Hono `c.json(upstream.body, upstream.status as ContentfulStatusCode)` (the type comes from `hono/utils/http-status`), Next.js `NextResponse.json(upstream.body, { status: upstream.status })`.
 
-`forwardChatCompletion(body, { baseUrl, apiKey, maxOutputTokens, outputTokensField, timeout, headers, fetch, fields })` posts to `${baseUrl}/chat/completions` with only the fields the cap accounts for (`FORWARDED_FIELDS`: model, messages, tools, sampling parameters, reasoning options), `stream: false` and the completion bounded by `maxOutputTokens` (sent as `max_tokens`, or `max_completion_tokens` for providers that want it; a `reasoning.max_tokens` budget is bounded the same way), and returns the provider's `{ status, body }`: a 2xx and the statuses about the client's request (400, 404, 413, 422, 429 and the like) are handed back as they are, so nothing is settled on an error; a status about the merchant's account with the provider (401, 402, 403, 5xx) is folded into 502 `UPSTREAM_ERROR` with a fixed body, so the client never sees the merchant's provider details; a provider that cannot be reached answers 502 `UPSTREAM_UNAVAILABLE`, a timeout 504 `UPSTREAM_TIMEOUT` (five minutes by default).
+`forwardChatCompletion(body, { baseUrl, apiKey, maxOutputTokens, outputTokensField, timeout, headers, fetch, fields })` posts to `${baseUrl}/chat/completions` with only the fields the cap accounts for (`FORWARDED_FIELDS`: model, messages, tools and tool choice, response format, sampling parameters and penalties, stop sequences, seed, reasoning options, parallel tool calls, logit bias and `user`), `stream: false`, and the completion bounded by `maxOutputTokens`. The bound is sent as `max_tokens`, or as `max_completion_tokens` for providers that want it, and a `reasoning.max_tokens` budget is bounded the same way. It returns the provider's `{ status, body }`. A 2xx and the statuses about the client's request (400, 404, 405, 408, 409, 413, 415, 422 and 429) are handed back as they are, so nothing is settled on an error. Any other status, such as a 401, 402, 403 or 5xx about the merchant's account with the provider, is folded into 502 `UPSTREAM_ERROR` with a fixed body, so the client never sees the merchant's provider details. A provider that cannot be reached answers 502 `UPSTREAM_UNAVAILABLE`, and a timeout 504 `UPSTREAM_TIMEOUT` (five minutes by default).
 
 `chatCompletionMeter({ prices? })` reads the amount from the response: `usage.cost` in dollars when the provider reports one (OpenRouter does), otherwise `usage.prompt_tokens` and `usage.completion_tokens` at the model's prices when `prices` is given, otherwise nothing, which charges the cap. So a provider that reports no cost (DeepSeek, most direct APIs) needs the same `prices` as the cap, or every request settles at the cap with nothing refunded and no error to show it. A zero cost serves the request for free. Cached input tokens are charged at the full input price in the token-count path.
 
-The cap of a request is a bound on its input tokens at the model's input price, plus the largest completion the request may produce (`max_tokens`, bounded by `maxOutputTokens`, which also stands in for it when absent) at its output price. One USDp per dollar. The cap must cover the real count whichever tokenizer the provider uses, or the response is refused and the merchant has paid the provider for nothing, so the built-in bound counts one token per UTF-8 byte of the messages and tools, which no tokenizer exceeds. English prose runs at about four characters per token, so the cap is loose there: the payer only pays the provider's real count and the rest is refunded. A merchant who wants a tighter cap plugs a real tokenizer through `estimateInputTokens`.
+The cap of a request is a bound on its input tokens at the model's input price, plus the largest completion the request may produce (`max_tokens` or `max_completion_tokens`, bounded by `maxOutputTokens`, which also stands in for it when absent) at its output price. One USDp per dollar. The cap must cover the real count whichever tokenizer the provider uses, or the response is refused and the merchant has paid the provider for nothing, so the built-in bound counts one token per UTF-8 byte of the messages and tools, which no tokenizer exceeds. English prose runs at about four characters per token, so the cap is loose there: the payer only pays the provider's real count and the rest is refunded. A merchant who wants a tighter cap plugs a real tokenizer through `estimateInputTokens`.
 
 | Option | Default | Description |
 |--------|---------|-------------|
@@ -523,7 +529,7 @@ A handler that does not use `forwardChatCompletion` should still forward only th
 
 `openRouterPrices({ ttl: "24h", timeout: "10s" })` loads the public models listing (no API key) on first use, serves it from memory and refreshes it in the background once older than `ttl`, so no request waits for OpenRouter after the first one; a load is abandoned after `timeout`, a refresh that fails keeps the current list, and a failed load is not retried for five seconds. With no list at all, requests are refused with a 503 `PRICING_UNAVAILABLE`. A model the list does not know may have been released since the list was loaded: once the list is more than five minutes old, such a request refreshes it in the background and is refused with an `UNKNOWN_MODEL` message that says so, and the next request finds the model. A fixed table never touches the network: `prices: { "deepseek-flash": { input: 0.30, output: 1.20 } }`.
 
-Requests the route cannot meter are refused before anything is invoiced, with a 400 and a JSON body: an unknown model (`UNKNOWN_MODEL`), a model outside `models` (`MODEL_NOT_ALLOWED`), more than one choice (`n`), non-text content, plugins, web search, image or audio output, or streaming (`UNSUPPORTED_OPTION`), a malformed body (`INVALID_REQUEST`). Live prices are the one accepted exception to the purity rule of price functions: a list refreshed between the unpaid request and the paid retry may re-price the retry, which is then refused and re-invoiced.
+Requests the route cannot meter are refused before anything is invoiced, with a 400 and a JSON body: an unknown model (`UNKNOWN_MODEL`), a model outside `models` (`MODEL_NOT_ALLOWED`), more than one choice (`n`), non-text content, plugins, web search, image or audio output, or streaming (`UNSUPPORTED_OPTION`), a malformed body (`INVALID_REQUEST`). Live prices are the one accepted exception to the purity rule of price functions: a list refreshed between the unpaid request and the paid retry may re-price the retry. A retry priced above the amount the payer signed is refused and re-invoiced.
 
 Without `meter`, what is charged after the response is the handler's call: set the `payment-settle-amount` header to the provider's cost, see [Metered routes](#metered-routes-upto).
 
@@ -537,11 +543,11 @@ The facilitator supports 13 settlement routes. The route is selected automatical
 |-------|--------------------------|---------------------|------------------------------|----------|-------|
 | **A** | `transferWithAuthorization` | USDp | USDp | ~65K | Direct USDp transfer |
 | **B** | `swapExactOutputWithAuthorization` | USDp | USDC (exact) | ~120K | Parallelizer swaps agent's USDp → exact USDC for merchant |
-| **C** | `depositWithAuthorization` | USDp | sUSDp | ~90K | Agent's USDp deposited into savings vault; merchant receives sUSDp shares |
+| **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 (exact) | USDp (min) | ~120K | Agent pays exact USDC; Parallelizer delivers minimum USDp to merchant |
-| **F** | `transferWithAuthorization` | USDC (or any EIP-3009 token) | same token | ~65K | Direct EIP-3009 token push |
-| **G** | `swapExactInputWithAuthorization` | USDC (exact) | sUSDp | ~200K | USDC → USDp swap, then USDp deposited as sUSDp for merchant (atomic multicall3) |
+| **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) |
 | **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 |
@@ -551,9 +557,12 @@ 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 C, G, H, I, J, K, L require **sUSDp** (savings module) to be deployed on the target chain.
-- Route A and F work on all chains where the respective token is deployed.
+- 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.
+- 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.
 
 ---
 
@@ -568,7 +577,14 @@ import {
   createPaymentMiddleware,
   resolveCharge,
   resolveSettleAmount,
+  settleVerified,
+  settlementFailureResponse,
   SETTLE_AMOUNT_HEADER,
+  type ChargeResponse,
+  type SettleAmountResolution,
+  type SettlementFailure,
+  type SettlementFailureBody,
+  type SettlementOutcome,
 
   // Facilitator client
   FacilitatorClient,
@@ -588,7 +604,9 @@ import {
 
   // Types
   type FacilitatorConfig,
+  type FacilitatorPaymentRequirements,
   type FacilitatorResponse,
+  type FacilitatorSettleOptions,
   type HTTPAdapter,
   type MeterContext,
   type MeterFunction,
@@ -604,7 +622,11 @@ import {
   type PriceFunction,
   type ResourceInfo,
   type RouteConfig,
+  type RunHandlerOptions,
   type RunHandlerResult,
+  type SettleOptions,
+  type VerifiedPayment,
+  type VerifyResult,
 
   // Utils
   encodeBase64,
@@ -644,9 +666,11 @@ import {
   type ChatCompletionCapOptions,
   type ChatCompletionMeterOptions,
   type ChatCompletionBody,
+  type ChatMessage,
   type ForwardChatCompletionOptions,
   type ForwardedResponse,
   type ModelPrice,
+  type OpenRouterPricesOptions,
   type PriceSource,
   type PriceTable,
 } from "@parallel-protocol/x402/llm";
@@ -669,19 +693,21 @@ const result = await gate({
   getMethod: () => request.method,
   getPath:   () => request.path,
   getUrl:    () => request.url,
+  getBody:   async () => request.body, // optional: the parsed body, for price and meter functions
 });
 
 if (result.type === "pass") {
   // Route not configured for payment, proceed normally
 } else if (result.type === "error") {
-  // Send 402: result.result.status / result.result.headers / result.result.body
+  // Send result.result.status (402, or the status of a price refusal)
+  // with result.result.headers and result.result.body
 } else {
   // result.type === "verified"
   // Run your handler...
   const handlerStatus = await runHandler();
 
   if (handlerStatus >= 200 && handlerStatus < 300) {
-    const settlement = await result.settle();
+    const settlement = await result.settle(); // a metered route passes { amount }
     if (settlement.success) {
       // settlement.txHash / settlement.route / settlement.gasSponsored
     }
@@ -689,7 +715,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 whole flow (verify, run the handler, settle) 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. On a metered route, `result.settle({ amount })` takes the amount to charge in the token's smallest unit, which `resolveCharge` computes from the handler's response as the adapters do. `result.settle()` makes a single call and throws as [`FacilitatorClient.settle`](#facilitatorclient) does. `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,33 +737,49 @@ 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.
+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.
 
-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.
+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 }`.
 
 ---
 
 ## Error codes
 
+### Responses to the agent
+
+What the middleware answers on a paid route instead of the handler's response:
+
+| Status | Body | When |
+|--------|------|------|
+| 402 | `PaymentRequired`, with `error` and `message` when a payment was refused | No payment header, or the payment was refused at verify, see [Propagated from the facilitator](#propagated-from-the-facilitator) |
+| 402 | `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }` | The handler answered 2xx and the payment could not be settled. The handler's response is discarded |
+| 402 | `{ error: "INVALID_SETTLE_AMOUNT", message }` | A metered route named an amount the middleware cannot settle, see [Metered routes](#metered-routes-upto) |
+| 504 | `{ error: "HANDLER_TIMEOUT", message }` on Express and Hono, an empty body on Next.js | The handler did not answer within its timeout, and nothing is settled. Next.js also answers this empty 504 when the handler throws |
+| 400, or the status the price function chose | `{ error, message }` | A price function refused the request with `X402PriceRejectedError`, and nothing was invoiced |
+
 ### Thrown by the SDK
 
 | Error class | When |
 |-------------|------|
-| `X402ConfigError` | Invalid config at construction (bad `payTo`, bad facilitator URL, empty `routes`, non-positive `price`) — plus, on the first request to a route, an unknown network with no `acceptedTokens`, or an accepted token whose decimals are neither in the catalog nor set via `decimals` |
+| `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 |
 | `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. |
 
@@ -753,23 +795,80 @@ 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 |
-| `INVALID_PAYMENT` | `payment-signature` / `X-PAYMENT` header could not be base64-decoded |
+| `FACILITATOR_UNAVAILABLE` | The facilitator gave no usable answer: unreachable, too slow on verify, a redirect, an error without an `error` field, or a body that is not JSON (see below) |
+| `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. The middleware also gives this code to a verify refusal whose `error` is not a code, see [Propagated from the facilitator](#propagated-from-the-facilitator) |
+| `INVALID_PAYMENT` | `payment-signature` / `X-PAYMENT` header is not base64-encoded JSON |
 
-### Propagated from the facilitator
+#### `FACILITATOR_UNAVAILABLE`
 
-When the facilitator rejects a payment, its error code is forwarded as the `error` field on the re-issued 402 body. Common values:
+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 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.
+
+### Propagated from the facilitator
 
-| Code | Meaning |
-|------|---------|
-| `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 |
-| `NETWORK_MISMATCH` | Payload chain ≠ route config 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 a payment at verify, its code is forwarded as the `error` field on the re-issued 402 body, its text as `message`, and its `Retry-After` header is copied when it sent one. The agent always gets a 402. The facilitator's own status is the `.status` of the `X402RuntimeError` that `FacilitatorClient.verify` throws. The codes:
+
+| Code | Facilitator status | Meaning | What the agent should do |
+|------|--------------------|---------|--------------------------|
+| `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 |
+| `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 |
+| `ASSET_MISMATCH` | 400 | The route does not deliver the token the merchant requires | Pay so that the merchant receives one of the `accepts` assets |
+| `RECIPIENT_MISMATCH` | 400 | The signed recipient is not the merchant's `payTo` | Sign to the invoiced `payTo` |
+| `NETWORK_MISMATCH` | 400 | The facilitator does not support the payload's chain, or it is not the route's chain | Sign on the invoiced network |
+| `WINDOW_TOO_LONG` | 400 | A metered authorization valid for more than 3600 s (one hour) | Sign again with a `validBefore` within the hour |
+| `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 |
+| `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)).
+
+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 | 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 |
+| `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 |
+| `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 |
+| `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 |
+| `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.
+
+`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.
+
+### Rate limits
+
+The facilitator counts the requests of each IP address that calls it, which is the merchant's server: 60 `POST /x402/verify` a minute and 600 `POST /x402/settle` a minute, each on its own counter. It also counts the verifies of each payer: 1,000 per UTC clock hour.
+
+| 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` |
+| 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.
 
 ---
 
@@ -808,9 +907,9 @@ import {
 | Decimals | per accepted token (chains catalog) | 6 (fixed default) |
 | Auth standard | x402 / Coinbase | RFC 9110 `Payment` auth-scheme |
 | Facilitator endpoints | `/x402/verify`, `/x402/settle` | `/mpp/verify`, `/mpp/settle` |
-| On-chain routes | A–L | A–L (same) |
+| On-chain routes | A to L, and U for `upto` | A to L, except G |
 
-Both protocols share the same facilitator backend, the same `SignedPaymentPayload` authorization format, and the same settlement routes.
+Both protocols settle through the same facilitator backend. MPP reaches routes A to L except G, its `parallel` method carrying the same `SignedPaymentPayload` as x402. Route U, for metered payments, is x402 only.
 
 ---
 
@@ -818,10 +917,11 @@ Both protocols share the same facilitator backend, the same `SignedPaymentPayloa
 
 | Package | Purpose |
 |---------|---------|
+| [`@parallel-protocol/x402-fetch`](../x402-fetch) | The payer side: a `fetch` that pays these 402 challenges |
 | [`@parallel-protocol/payment-core`](../payment-core) | EIP-3009 authorization builders and EIP-712 signing helpers (agent-side) |
 | [`@parallel-protocol/x402-types`](../x402-types) | The facilitator's HTTP wire contract (Zod schemas) |
 | [`@parallel-protocol/mpp`](../mpp) | Machine Payments Protocol middleware (IETF `Payment` auth-scheme) |
-| [`@parallel-protocol/chains`](../chains) | 25-chain catalog with contract addresses |
+| [`@parallel-protocol/chains`](../chains) | 24-chain catalog with contract addresses |
 
 ---