@parallel-protocol/x402 0.5.3 → 0.6.0

package/dist/express.d.cts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
-import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.cjs';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.cjs';
 import 'viem';
 
 declare class ExpressAdapter implements HTTPAdapter {
@@ -11,7 +11,7 @@ declare class ExpressAdapter implements HTTPAdapter {
     getMethod(): string;
     getPath(): string;
     getUrl(): string;
-    runHandler(): Promise<RunHandlerResult>;
+    runHandler(options?: RunHandlerOptions): Promise<RunHandlerResult>;
 }
 
 declare function paymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/express.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
-import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.js';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.js';
 import 'viem';
 
 declare class ExpressAdapter implements HTTPAdapter {
@@ -11,7 +11,7 @@ declare class ExpressAdapter implements HTTPAdapter {
     getMethod(): string;
     getPath(): string;
     getUrl(): string;
-    runHandler(): Promise<RunHandlerResult>;
+    runHandler(options?: RunHandlerOptions): Promise<RunHandlerResult>;
 }
 
 declare function paymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/express.js

@@ -1,7 +1,10 @@
-import { raceTimeout, HANDLER_TIMEOUT } from './chunk-2UEAVMCH.js';
-import { createPaymentMiddleware } from './chunk-75GLDK7L.js';
+import { raceTimeout, HANDLER_TIMEOUT, createPaymentMiddleware } from './chunk-TLCEPWQI.js';
 
 // 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."
@@ -28,7 +31,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);
@@ -72,7 +75,7 @@ var ExpressAdapter = class {
       return originalEnd(...args);
     });
     next();
-    const outcome = await raceTimeout(endPromise);
+    const outcome = await raceTimeout(endPromise, options?.timeoutMs);
     if (outcome === HANDLER_TIMEOUT) {
       discarded = true;
       return {
@@ -80,6 +83,9 @@ var ExpressAdapter = class {
         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" });
@@ -92,6 +98,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();

package/dist/fastify.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkK6QETMQA_cjs = require('./chunk-K6QETMQA.cjs');
 var fp = require('fastify-plugin');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -29,10 +29,22 @@ var FastifyAdapter = class {
 };
 
 // src/fastify/index.ts
+function refuse(reply, body) {
+  const json = JSON.stringify(body);
+  reply.status(402);
+  reply.header("Content-Type", "application/json");
+  reply.header("Content-Length", Buffer.byteLength(json));
+  return json;
+}
+function headerValue(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : String(value);
+}
 function paymentMiddleware(config) {
   return fp__default.default(async (fastify) => {
-    const gate = chunkKQPIZ6SZ_cjs.createPaymentGate(config);
-    const settleMap = /* @__PURE__ */ new WeakMap();
+    const gate = chunkK6QETMQA_cjs.createPaymentGate(config);
+    const verifiedMap = /* @__PURE__ */ new WeakMap();
+    const rawWriters = /* @__PURE__ */ new WeakMap();
     fastify.addHook("onRequest", async (req, reply) => {
       const gateResult = await gate(new FastifyAdapter(req));
       if (gateResult.type === "pass") return;
@@ -43,32 +55,69 @@ function paymentMiddleware(config) {
         reply.status(gateResult.result.status).send(gateResult.result.body);
         return;
       }
-      settleMap.set(req, gateResult.settle);
+      verifiedMap.set(req, gateResult);
+      const raw = reply.raw;
+      rawWriters.set(req, {
+        write: raw.write,
+        end: raw.end,
+        writeHead: raw.writeHead
+      });
+      const refuse2 = () => {
+        throw new Error(
+          "x402: raw responses are not supported on paid routes \u2014 return the body from the handler so the payment can settle"
+        );
+      };
+      raw.write = refuse2;
+      raw.end = refuse2;
+      raw.writeHead = refuse2;
     });
     fastify.addHook("onSend", async (req, reply, payload) => {
-      const settle = settleMap.get(req);
-      if (!settle || reply.statusCode < 200 || reply.statusCode >= 300) {
+      const writers = rawWriters.get(req);
+      if (writers) {
+        const raw2 = reply.raw;
+        raw2.write = writers.write;
+        raw2.end = writers.end;
+        raw2.writeHead = writers.writeHead;
+        rawWriters.delete(req);
+      }
+      const verified = verifiedMap.get(req);
+      if (!verified) return payload;
+      let raw;
+      if (verified.scheme === "upto") {
+        raw = headerValue(reply.getHeader(chunkK6QETMQA_cjs.SETTLE_AMOUNT_HEADER));
+        reply.removeHeader(chunkK6QETMQA_cjs.SETTLE_AMOUNT_HEADER);
+      }
+      if (reply.statusCode < 200 || reply.statusCode >= 300) {
         return payload;
       }
+      let settleOptions;
+      if (verified.scheme === "upto") {
+        const resolved = chunkK6QETMQA_cjs.resolveSettleAmount(
+          raw,
+          verified.maxAmount,
+          verified.decimals
+        );
+        if (resolved.kind === "invalid") {
+          return refuse(reply, chunkK6QETMQA_cjs.INVALID_SETTLE_AMOUNT_RESPONSE);
+        }
+        if (resolved.kind === "skip") return payload;
+        settleOptions = { amount: resolved.amount };
+      }
       let settled = false;
       try {
-        const settleResponse = await settle();
+        const settleResponse = settleOptions ? await verified.settle(settleOptions) : await verified.settle();
         if (settleResponse.success) {
-          reply.header("payment-response", chunkKQPIZ6SZ_cjs.encodeBase64(settleResponse));
+          reply.header("payment-response", chunkK6QETMQA_cjs.encodeBase64(settleResponse));
           reply.header("access-control-expose-headers", "payment-response");
           settled = true;
         }
       } catch {
       }
       if (!settled) {
-        const body = JSON.stringify({
+        return refuse(reply, {
           error: "PAYMENT_SETTLEMENT_FAILED",
           message: "Payment could not be confirmed after multiple attempts. Please retry."
         });
-        reply.status(402);
-        reply.header("Content-Type", "application/json");
-        reply.header("Content-Length", Buffer.byteLength(body));
-        return body;
       }
       return payload;
     });

package/dist/fastify.d.cts

@@ -1,5 +1,5 @@
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CUi55YSx.cjs';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.cjs';
 import 'viem';
 
 declare class FastifyAdapter implements HTTPAdapter {

package/dist/fastify.d.ts

@@ -1,5 +1,5 @@
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CUi55YSx.js';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.js';
 import 'viem';
 
 declare class FastifyAdapter implements HTTPAdapter {

package/dist/fastify.js

@@ -1,4 +1,4 @@
-import { createPaymentGate, encodeBase64 } from './chunk-75GLDK7L.js';
+import { createPaymentGate, SETTLE_AMOUNT_HEADER, resolveSettleAmount, encodeBase64, INVALID_SETTLE_AMOUNT_RESPONSE } from './chunk-TLCEPWQI.js';
 import fp from 'fastify-plugin';
 
 // src/fastify/adapter.ts
@@ -23,10 +23,22 @@ var FastifyAdapter = class {
 };
 
 // src/fastify/index.ts
+function refuse(reply, body) {
+  const json = JSON.stringify(body);
+  reply.status(402);
+  reply.header("Content-Type", "application/json");
+  reply.header("Content-Length", Buffer.byteLength(json));
+  return json;
+}
+function headerValue(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : String(value);
+}
 function paymentMiddleware(config) {
   return fp(async (fastify) => {
     const gate = createPaymentGate(config);
-    const settleMap = /* @__PURE__ */ new WeakMap();
+    const verifiedMap = /* @__PURE__ */ new WeakMap();
+    const rawWriters = /* @__PURE__ */ new WeakMap();
     fastify.addHook("onRequest", async (req, reply) => {
       const gateResult = await gate(new FastifyAdapter(req));
       if (gateResult.type === "pass") return;
@@ -37,16 +49,57 @@ function paymentMiddleware(config) {
         reply.status(gateResult.result.status).send(gateResult.result.body);
         return;
       }
-      settleMap.set(req, gateResult.settle);
+      verifiedMap.set(req, gateResult);
+      const raw = reply.raw;
+      rawWriters.set(req, {
+        write: raw.write,
+        end: raw.end,
+        writeHead: raw.writeHead
+      });
+      const refuse2 = () => {
+        throw new Error(
+          "x402: raw responses are not supported on paid routes \u2014 return the body from the handler so the payment can settle"
+        );
+      };
+      raw.write = refuse2;
+      raw.end = refuse2;
+      raw.writeHead = refuse2;
     });
     fastify.addHook("onSend", async (req, reply, payload) => {
-      const settle = settleMap.get(req);
-      if (!settle || reply.statusCode < 200 || reply.statusCode >= 300) {
+      const writers = rawWriters.get(req);
+      if (writers) {
+        const raw2 = reply.raw;
+        raw2.write = writers.write;
+        raw2.end = writers.end;
+        raw2.writeHead = writers.writeHead;
+        rawWriters.delete(req);
+      }
+      const verified = verifiedMap.get(req);
+      if (!verified) return payload;
+      let raw;
+      if (verified.scheme === "upto") {
+        raw = headerValue(reply.getHeader(SETTLE_AMOUNT_HEADER));
+        reply.removeHeader(SETTLE_AMOUNT_HEADER);
+      }
+      if (reply.statusCode < 200 || reply.statusCode >= 300) {
         return payload;
       }
+      let settleOptions;
+      if (verified.scheme === "upto") {
+        const resolved = resolveSettleAmount(
+          raw,
+          verified.maxAmount,
+          verified.decimals
+        );
+        if (resolved.kind === "invalid") {
+          return refuse(reply, INVALID_SETTLE_AMOUNT_RESPONSE);
+        }
+        if (resolved.kind === "skip") return payload;
+        settleOptions = { amount: resolved.amount };
+      }
       let settled = false;
       try {
-        const settleResponse = await settle();
+        const settleResponse = settleOptions ? await verified.settle(settleOptions) : await verified.settle();
         if (settleResponse.success) {
           reply.header("payment-response", encodeBase64(settleResponse));
           reply.header("access-control-expose-headers", "payment-response");
@@ -55,14 +108,10 @@ function paymentMiddleware(config) {
       } catch {
       }
       if (!settled) {
-        const body = JSON.stringify({
+        return refuse(reply, {
           error: "PAYMENT_SETTLEMENT_FAILED",
           message: "Payment could not be confirmed after multiple attempts. Please retry."
         });
-        reply.status(402);
-        reply.header("Content-Type", "application/json");
-        reply.header("Content-Length", Buffer.byteLength(body));
-        return body;
       }
       return payload;
     });

package/dist/hono.cjs

@@ -1,7 +1,6 @@
 'use strict';
 
-var chunkXUNNMCO5_cjs = require('./chunk-XUNNMCO5.cjs');
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkK6QETMQA_cjs = require('./chunk-K6QETMQA.cjs');
 
 // src/hono/adapter.ts
 var TIMEOUT_BODY = JSON.stringify({
@@ -27,13 +26,16 @@ var HonoAdapter = class {
   getUrl() {
     return this.c.req.url;
   }
-  async runHandler() {
-    const outcome = await chunkXUNNMCO5_cjs.raceTimeout(this.next());
-    if (outcome === chunkXUNNMCO5_cjs.HANDLER_TIMEOUT) {
+  async runHandler(options) {
+    const outcome = await chunkK6QETMQA_cjs.raceTimeout(this.next(), options?.timeoutMs);
+    if (outcome === chunkK6QETMQA_cjs.HANDLER_TIMEOUT) {
       return {
         status: 504,
         setResponseHeader: () => {
         },
+        getResponseHeader: () => void 0,
+        removeResponseHeader: () => {
+        },
         sendResponse: () => {
           this.c.res = new Response(TIMEOUT_BODY, {
             status: 504,
@@ -48,6 +50,8 @@ var HonoAdapter = class {
     return {
       status: res.status,
       setResponseHeader: (name, value) => res.headers.set(name, value),
+      getResponseHeader: (name) => res.headers.get(name) ?? void 0,
+      removeResponseHeader: (name) => res.headers.delete(name),
       sendResponse: () => {
       },
       discardResponse: () => {
@@ -58,7 +62,7 @@ var HonoAdapter = class {
 
 // src/hono/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkKQPIZ6SZ_cjs.createPaymentMiddleware(config);
+  const middleware = chunkK6QETMQA_cjs.createPaymentMiddleware(config);
   return async (c, next) => {
     const result = await middleware(new HonoAdapter(c, next));
     if ("pass" in result) {

package/dist/hono.d.cts

@@ -1,5 +1,5 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.cjs';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.cjs';
 import 'viem';
 
 declare class HonoAdapter implements HTTPAdapter {
@@ -10,7 +10,7 @@ declare class HonoAdapter implements HTTPAdapter {
     getMethod(): string;
     getPath(): string;
     getUrl(): string;
-    runHandler(): Promise<RunHandlerResult>;
+    runHandler(options?: RunHandlerOptions): Promise<RunHandlerResult>;
 }
 
 declare function paymentMiddleware(config: PaymentMiddlewareConfig): MiddlewareHandler;

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { H as HTTPAdapter, R as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CUi55YSx.js';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.js';
 import 'viem';
 
 declare class HonoAdapter implements HTTPAdapter {
@@ -10,7 +10,7 @@ declare class HonoAdapter implements HTTPAdapter {
     getMethod(): string;
     getPath(): string;
     getUrl(): string;
-    runHandler(): Promise<RunHandlerResult>;
+    runHandler(options?: RunHandlerOptions): Promise<RunHandlerResult>;
 }
 
 declare function paymentMiddleware(config: PaymentMiddlewareConfig): MiddlewareHandler;

package/dist/hono.js

@@ -1,5 +1,4 @@
-import { raceTimeout, HANDLER_TIMEOUT } from './chunk-2UEAVMCH.js';
-import { createPaymentMiddleware } from './chunk-75GLDK7L.js';
+import { raceTimeout, HANDLER_TIMEOUT, createPaymentMiddleware } from './chunk-TLCEPWQI.js';
 
 // src/hono/adapter.ts
 var TIMEOUT_BODY = JSON.stringify({
@@ -25,13 +24,16 @@ var HonoAdapter = class {
   getUrl() {
     return this.c.req.url;
   }
-  async runHandler() {
-    const outcome = await raceTimeout(this.next());
+  async runHandler(options) {
+    const outcome = await raceTimeout(this.next(), options?.timeoutMs);
     if (outcome === HANDLER_TIMEOUT) {
       return {
         status: 504,
         setResponseHeader: () => {
         },
+        getResponseHeader: () => void 0,
+        removeResponseHeader: () => {
+        },
         sendResponse: () => {
           this.c.res = new Response(TIMEOUT_BODY, {
             status: 504,
@@ -46,6 +48,8 @@ var HonoAdapter = class {
     return {
       status: res.status,
       setResponseHeader: (name, value) => res.headers.set(name, value),
+      getResponseHeader: (name) => res.headers.get(name) ?? void 0,
+      removeResponseHeader: (name) => res.headers.delete(name),
       sendResponse: () => {
       },
       discardResponse: () => {

package/dist/index.cjs

@@ -1,54 +1,62 @@
 'use strict';
 
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkK6QETMQA_cjs = require('./chunk-K6QETMQA.cjs');
 
 
 
 Object.defineProperty(exports, "FacilitatorClient", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.FacilitatorClient; }
+  get: function () { return chunkK6QETMQA_cjs.FacilitatorClient; }
 });
 Object.defineProperty(exports, "PARALLEL_TOKENS", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.PARALLEL_TOKENS; }
+  get: function () { return chunkK6QETMQA_cjs.PARALLEL_TOKENS; }
+});
+Object.defineProperty(exports, "SETTLE_AMOUNT_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK6QETMQA_cjs.SETTLE_AMOUNT_HEADER; }
 });
 Object.defineProperty(exports, "X402ConfigError", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402ConfigError; }
+  get: function () { return chunkK6QETMQA_cjs.X402ConfigError; }
 });
 Object.defineProperty(exports, "X402RuntimeError", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402RuntimeError; }
+  get: function () { return chunkK6QETMQA_cjs.X402RuntimeError; }
 });
 Object.defineProperty(exports, "X402_ERROR_CODES", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402_ERROR_CODES; }
+  get: function () { return chunkK6QETMQA_cjs.X402_ERROR_CODES; }
 });
 Object.defineProperty(exports, "createPaymentGate", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.createPaymentGate; }
+  get: function () { return chunkK6QETMQA_cjs.createPaymentGate; }
 });
 Object.defineProperty(exports, "createPaymentMiddleware", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.createPaymentMiddleware; }
+  get: function () { return chunkK6QETMQA_cjs.createPaymentMiddleware; }
 });
 Object.defineProperty(exports, "encodeBase64", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.encodeBase64; }
+  get: function () { return chunkK6QETMQA_cjs.encodeBase64; }
 });
 Object.defineProperty(exports, "getDefaultAcceptedTokens", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.getDefaultAcceptedTokens; }
+  get: function () { return chunkK6QETMQA_cjs.getDefaultAcceptedTokens; }
 });
 Object.defineProperty(exports, "parsePrice", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.parsePrice; }
+  get: function () { return chunkK6QETMQA_cjs.parsePrice; }
+});
+Object.defineProperty(exports, "resolveSettleAmount", {
+  enumerable: true,
+  get: function () { return chunkK6QETMQA_cjs.resolveSettleAmount; }
 });
 Object.defineProperty(exports, "toEip155Network", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.toEip155Network; }
+  get: function () { return chunkK6QETMQA_cjs.toEip155Network; }
 });
 Object.defineProperty(exports, "validateAddress", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.validateAddress; }
+  get: function () { return chunkK6QETMQA_cjs.validateAddress; }
 });

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-import { F as FacilitatorConfig, a as FacilitatorPaymentRequirements, b as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, c as PaymentGateResult, M as MiddlewareResult, d as PassResult } from './types-CUi55YSx.cjs';
-export { e as PaymentConfirmation, f as PaymentFailure, g as PaymentRequired, h as PaymentRequirements, i as ResourceInfo, j as RouteConfig, R as RunHandlerResult } from './types-CUi55YSx.cjs';
+import { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, S as SettleOptions, c as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, d as PaymentGateResult, M as MiddlewareResult, e as PassResult } from './types-CBzm5CtM.cjs';
+export { f as PaymentConfirmation, g as PaymentFailure, h as PaymentRequired, i as PaymentRequirements, j as ResourceInfo, k as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult, V as VerifiedPayment } from './types-CBzm5CtM.cjs';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
     private readonly config;
     constructor(config: FacilitatorConfig);
     verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<FacilitatorResponse>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -25,6 +25,31 @@ declare class X402RuntimeError extends Error {
     constructor(code: string);
 }
 
+/**
+ * Response header a handler on a metered (`upto`) route sets to the amount it
+ * actually charges, in whole token units like `price` ("0.75"). Read and
+ * stripped by the middleware before the response leaves. Absent → the cap is
+ * charged; "0" → the request is served for free (no settlement).
+ */
+declare const SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+type SettleAmountResolution = {
+    kind: "settle";
+    amount: string;
+} | {
+    kind: "skip";
+} | {
+    kind: "invalid";
+    reason: "malformed" | "precision" | "above-cap";
+};
+/**
+ * Turns the handler's `payment-settle-amount` header into a settle decision.
+ * A malformed value, one carrying more decimals than the token has, or one
+ * above the signed cap is a merchant bug: the payment fails closed rather than
+ * charging something the handler did not mean. Only an explicit zero skips
+ * the settlement — a positive amount the token cannot represent is never
+ * silently served for free.
+ */
+declare function resolveSettleAmount(raw: string | undefined, maxAmount: bigint, decimals: number): SettleAmountResolution;
 declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod">) => Promise<PaymentGateResult>;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
@@ -49,4 +74,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress };
+export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { F as FacilitatorConfig, a as FacilitatorPaymentRequirements, b as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, c as PaymentGateResult, M as MiddlewareResult, d as PassResult } from './types-CUi55YSx.js';
-export { e as PaymentConfirmation, f as PaymentFailure, g as PaymentRequired, h as PaymentRequirements, i as ResourceInfo, j as RouteConfig, R as RunHandlerResult } from './types-CUi55YSx.js';
+import { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, S as SettleOptions, c as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, d as PaymentGateResult, M as MiddlewareResult, e as PassResult } from './types-CBzm5CtM.js';
+export { f as PaymentConfirmation, g as PaymentFailure, h as PaymentRequired, i as PaymentRequirements, j as ResourceInfo, k as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult, V as VerifiedPayment } from './types-CBzm5CtM.js';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
     private readonly config;
     constructor(config: FacilitatorConfig);
     verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<FacilitatorResponse>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -25,6 +25,31 @@ declare class X402RuntimeError extends Error {
     constructor(code: string);
 }
 
+/**
+ * Response header a handler on a metered (`upto`) route sets to the amount it
+ * actually charges, in whole token units like `price` ("0.75"). Read and
+ * stripped by the middleware before the response leaves. Absent → the cap is
+ * charged; "0" → the request is served for free (no settlement).
+ */
+declare const SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+type SettleAmountResolution = {
+    kind: "settle";
+    amount: string;
+} | {
+    kind: "skip";
+} | {
+    kind: "invalid";
+    reason: "malformed" | "precision" | "above-cap";
+};
+/**
+ * Turns the handler's `payment-settle-amount` header into a settle decision.
+ * A malformed value, one carrying more decimals than the token has, or one
+ * above the signed cap is a merchant bug: the payment fails closed rather than
+ * charging something the handler did not mean. Only an explicit zero skips
+ * the settlement — a positive amount the token cannot represent is never
+ * silently served for free.
+ */
+declare function resolveSettleAmount(raw: string | undefined, maxAmount: bigint, decimals: number): SettleAmountResolution;
 declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod">) => Promise<PaymentGateResult>;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
@@ -49,4 +74,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress };
+export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/index.js

@@ -1 +1 @@
-export { FacilitatorClient, PARALLEL_TOKENS, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress } from './chunk-75GLDK7L.js';
+export { FacilitatorClient, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveSettleAmount, toEip155Network, validateAddress } from './chunk-TLCEPWQI.js';