@parallel-protocol/x402 0.8.3 → 0.10.0

package/README.md

@@ -201,7 +201,7 @@ interface PaymentMiddlewareConfig {
 | `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. |
+| `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. It may also list the network's USDC where the escrow takes Permit2 payments (Base), see [Payments from standard x402 clients](#payments-from-standard-x402-clients-usdc-through-permit2). Any other token is rejected at construction. |
 | `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). |
@@ -314,8 +314,17 @@ interface PaymentRequired {
     amount: string;         // smallest unit of `asset`, per its own decimals — the cap for "upto"
     payTo: string;
     maxTimeoutSeconds: number;  // the route's settlement window (default 300)
-    extra: { decimals: number };  // decimals of `asset` — payers need not guess
+    extra: {
+      decimals: number;     // decimals of `asset` — payers need not guess
+      // on an "upto" entry paid through Permit2 (USDC): the token's EIP-712 domain and the escrow
+      name?: string;
+      version?: string;
+      facilitatorAddress?: string;
+    };
   }>;
+  extensions?: {            // present when an entry is paid through Permit2
+    eip2612GasSponsoring: { info: { description: string; version: "1" }; schema: object };
+  };
 }
 ```
 
@@ -364,7 +373,13 @@ interface PaymentConfirmation {
   gasSponsored: boolean;
   networkId: string;    // "eip155:8453"
   amountSettled?: string;  // metered routes: what was actually charged (smallest unit)
+  amountDelivered?: string; // paid through Permit2: the USDp the merchant received (smallest unit), when the facilitator read it
   alreadySettled?: true;   // the facilitator answered from a recorded outcome, this call broadcast nothing
+  // The fields of the standard x402 settlement response, read by clients built on the x402 SDKs:
+  transaction?: string;    // the txHash
+  network?: string;        // "eip155:8453"
+  amount?: string;         // the amount charged, in the smallest unit of the paid token
+  payer?: string;
 }
 ```
 
@@ -374,7 +389,7 @@ 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. 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`.
+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, and in USDC from standard x402 clients ([below](#payments-from-standard-x402-clients-usdc-through-permit2)). 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: {
@@ -430,11 +445,36 @@ Instead of a header the handler sets, a route may carry a `meter` function that
 | `"0"` | The request is served for free, nothing is settled. |
 | `undefined` or `null` | The `payment-settle-amount` header decides, with the rules above (absent charges the cap). |
 | it throws, or returns something that is not an amount | The response is discarded and the client gets 402 `INVALID_SETTLE_AMOUNT`. |
+| a bigint, on a route that accepts tokens with different decimals | Refused like a failing meter, since a bigint is in one token's unit. Return a decimal string such as `"0.75"`. |
 
 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 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.
 
+### Payments from standard x402 clients (USDC through Permit2)
+
+Agents built on the x402 SDKs, AgentCash among them, pay a metered route with a Permit2 signature of the cap in USDC. To accept them, list the network's USDC in `acceptedTokens`:
+
+```typescript
+import { PARALLEL_TOKENS } from "@parallel-protocol/x402";
+
+routes: {
+  "/v1/chat/completions": {
+    scheme: "upto",
+    price: "2",              // the cap, in USDC or in USDp
+    network: "base",
+    payTo: "0xYourReceivingAddress",
+    acceptedTokens: [PARALLEL_TOKENS.base.usdc, PARALLEL_TOKENS.base.usdp],
+  },
+},
+```
+
+The 402 lists the USDC entry first, because these clients pay the first `upto` entry, and declares the `eip2612GasSponsoring` extension, so an agent that has not approved Permit2 signs a permit instead ([402 response](#402-response-payment-required)). The escrow converts the USDC to USDp, which the merchant receives. The handler names the amount to charge as for any metered route. The `payment-response` receipt gives the USDC charged in `amountSettled`, and the USDp the merchant received in `amountDelivered` when the facilitator could read it from the settlement.
+
+Before listing USDC, approve the escrow once for USDC from the `payTo` address, since the escrow takes the USDC back to convert it. Its address is `getUptoEscrowAddress("base")` from `@parallel-protocol/chains`. Receive on a dedicated address rather than a treasury: it bounds what the approval exposes.
+
+The price must be a decimal string such as `"2"`, and so must the amount a `meter` returns. A bigint, or an explicit `decimals`, is in one token's unit and is refused on a route that accepts both tokens. Standard clients also refuse a cap above their spending limit, a few dollars by default, so keep the cap of such a route low.
+
 ---
 
 ## Per-request pricing
@@ -541,7 +581,7 @@ Without `meter`, what is charged after the response is the handler's call: set t
 
 ## Payment routes
 
-The facilitator supports 13 settlement routes. The route is selected automatically based on the signed payload:
+The facilitator supports 14 settlement routes. The route is selected automatically based on the signed payload:
 
 | Route | Credential method(s) | tokenIn (agent pays) | tokenOut (merchant receives) | Gas est. | Notes |
 |-------|--------------------------|---------------------|------------------------------|----------|-------|
@@ -558,6 +598,7 @@ The facilitator supports 13 settlement routes. The route is selected automatical
 | **K** | `redeemWithAuthorization` + `swapExactOutputWithAuthorization` | sUSDp | non-USDC backing (exact) | ~180K | Same as I but for other Parallelizer collaterals (atomic multicall3) |
 | **L** | `partialRedeemWithAuthorization` | sUSDp (partial) + USDp | USDp or backing collateral | ~180K | Partial sUSDp redeem combined with existing USDp; delivers to merchant (atomic multicall3) |
 | **U** | `uptoWithAuthorization` | USDp (cap) | USDp (actual) | ~130K | Metered payment: the escrow pulls the signed cap, pays the merchant the settled amount and refunds the rest atomically (scheme `upto`) |
+| **V** | `uptoPermit2` | USDC (cap), from a standard x402 client | USDp (actual, converted) | ~390K | Metered payment signed with Permit2: the x402 proxy pays the merchant the settled amount in USDC, which the escrow converts to USDp in the same transaction (scheme `upto`) |
 
 **Chain requirements:**
 - Routes B, D, E, G, I, K, L require the **Parallelizer** to be deployed on the target chain (Ethereum, Base, Avalanche, HyperEVM).
@@ -565,7 +606,7 @@ The facilitator supports 13 settlement routes. The route is selected automatical
 - Routes C, G, H, I, J, K, L require **sUSDp** (savings module) to be deployed on the target chain.
 - 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`.
+- Routes U and V need 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.
 
@@ -784,7 +825,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 `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 |
+| `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, a token other than USDp and the network's USDC paid through Permit2, or a bigint price or an explicit `decimals` while it accepts tokens with different decimals. 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, returns something that is not a price, or returns a bigint on an `upto` route that accepts tokens with different decimals |
 | `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. |
 
@@ -825,12 +866,15 @@ When the facilitator refuses a payment at verify, its code is forwarded as the `
 
 | 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_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, or its EIP-2612 permit is not for the cap or ends before the Permit2 deadline | Sign a payment that matches one of the `accepts` entries |
+| `INVALID_SIGNATURE` | 400 | EIP-712 signature recovery failed, or the payer's contract wallet refused the signature (payments through Permit2) | Sign again |
 | `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 |
+| `PAYMENT_NOT_YET_VALID` | 402 | A payment through Permit2 whose `validAfter` has not passed yet | Sign again with a `validAfter` in the past |
 | `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 |
+| `PERMIT2_ALLOWANCE_REQUIRED` | 412 | A payment through Permit2 from a payer whose Permit2 approval for the token is below the cap, with no EIP-2612 permit or one the token refused. The message starts with `permit2_allowance_required`, the reason standard x402 clients look for | Approve Permit2 for the token once, or sign the payment with an EIP-2612 permit |
+| `TOKEN_BLOCKED` | 403 | The token refuses the transfer: an address is blacklisted, or the token is paused. Nothing was taken | Pay with another token |
 | `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 |
@@ -840,6 +884,9 @@ When the facilitator refuses a payment at verify, its code is forwarded as the `
 | `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 |
+| `MERCHANT_NOT_ENABLED` | 503 | The merchant's `payTo` has not approved the escrow for USDC yet, so a USDC payment cannot be converted (see [Payments from standard x402 clients](#payments-from-standard-x402-clients-usdc-through-permit2)). Nothing was taken | Pay with USDp, or pay again later |
+| `SWAP_UNAVAILABLE` | 503 | The Parallelizer cannot convert the token now: a cap is reached or a price feed is stale. Nothing was taken | Pay with USDp, or pay again later |
+| `SETTLEMENT_WOULD_FAIL` | 402 | A payment through Permit2 whose settlement, simulated at verify, would revert for another reason. Nothing was taken | Pay with another token, or sign a new payment 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)).
@@ -848,7 +895,7 @@ 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 |
+| `INSUFFICIENT_BALANCE` | 402 | The payer no longer holds the signed amount, or for a payment through Permit2 the amount charged | Fund the wallet, 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 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 |
@@ -857,7 +904,7 @@ When the facilitator refuses at settle, the 402 body is `{ error: "PAYMENT_SETTL
 | `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 |
-| `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_PRICE_MOVED` | 402 | The Parallelizer refused the swap: its price or fee moved beyond the payment's margin, the one signed with it, or for a payment through Permit2 the one the facilitator sets under the Parallelizer's quote. 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 |

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

@@ -2,6 +2,7 @@
 
 var chunkKZZY5LS6_cjs = require('./chunk-KZZY5LS6.cjs');
 var chains = require('@parallel-protocol/chains');
+var paymentCore = require('@parallel-protocol/payment-core');
 var zod = require('zod');
 
 var PARALLEL_TOKENS = {
@@ -35,6 +36,9 @@ var PARALLEL_TOKENS = {
     sUSDe: "0x211Cc4DD073734dA055fbF44a2b4667d5E5fE5d2"
   }
 };
+var USDC_EIP712_DOMAIN = {
+  base: { name: "USD Coin", version: "2" }
+};
 function getDefaultAcceptedTokens(network) {
   const entry = PARALLEL_TOKENS[network];
   if (!entry) return void 0;
@@ -48,6 +52,12 @@ function getMeteredAcceptedTokens(network) {
 function getTokenDecimals(network, address) {
   return chains.getTokenDecimals(network, address);
 }
+function hasMixedDecimals(network, tokens) {
+  const decimals = new Set(
+    tokens?.map((token) => chains.getTokenDecimals(network, token))
+  );
+  return decimals.size > 1;
+}
 
 // src/utils.ts
 var EIP155_NETWORKS = {
@@ -118,6 +128,114 @@ function matchRoute(path, routes) {
   }
   return bestMatch;
 }
+function permit2Extra(network, asset) {
+  const domain = USDC_EIP712_DOMAIN[network];
+  const escrow = chains.getUptoEscrowAddress(network);
+  if (!domain || !escrow) return void 0;
+  const usdc = PARALLEL_TOKENS[network].usdc;
+  if (usdc.toLowerCase() !== asset.toLowerCase()) return void 0;
+  return { ...domain, facilitatorAddress: escrow };
+}
+var EIP2612_GAS_SPONSORING_EXTENSION = {
+  eip2612GasSponsoring: {
+    info: {
+      description: "The facilitator accepts EIP-2612 gasless Permit to `Permit2` canonical contract.",
+      version: "1"
+    },
+    schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: {
+        from: {
+          type: "string",
+          pattern: "^0x[a-fA-F0-9]{40}$",
+          description: "The address of the sender."
+        },
+        asset: {
+          type: "string",
+          pattern: "^0x[a-fA-F0-9]{40}$",
+          description: "The address of the ERC-20 token contract."
+        },
+        spender: {
+          type: "string",
+          pattern: "^0x[a-fA-F0-9]{40}$",
+          description: "The address of the spender (Canonical Permit2)."
+        },
+        amount: {
+          type: "string",
+          pattern: "^[0-9]+$",
+          description: "The amount to approve (uint256). Typically MaxUint."
+        },
+        nonce: {
+          type: "string",
+          pattern: "^[0-9]+$",
+          description: "The current nonce of the sender."
+        },
+        deadline: {
+          type: "string",
+          pattern: "^[0-9]+$",
+          description: "The timestamp at which the signature expires."
+        },
+        signature: {
+          type: "string",
+          pattern: "^0x[a-fA-F0-9]+$",
+          description: "The 65-byte concatenated signature (r, s, v) as a hex string."
+        },
+        version: {
+          type: "string",
+          pattern: "^[0-9]+(\\.[0-9]+)*$",
+          description: "Schema version identifier."
+        }
+      },
+      required: [
+        "from",
+        "asset",
+        "spender",
+        "amount",
+        "nonce",
+        "deadline",
+        "signature",
+        "version"
+      ]
+    }
+  }
+};
+function signedPermit(info = {}) {
+  const { amount, deadline, signature } = info;
+  return typeof amount === "string" && typeof deadline === "string" && typeof signature === "string" ? { value: amount, deadline, signature } : void 0;
+}
+function isStandardPermit2Payment(decoded) {
+  const payment = decoded;
+  return typeof payment?.payload?.permit2Authorization === "object" && payment.payload.permit2Authorization !== null && payment.accepted?.scheme === "upto";
+}
+function toFacilitatorPayload(decoded, network) {
+  if (!isStandardPermit2Payment(decoded)) return decoded;
+  const { signature, permit2Authorization: auth } = decoded.payload;
+  const permit = signedPermit(decoded.extensions?.eip2612GasSponsoring?.info);
+  return {
+    scheme: "upto",
+    network,
+    method: "uptoPermit2",
+    tokenIn: auth.permitted.token,
+    payload: {
+      signature,
+      authorization: {
+        from: auth.from,
+        to: auth.witness.to,
+        value: auth.permitted.amount,
+        validAfter: auth.witness.validAfter,
+        validBefore: auth.deadline,
+        nonce: paymentCore.permit2NonceToBytes32(auth.nonce)
+      },
+      ...permit && { permit2612: permit }
+    },
+    uptoParams: { payTo: auth.witness.to },
+    permit2Params: {
+      spender: auth.spender,
+      facilitator: auth.witness.facilitator
+    }
+  };
+}
 var ethereumAddressSchema = zod.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "Invalid Ethereum address");
 var txHashSchema = zod.z.string().regex(/^0x[0-9a-fA-F]{64}$/);
 var priceSchema = zod.z.union([
@@ -152,6 +270,7 @@ var routeConfigSchema = zod.z.object({
   description: zod.z.string().optional(),
   scheme: zod.z.enum(["exact", "upto"]).optional(),
   maxTimeoutSeconds: zod.z.number().int().positive().optional(),
+  decimals: zod.z.number().int().nonnegative().optional(),
   meter: zod.z.custom(
     (value) => typeof value === "function",
     "meter must be a function of the response"
@@ -173,9 +292,12 @@ var routeConfigSchema = zod.z.object({
   const usdp = PARALLEL_TOKENS[route.network]?.usdp;
   if (!usdp) return true;
   return route.acceptedTokens.every(
-    (token) => token.toLowerCase() === usdp.toLowerCase()
+    (token) => token.toLowerCase() === usdp.toLowerCase() || permit2Extra(route.network, token) !== void 0
   );
-}, "acceptedTokens on an upto route may only list the network's USDp");
+}, "acceptedTokens on an upto route may only list the network's USDp, and its USDC where the escrow takes Permit2 payments").refine(
+  (route) => route.scheme !== "upto" || !hasMixedDecimals(route.network, route.acceptedTokens) || typeof route.price !== "bigint" && route.decimals === void 0,
+  'An upto route that accepts tokens with different decimals needs a price like "0.01", not a bigint or an explicit decimals'
+);
 var paymentMiddlewareConfigSchema = zod.z.object({
   facilitator: facilitatorConfigSchema,
   routes: zod.z.record(zod.z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
@@ -212,6 +334,9 @@ var settleSuccessSchema = zod.z.object({
   gasSponsored: zod.z.boolean(),
   // Metered routes: the amount actually charged (smallest unit).
   amountSettled: zod.z.string().optional(),
+  // A standard x402 Permit2 payment: the USDp the merchant received for
+  // amountSettled (smallest unit), when the facilitator read it.
+  amountDelivered: zod.z.string().optional(),
   // The facilitator answered from a recorded outcome, nothing was broadcast.
   alreadySettled: zod.z.boolean().optional()
 });
@@ -250,13 +375,17 @@ function throwIfRedirect(response) {
     status: response.status
   });
 }
-function decodePaymentHeader(paymentHeader) {
+function decodePaymentHeader(paymentHeader, network) {
   try {
-    return decodeBase64(paymentHeader);
+    return toFacilitatorPayload(decodeBase64(paymentHeader), network);
   } catch {
     throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.INVALID_PAYMENT);
   }
 }
+function payerOf(paymentPayload) {
+  const from = paymentPayload?.payload?.authorization?.from;
+  return typeof from === "string" ? from : void 0;
+}
 var FacilitatorClient = class {
   // Checked and kept when the client is built: a config changed afterwards
   // does not move the calls elsewhere.
@@ -274,7 +403,10 @@ var FacilitatorClient = class {
     this.apiKey = config.apiKey;
   }
   async verify(paymentHeader, paymentRequirements) {
-    const paymentPayload = decodePaymentHeader(paymentHeader);
+    const paymentPayload = decodePaymentHeader(
+      paymentHeader,
+      paymentRequirements.network
+    );
     let json;
     try {
       const response = await fetch(`${this.url}/x402/verify`, {
@@ -309,7 +441,10 @@ var FacilitatorClient = class {
     }
   }
   async settle(paymentHeader, paymentRequirements, options) {
-    const paymentPayload = decodePaymentHeader(paymentHeader);
+    const paymentPayload = decodePaymentHeader(
+      paymentHeader,
+      paymentRequirements.network
+    );
     let json;
     try {
       const response = await fetch(`${this.url}/x402/settle`, {
@@ -360,17 +495,27 @@ var FacilitatorClient = class {
     try {
       const parsed = settleResponseSchema.parse(json);
       if ("txHash" in parsed) {
+        const txHash = parsed.txHash;
+        const networkId = toEip155Network(paymentRequirements.network);
+        const payer = payerOf(paymentPayload);
         return {
           success: true,
-          txHash: parsed.txHash,
+          txHash,
           route: parsed.route,
           chain: paymentRequirements.network,
           gasSponsored: parsed.gasSponsored,
-          networkId: toEip155Network(paymentRequirements.network),
+          networkId,
           ...parsed.amountSettled !== void 0 && {
             amountSettled: parsed.amountSettled
           },
-          ...parsed.alreadySettled && { alreadySettled: true }
+          ...parsed.amountDelivered !== void 0 && {
+            amountDelivered: parsed.amountDelivered
+          },
+          ...parsed.alreadySettled && { alreadySettled: true },
+          transaction: txHash,
+          network: networkId,
+          amount: parsed.amountSettled ?? paymentRequirements.maxAmountRequired,
+          ...payer && { payer }
         };
       }
       return {
@@ -449,7 +594,7 @@ async function requestContext(adapter) {
     body: adapter.getBody ? await adapter.getBody() : void 0
   };
 }
-async function resolvePrice(config, ctx) {
+async function resolvePrice(config, ctx, tokens) {
   if (typeof config.price !== "function") return config.price;
   if (!ctx) throw new chunkKZZY5LS6_cjs.X402ConfigError("A price function needs the request");
   let price;
@@ -470,6 +615,11 @@ async function resolvePrice(config, ctx) {
       )} \u2014 expected a positive amount like "0.01" or a bigint`
     );
   }
+  if (typeof price === "bigint" && config.scheme === "upto" && hasMixedDecimals(config.network, tokens)) {
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+      `The price function of route "${config.network}${ctx.path}" returned a bigint, but the route accepts tokens with different decimals: return a price like "0.01"`
+    );
+  }
   return price;
 }
 var SETTLE_AMOUNT_HEADER = "payment-settle-amount";
@@ -521,6 +671,17 @@ function invalidSettleAmountResponse(reason) {
     reason === "meter" ? INVALID_METER_RESPONSE : INVALID_SETTLE_AMOUNT_RESPONSE
   );
 }
+function refusingBigints(meter) {
+  return async (ctx) => {
+    const amount = await meter(ctx);
+    if (typeof amount === "bigint") {
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(
+        'The meter returned a bigint, but the route accepts tokens with different decimals: return an amount like "0.75"'
+      );
+    }
+    return amount;
+  };
+}
 var AMOUNT_FORMAT = /^\d+(?:\.\d+)?$/;
 async function resolveCharge(verified, settleHeader, response) {
   if (verified.meter) {
@@ -600,18 +761,27 @@ function priceInUnits(price, decimals, asset) {
 }
 function buildPaymentRequired(url, config, resolvedTokens, price) {
   const network = toEip155Network(config.network);
-  const accepts = resolvedTokens.map((asset) => {
+  const scheme = config.scheme ?? "exact";
+  const entries = resolvedTokens.map((asset) => {
     const decimals = resolveDecimals(config, asset);
     return {
-      scheme: config.scheme ?? "exact",
+      scheme,
       network,
       asset,
       amount: priceInUnits(price, decimals, asset),
       payTo: config.payTo,
       maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS,
-      extra: { decimals }
+      extra: {
+        decimals,
+        ...scheme === "upto" && permit2Extra(config.network, asset)
+      }
     };
   });
+  const viaPermit2 = (entry) => "facilitatorAddress" in entry.extra;
+  const accepts = [
+    ...entries.filter(viaPermit2),
+    ...entries.filter((entry) => !viaPermit2(entry))
+  ];
   return {
     x402Version: 2,
     resource: {
@@ -619,13 +789,17 @@ function buildPaymentRequired(url, config, resolvedTokens, price) {
       description: config.description,
       mimeType: "application/json"
     },
-    accepts
+    accepts,
+    ...accepts.some(viaPermit2) && {
+      extensions: EIP2612_GAS_SPONSORING_EXTENSION
+    }
   };
 }
-function decodePaymentPayload(header) {
+function decodePaymentPayload(header, network) {
   try {
-    const parsed = JSON.parse(
-      Buffer.from(header, "base64").toString("utf8")
+    const parsed = toFacilitatorPayload(
+      JSON.parse(Buffer.from(header, "base64").toString("utf8")),
+      network
     );
     return typeof parsed === "object" && parsed !== null ? parsed : void 0;
   } catch {
@@ -644,7 +818,7 @@ function deliveredToken(payload, chainTokens) {
   return payload.tokenIn ?? chainTokens?.usdp;
 }
 function resolveDeliveredAsset(header, config, resolvedTokens) {
-  const payload = decodePaymentPayload(header);
+  const payload = decodePaymentPayload(header, config.network);
   const target = payload ? deliveredToken(
     payload,
     PARALLEL_TOKENS[config.network]
@@ -719,7 +893,7 @@ function createPaymentGate(config) {
     let request = typeof routeConfig.price === "function" ? await requestContext(adapter) : void 0;
     let price;
     try {
-      price = await resolvePrice(routeConfig, request);
+      price = await resolvePrice(routeConfig, request, resolvedTokens);
     } catch (err) {
       if (!chunkKZZY5LS6_cjs.isPriceRejection(err)) throw err;
       const status = Number.isInteger(err.status) && err.status >= 400 && err.status <= 599 ? err.status : 400;
@@ -770,7 +944,8 @@ function createPaymentGate(config) {
         )
       };
     }
-    if (routeConfig.meter && !request) request = await requestContext(adapter);
+    const meter = routeConfig.meter && hasMixedDecimals(routeConfig.network, resolvedTokens) ? refusingBigints(routeConfig.meter) : routeConfig.meter;
+    if (meter && !request) request = await requestContext(adapter);
     return {
       type: "verified",
       scheme: routeConfig.scheme ?? "exact",
@@ -778,7 +953,7 @@ function createPaymentGate(config) {
       decimals: resolveDecimals(routeConfig, asset),
       handlerTimeoutMs: handlerTimeoutFor(routeConfig),
       settle: (options) => client.settle(paymentHeader, requirements, { ...options, settleToken }),
-      ...routeConfig.meter && { meter: routeConfig.meter, request }
+      ...meter && { meter, request }
     };
   };
 }