@parallel-protocol/x402 0.5.3 → 0.6.0

package/README.md

@@ -40,6 +40,7 @@ Agent                        Merchant (this SDK)           Facilitator
 - 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.)
+- 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.
 
 ---
@@ -198,6 +199,8 @@ interface PaymentMiddlewareConfig {
 | `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)). |
 | `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). |
+| `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. |
 
 Route matching uses **longest prefix wins**: `/api/v1/users` will match a `/api/v1` route config before a `/api` one.
 
@@ -299,12 +302,12 @@ interface PaymentRequired {
     mimeType: "application/json";
   };
   accepts: Array<{         // one entry per accepted token
-    scheme: "exact";
+    scheme: "exact" | "upto";  // the route's scheme ("exact" unless configured)
     network: string;        // EIP-155 format: "eip155:8453"
     asset: string;          // token address
-    amount: string;         // smallest unit of `asset`, per its own decimals
+    amount: string;         // smallest unit of `asset`, per its own decimals — the cap for "upto"
     payTo: string;
-    maxTimeoutSeconds: 300;
+    maxTimeoutSeconds: number;  // the route's settlement window (default 300)
     extra: { decimals: number };  // decimals of `asset` — payers need not guess
   }>;
 }
@@ -350,6 +353,7 @@ interface PaymentConfirmation {
   chain: string;        // "base"
   gasSponsored: boolean;
   networkId: string;    // "eip155:8453"
+  amountSettled?: string;  // metered routes: what was actually charged (smallest unit)
 }
 ```
 
@@ -357,9 +361,51 @@ 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.
+
+```typescript
+routes: {
+  "/v1/chat/completions": {
+    scheme: "upto",
+    price: "2",                // the cap, in USDp
+    maxTimeoutSeconds: 600,    // the handler may take up to ~9 minutes
+    network: "base",
+    payTo: "0xYourAddress",
+    acceptedTokens: [PARALLEL_TOKENS.base.usdp],
+  },
+},
+```
+
+The handler reports the amount to charge through the `payment-settle-amount` response header, in whole token units like `price`:
+
+```typescript
+import { SETTLE_AMOUNT_HEADER } from "@parallel-protocol/x402";
+
+fastify.post("/v1/chat/completions", async (request, reply) => {
+  const completion = await runInference(request.body);
+  reply.header(SETTLE_AMOUNT_HEADER, completion.costInUsdp); // e.g. "0.0137"
+  return completion;
+});
+```
+
+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:
+
+| Header value | What happens |
+|---|---|
+| absent | The cap is charged. |
+| `"0"` (an explicit zero) | The request is served for free — nothing is settled, no `payment-response`. |
+| a decimal up to `price` | That amount is settled; the receipt's `amountSettled` carries it. |
+| malformed, more decimals than the token, or above `price` | The response is discarded and the client gets 402 `INVALID_SETTLE_AMOUNT` — a handler bug never charges the payer, and a positive amount the token cannot represent is never silently served for free. Round your cost to the token's precision before setting the header. |
+
+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.
+
+---
+
 ## Payment routes
 
-The facilitator supports 12 settlement routes. The route is selected automatically based on the signed payload:
+The facilitator supports 13 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 |
 |-------|--------------------------|---------------------|------------------------------|----------|-------|
@@ -375,6 +421,7 @@ The facilitator supports 12 settlement routes. The route is selected automatical
 | **J** | `transferWithAuthorization` | sUSDp | sUSDp | ~65K | Direct sUSDp share transfer |
 | **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`) |
 
 **Chain requirements:**
 - Routes B, D, E, G, I, K, L require the **Parallelizer** to be deployed on the target chain (Ethereum, Base, Avalanche, HyperEVM).

package/dist/{chunk-KQPIZ6SZ.cjs → chunk-K6QETMQA.cjs}

@@ -82,13 +82,19 @@ var facilitatorConfigSchema = zod.z.object({
   url: zod.z.string().refine((v) => URL.canParse(v), "Invalid facilitator URL"),
   apiKey: zod.z.string().optional()
 });
+var UPTO_MAX_TIMEOUT_SECONDS = 3600;
 var routeConfigSchema = zod.z.object({
   price: priceSchema,
   network: zod.z.string().min(1, "Network is required"),
   payTo: ethereumAddressSchema,
   acceptedTokens: zod.z.array(ethereumAddressSchema).optional(),
-  description: zod.z.string().optional()
-});
+  description: zod.z.string().optional(),
+  scheme: zod.z.enum(["exact", "upto"]).optional(),
+  maxTimeoutSeconds: zod.z.number().int().positive().optional()
+}).refine(
+  (route) => route.scheme !== "upto" || (route.maxTimeoutSeconds ?? 300) <= UPTO_MAX_TIMEOUT_SECONDS,
+  `maxTimeoutSeconds must be at most ${UPTO_MAX_TIMEOUT_SECONDS} on an upto route`
+);
 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")
@@ -100,7 +106,8 @@ var facilitatorResponseSchema = zod.z.discriminatedUnion("success", [
     route: zod.z.string(),
     chain: zod.z.string(),
     gasSponsored: zod.z.boolean(),
-    networkId: zod.z.string()
+    networkId: zod.z.string(),
+    amountSettled: zod.z.string().optional()
   }),
   zod.z.object({
     success: zod.z.literal(false),
@@ -117,7 +124,9 @@ var verifyResponseSchema = zod.z.object({
 var settleSuccessSchema = zod.z.object({
   txHash: txHashSchema,
   route: zod.z.string(),
-  gasSponsored: zod.z.boolean()
+  gasSponsored: zod.z.boolean(),
+  // Metered routes: the amount actually charged (smallest unit).
+  amountSettled: zod.z.string().optional()
 });
 var settleErrorSchema = zod.z.object({
   error: zod.z.string(),
@@ -169,14 +178,21 @@ var FacilitatorClient = class {
       throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
-  async settle(paymentHeader, paymentRequirements) {
+  async settle(paymentHeader, paymentRequirements, options) {
     const paymentPayload = decodePaymentHeader(paymentHeader);
     let json;
     try {
       const response = await fetch(`${this.config.url}/x402/settle`, {
         method: "POST",
         headers: this.buildHeaders(),
-        body: JSON.stringify({ paymentPayload, paymentRequirements }),
+        // settleAmount only travels for metered routes — exact bodies are unchanged.
+        body: JSON.stringify({
+          paymentPayload,
+          paymentRequirements,
+          ...options?.amount !== void 0 && {
+            settleAmount: options.amount
+          }
+        }),
         signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS)
       });
       if (!response.ok) {
@@ -199,7 +215,10 @@ var FacilitatorClient = class {
           route: parsed.route,
           chain: paymentRequirements.network,
           gasSponsored: parsed.gasSponsored,
-          networkId: toEip155Network(paymentRequirements.network)
+          networkId: toEip155Network(paymentRequirements.network),
+          ...parsed.amountSettled !== void 0 && {
+            amountSettled: parsed.amountSettled
+          }
         };
       }
       return {
@@ -244,6 +263,22 @@ var FacilitatorClient = class {
     return headers;
   }
 };
+
+// src/timeout.ts
+var HANDLER_TIMEOUT_MS = 3e4;
+var HANDLER_TIMEOUT = /* @__PURE__ */ Symbol("x402:handler-timeout");
+async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(HANDLER_TIMEOUT), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 var PARALLEL_TOKENS = {
   ethereum: {
     usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
@@ -285,6 +320,34 @@ function getTokenDecimals(network, address) {
 }
 
 // src/middleware.ts
+var SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+function handlerTimeoutFor(config) {
+  if ((config.scheme ?? "exact") !== "upto") return HANDLER_TIMEOUT_MS;
+  const seconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+  return Math.max(HANDLER_TIMEOUT_MS, (seconds - 60) * 1e3);
+}
+function resolveSettleAmount(raw, maxAmount, decimals) {
+  if (raw === void 0)
+    return { kind: "settle", amount: maxAmount.toString() };
+  const value = raw.trim();
+  let amount;
+  try {
+    amount = parsePrice(value, decimals);
+  } catch {
+    return { kind: "invalid", reason: "malformed" };
+  }
+  const fraction = value.split(".")[1] ?? "";
+  if (fraction.length > decimals)
+    return { kind: "invalid", reason: "precision" };
+  if (amount === 0n) return { kind: "skip" };
+  if (amount > maxAmount) return { kind: "invalid", reason: "above-cap" };
+  return { kind: "settle", amount: amount.toString() };
+}
+var INVALID_SETTLE_AMOUNT_RESPONSE = {
+  error: "INVALID_SETTLE_AMOUNT",
+  message: `The handler set an invalid ${SETTLE_AMOUNT_HEADER} header \u2014 expected a decimal amount in token units, formatted like the route price and within the token's precision, at most the route price.`
+};
 function resolveAcceptedTokens(config) {
   if (config.acceptedTokens?.length) {
     return config.acceptedTokens;
@@ -309,12 +372,12 @@ function buildPaymentRequired(url, config, resolvedTokens) {
   const accepts = resolvedTokens.map((asset) => {
     const decimals = resolveDecimals(config, asset);
     return {
-      scheme: "exact",
+      scheme: config.scheme ?? "exact",
       network,
       asset,
       amount: parsePrice(config.price, decimals).toString(),
       payTo: config.payTo,
-      maxTimeoutSeconds: 300,
+      maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS,
       extra: { decimals }
     };
   });
@@ -360,11 +423,17 @@ function resolveDeliveredAsset(header, config, resolvedTokens) {
 }
 function buildFacilitatorRequirements(config, asset) {
   const decimals = resolveDecimals(config, asset);
+  const scheme = config.scheme ?? "exact";
   return {
     maxAmountRequired: parsePrice(config.price, decimals).toString(),
     asset,
     payTo: config.payTo,
-    network: config.network
+    network: config.network,
+    // Only metered routes name their scheme — exact requirements are unchanged.
+    ...scheme === "upto" && {
+      scheme,
+      maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS
+    }
   };
 }
 function paymentRequiredResponse(url, config, resolvedTokens, error) {
@@ -407,10 +476,12 @@ function createPaymentGate(config) {
         )
       };
     }
-    const requirements = buildFacilitatorRequirements(
+    const asset = resolveDeliveredAsset(
+      paymentHeader,
       routeConfig,
-      resolveDeliveredAsset(paymentHeader, routeConfig, resolvedTokens)
+      resolvedTokens
     );
+    const requirements = buildFacilitatorRequirements(routeConfig, asset);
     try {
       await client.verify(paymentHeader, requirements);
     } catch (e) {
@@ -427,7 +498,12 @@ function createPaymentGate(config) {
     }
     return {
       type: "verified",
-      settle: () => client.settle(paymentHeader, requirements)
+      scheme: routeConfig.scheme ?? "exact",
+      maxAmount: BigInt(requirements.maxAmountRequired),
+      decimals: resolveDecimals(routeConfig, asset),
+      handlerTimeoutMs: handlerTimeoutFor(routeConfig),
+      // Exact routes keep the historical two-argument client call.
+      settle: (options) => options ? client.settle(paymentHeader, requirements, options) : client.settle(paymentHeader, requirements)
     };
   };
 }
@@ -439,14 +515,42 @@ function createPaymentMiddleware(config) {
     if (gateResult.type === "error") return gateResult.result;
     let handlerResult;
     try {
-      handlerResult = await adapter.runHandler();
+      handlerResult = await adapter.runHandler({
+        timeoutMs: gateResult.handlerTimeoutMs
+      });
     } catch {
       return { pass: true, handlerRan: true };
     }
+    let raw;
+    if (gateResult.scheme === "upto") {
+      raw = handlerResult.getResponseHeader?.(SETTLE_AMOUNT_HEADER);
+      handlerResult.removeResponseHeader?.(SETTLE_AMOUNT_HEADER);
+    }
     if (handlerResult.status >= 200 && handlerResult.status < 300) {
+      let settleOptions;
+      if (gateResult.scheme === "upto") {
+        const resolved = resolveSettleAmount(
+          raw,
+          gateResult.maxAmount,
+          gateResult.decimals
+        );
+        if (resolved.kind === "invalid") {
+          handlerResult.discardResponse();
+          return {
+            status: 402,
+            headers: { "Content-Type": "application/json" },
+            body: INVALID_SETTLE_AMOUNT_RESPONSE
+          };
+        }
+        if (resolved.kind === "skip") {
+          handlerResult.sendResponse();
+          return { pass: true, handlerRan: true };
+        }
+        settleOptions = { amount: resolved.amount };
+      }
       let settled = false;
       try {
-        const settleResponse = await gateResult.settle();
+        const settleResponse = settleOptions ? await gateResult.settle(settleOptions) : await gateResult.settle();
         if (settleResponse.success) {
           handlerResult.setResponseHeader(
             "payment-response",
@@ -478,7 +582,10 @@ function createPaymentMiddleware(config) {
 }
 
 exports.FacilitatorClient = FacilitatorClient;
+exports.HANDLER_TIMEOUT = HANDLER_TIMEOUT;
+exports.INVALID_SETTLE_AMOUNT_RESPONSE = INVALID_SETTLE_AMOUNT_RESPONSE;
 exports.PARALLEL_TOKENS = PARALLEL_TOKENS;
+exports.SETTLE_AMOUNT_HEADER = SETTLE_AMOUNT_HEADER;
 exports.X402ConfigError = X402ConfigError;
 exports.X402RuntimeError = X402RuntimeError;
 exports.X402_ERROR_CODES = X402_ERROR_CODES;
@@ -487,5 +594,7 @@ exports.createPaymentMiddleware = createPaymentMiddleware;
 exports.encodeBase64 = encodeBase64;
 exports.getDefaultAcceptedTokens = getDefaultAcceptedTokens;
 exports.parsePrice = parsePrice;
+exports.raceTimeout = raceTimeout;
+exports.resolveSettleAmount = resolveSettleAmount;
 exports.toEip155Network = toEip155Network;
 exports.validateAddress = validateAddress;

package/dist/{chunk-75GLDK7L.js → chunk-TLCEPWQI.js}

@@ -80,13 +80,19 @@ var facilitatorConfigSchema = z.object({
   url: z.string().refine((v) => URL.canParse(v), "Invalid facilitator URL"),
   apiKey: z.string().optional()
 });
+var UPTO_MAX_TIMEOUT_SECONDS = 3600;
 var routeConfigSchema = z.object({
   price: priceSchema,
   network: z.string().min(1, "Network is required"),
   payTo: ethereumAddressSchema,
   acceptedTokens: z.array(ethereumAddressSchema).optional(),
-  description: z.string().optional()
-});
+  description: z.string().optional(),
+  scheme: z.enum(["exact", "upto"]).optional(),
+  maxTimeoutSeconds: z.number().int().positive().optional()
+}).refine(
+  (route) => route.scheme !== "upto" || (route.maxTimeoutSeconds ?? 300) <= UPTO_MAX_TIMEOUT_SECONDS,
+  `maxTimeoutSeconds must be at most ${UPTO_MAX_TIMEOUT_SECONDS} on an upto route`
+);
 var paymentMiddlewareConfigSchema = z.object({
   facilitator: facilitatorConfigSchema,
   routes: z.record(z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
@@ -98,7 +104,8 @@ var facilitatorResponseSchema = z.discriminatedUnion("success", [
     route: z.string(),
     chain: z.string(),
     gasSponsored: z.boolean(),
-    networkId: z.string()
+    networkId: z.string(),
+    amountSettled: z.string().optional()
   }),
   z.object({
     success: z.literal(false),
@@ -115,7 +122,9 @@ var verifyResponseSchema = z.object({
 var settleSuccessSchema = z.object({
   txHash: txHashSchema,
   route: z.string(),
-  gasSponsored: z.boolean()
+  gasSponsored: z.boolean(),
+  // Metered routes: the amount actually charged (smallest unit).
+  amountSettled: z.string().optional()
 });
 var settleErrorSchema = z.object({
   error: z.string(),
@@ -167,14 +176,21 @@ var FacilitatorClient = class {
       throw new X402RuntimeError(X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
-  async settle(paymentHeader, paymentRequirements) {
+  async settle(paymentHeader, paymentRequirements, options) {
     const paymentPayload = decodePaymentHeader(paymentHeader);
     let json;
     try {
       const response = await fetch(`${this.config.url}/x402/settle`, {
         method: "POST",
         headers: this.buildHeaders(),
-        body: JSON.stringify({ paymentPayload, paymentRequirements }),
+        // settleAmount only travels for metered routes — exact bodies are unchanged.
+        body: JSON.stringify({
+          paymentPayload,
+          paymentRequirements,
+          ...options?.amount !== void 0 && {
+            settleAmount: options.amount
+          }
+        }),
         signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS)
       });
       if (!response.ok) {
@@ -197,7 +213,10 @@ var FacilitatorClient = class {
           route: parsed.route,
           chain: paymentRequirements.network,
           gasSponsored: parsed.gasSponsored,
-          networkId: toEip155Network(paymentRequirements.network)
+          networkId: toEip155Network(paymentRequirements.network),
+          ...parsed.amountSettled !== void 0 && {
+            amountSettled: parsed.amountSettled
+          }
         };
       }
       return {
@@ -242,6 +261,22 @@ var FacilitatorClient = class {
     return headers;
   }
 };
+
+// src/timeout.ts
+var HANDLER_TIMEOUT_MS = 3e4;
+var HANDLER_TIMEOUT = /* @__PURE__ */ Symbol("x402:handler-timeout");
+async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(HANDLER_TIMEOUT), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 var PARALLEL_TOKENS = {
   ethereum: {
     usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
@@ -283,6 +318,34 @@ function getTokenDecimals(network, address) {
 }
 
 // src/middleware.ts
+var SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+function handlerTimeoutFor(config) {
+  if ((config.scheme ?? "exact") !== "upto") return HANDLER_TIMEOUT_MS;
+  const seconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+  return Math.max(HANDLER_TIMEOUT_MS, (seconds - 60) * 1e3);
+}
+function resolveSettleAmount(raw, maxAmount, decimals) {
+  if (raw === void 0)
+    return { kind: "settle", amount: maxAmount.toString() };
+  const value = raw.trim();
+  let amount;
+  try {
+    amount = parsePrice(value, decimals);
+  } catch {
+    return { kind: "invalid", reason: "malformed" };
+  }
+  const fraction = value.split(".")[1] ?? "";
+  if (fraction.length > decimals)
+    return { kind: "invalid", reason: "precision" };
+  if (amount === 0n) return { kind: "skip" };
+  if (amount > maxAmount) return { kind: "invalid", reason: "above-cap" };
+  return { kind: "settle", amount: amount.toString() };
+}
+var INVALID_SETTLE_AMOUNT_RESPONSE = {
+  error: "INVALID_SETTLE_AMOUNT",
+  message: `The handler set an invalid ${SETTLE_AMOUNT_HEADER} header \u2014 expected a decimal amount in token units, formatted like the route price and within the token's precision, at most the route price.`
+};
 function resolveAcceptedTokens(config) {
   if (config.acceptedTokens?.length) {
     return config.acceptedTokens;
@@ -307,12 +370,12 @@ function buildPaymentRequired(url, config, resolvedTokens) {
   const accepts = resolvedTokens.map((asset) => {
     const decimals = resolveDecimals(config, asset);
     return {
-      scheme: "exact",
+      scheme: config.scheme ?? "exact",
       network,
       asset,
       amount: parsePrice(config.price, decimals).toString(),
       payTo: config.payTo,
-      maxTimeoutSeconds: 300,
+      maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS,
       extra: { decimals }
     };
   });
@@ -358,11 +421,17 @@ function resolveDeliveredAsset(header, config, resolvedTokens) {
 }
 function buildFacilitatorRequirements(config, asset) {
   const decimals = resolveDecimals(config, asset);
+  const scheme = config.scheme ?? "exact";
   return {
     maxAmountRequired: parsePrice(config.price, decimals).toString(),
     asset,
     payTo: config.payTo,
-    network: config.network
+    network: config.network,
+    // Only metered routes name their scheme — exact requirements are unchanged.
+    ...scheme === "upto" && {
+      scheme,
+      maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS
+    }
   };
 }
 function paymentRequiredResponse(url, config, resolvedTokens, error) {
@@ -405,10 +474,12 @@ function createPaymentGate(config) {
         )
       };
     }
-    const requirements = buildFacilitatorRequirements(
+    const asset = resolveDeliveredAsset(
+      paymentHeader,
       routeConfig,
-      resolveDeliveredAsset(paymentHeader, routeConfig, resolvedTokens)
+      resolvedTokens
     );
+    const requirements = buildFacilitatorRequirements(routeConfig, asset);
     try {
       await client.verify(paymentHeader, requirements);
     } catch (e) {
@@ -425,7 +496,12 @@ function createPaymentGate(config) {
     }
     return {
       type: "verified",
-      settle: () => client.settle(paymentHeader, requirements)
+      scheme: routeConfig.scheme ?? "exact",
+      maxAmount: BigInt(requirements.maxAmountRequired),
+      decimals: resolveDecimals(routeConfig, asset),
+      handlerTimeoutMs: handlerTimeoutFor(routeConfig),
+      // Exact routes keep the historical two-argument client call.
+      settle: (options) => options ? client.settle(paymentHeader, requirements, options) : client.settle(paymentHeader, requirements)
     };
   };
 }
@@ -437,14 +513,42 @@ function createPaymentMiddleware(config) {
     if (gateResult.type === "error") return gateResult.result;
     let handlerResult;
     try {
-      handlerResult = await adapter.runHandler();
+      handlerResult = await adapter.runHandler({
+        timeoutMs: gateResult.handlerTimeoutMs
+      });
     } catch {
       return { pass: true, handlerRan: true };
     }
+    let raw;
+    if (gateResult.scheme === "upto") {
+      raw = handlerResult.getResponseHeader?.(SETTLE_AMOUNT_HEADER);
+      handlerResult.removeResponseHeader?.(SETTLE_AMOUNT_HEADER);
+    }
     if (handlerResult.status >= 200 && handlerResult.status < 300) {
+      let settleOptions;
+      if (gateResult.scheme === "upto") {
+        const resolved = resolveSettleAmount(
+          raw,
+          gateResult.maxAmount,
+          gateResult.decimals
+        );
+        if (resolved.kind === "invalid") {
+          handlerResult.discardResponse();
+          return {
+            status: 402,
+            headers: { "Content-Type": "application/json" },
+            body: INVALID_SETTLE_AMOUNT_RESPONSE
+          };
+        }
+        if (resolved.kind === "skip") {
+          handlerResult.sendResponse();
+          return { pass: true, handlerRan: true };
+        }
+        settleOptions = { amount: resolved.amount };
+      }
       let settled = false;
       try {
-        const settleResponse = await gateResult.settle();
+        const settleResponse = settleOptions ? await gateResult.settle(settleOptions) : await gateResult.settle();
         if (settleResponse.success) {
           handlerResult.setResponseHeader(
             "payment-response",
@@ -475,4 +579,4 @@ function createPaymentMiddleware(config) {
   };
 }
 
-export { FacilitatorClient, PARALLEL_TOKENS, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress };
+export { FacilitatorClient, HANDLER_TIMEOUT, INVALID_SETTLE_AMOUNT_RESPONSE, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, raceTimeout, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/express.cjs

@@ -1,9 +1,12 @@
 'use strict';
 
-var chunkXUNNMCO5_cjs = require('./chunk-XUNNMCO5.cjs');
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkK6QETMQA_cjs = require('./chunk-K6QETMQA.cjs');
 
 // src/express/adapter.ts
+function headerValue(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : String(value);
+}
 var TIMEOUT_BODY = JSON.stringify({
   error: "HANDLER_TIMEOUT",
   message: "The resource handler did not respond in time."
@@ -30,7 +33,7 @@ var ExpressAdapter = class {
   getUrl() {
     return `${this.req.protocol}://${this.req.headers.host}${this.req.originalUrl}`;
   }
-  async runHandler() {
+  async runHandler(options) {
     const res = this.res;
     const next = this.next;
     const originalWriteHead = res.writeHead.bind(res);
@@ -74,14 +77,17 @@ var ExpressAdapter = class {
       return originalEnd(...args);
     });
     next();
-    const outcome = await chunkXUNNMCO5_cjs.raceTimeout(endPromise);
-    if (outcome === chunkXUNNMCO5_cjs.HANDLER_TIMEOUT) {
+    const outcome = await chunkK6QETMQA_cjs.raceTimeout(endPromise, options?.timeoutMs);
+    if (outcome === chunkK6QETMQA_cjs.HANDLER_TIMEOUT) {
       discarded = true;
       return {
         status: 504,
         setResponseHeader: (name, value) => {
           if (!res.headersSent) res.setHeader(name, value);
         },
+        getResponseHeader: () => void 0,
+        removeResponseHeader: () => {
+        },
         sendResponse: () => {
           if (res.headersSent) return;
           originalWriteHead(504, { "Content-Type": "application/json" });
@@ -94,6 +100,8 @@ var ExpressAdapter = class {
     return {
       status: res.statusCode,
       setResponseHeader: (name, value) => res.setHeader(name, value),
+      getResponseHeader: (name) => headerValue(res.getHeader(name)),
+      removeResponseHeader: (name) => res.removeHeader(name),
       sendResponse: () => {
         settled = true;
         restore();
@@ -113,7 +121,7 @@ var ExpressAdapter = class {
 
 // src/express/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkKQPIZ6SZ_cjs.createPaymentMiddleware(config);
+  const middleware = chunkK6QETMQA_cjs.createPaymentMiddleware(config);
   return async (req, res, next) => {
     const result = await middleware(new ExpressAdapter(req, res, next));
     if ("pass" in result) {