refund without paid request

Author: phdargen

e2e/clients/axios/index.ts

@@ -111,11 +111,9 @@ if (avmSigner) {
 
 const axiosWithPayment = wrapAxiosWithPayment(axios.create(), client);
 
-// Multi-request scenarios (used by batch-settlement) issue several paid requests
-// against the same endpoint so the server can amortise on-chain claims, then
-// optionally signal a cooperative refund on the last request.
+// Multi-request scenarios (used by batch-settlement) 
 const numberOfRequests = Number.parseInt(process.env.MULTI_REQUEST_COUNT ?? "1", 10);
-const refundOnLastRequest = process.env.REFUND_ON_LAST === "true";
+const refundAfterRequests = process.env.REFUND_ON_LAST ?? "true";
 
 /**
  * Issues a single paid request and returns the parsed result.
@@ -147,21 +145,19 @@ async function issueRequest(): Promise<{
 
 try {
   const results: Awaited<ReturnType<typeof issueRequest>>[] = [];
-  let lastChannelId: string | undefined;
   for (let i = 0; i < numberOfRequests; i++) {
-    const isLast = i === numberOfRequests - 1;
-
-    if (isLast && refundOnLastRequest && lastChannelId) {
-      batchSettlementScheme.requestRefund(lastChannelId);
-    }
-
     const result = await issueRequest();
     results.push(result);
+  }
 
-    const channelId = result.payment_response?.extra?.channelId;
-    if (typeof channelId === "string" && channelId.length > 0) {
-      lastChannelId = channelId;
-    }
+  if (refundAfterRequests) {
+    const refundSettle = await batchSettlementScheme.refund(url);
+    results.push({
+      success: refundSettle.success,
+      data: { refund: true },
+      status_code: 200,
+      payment_response: refundSettle,
+    });
   }
 
   const last = results[results.length - 1]!;

e2e/clients/fetch/index.ts

@@ -106,11 +106,9 @@ if (avmSigner) {
 const fetchWithPayment = wrapFetchWithPayment(fetch, client);
 const httpClient = new x402HTTPClient(client);
 
-// Multi-request scenarios (used by batch-settlement) issue several paid requests
-// against the same endpoint so the server can amortise on-chain claims, then
-// optionally signal a cooperative refund on the last request.
+// Multi-request scenarios (used by batch-settlement) 
 const numberOfRequests = Number.parseInt(process.env.MULTI_REQUEST_COUNT ?? "1", 10);
-const refundOnLastRequest = process.env.REFUND_ON_LAST === "true";
+const refundAfterRequests = process.env.REFUND_ON_LAST ?? "true";
 
 /**
  * Issues a single paid request and returns the parsed result.
@@ -140,21 +138,19 @@ async function issueRequest(): Promise<{
 }
 
 const results: Awaited<ReturnType<typeof issueRequest>>[] = [];
-let lastChannelId: string | undefined;
 for (let i = 0; i < numberOfRequests; i++) {
-  const isLast = i === numberOfRequests - 1;
-
-  if (isLast && refundOnLastRequest && lastChannelId) {
-    batchSettlementScheme.requestRefund(lastChannelId);
-  }
-
   const result = await issueRequest();
   results.push(result);
+}
 
-  const channelId = result.payment_response?.extra?.channelId;
-  if (typeof channelId === "string" && channelId.length > 0) {
-    lastChannelId = channelId;
-  }
+if (refundAfterRequests) {
+  const refundSettle = await batchSettlementScheme.refund(url);
+  results.push({
+    success: refundSettle.success,
+    data: { refund: true },
+    status_code: 200,
+    payment_response: refundSettle,
+  });
 }
 
 const last = results[results.length - 1]!;

examples/typescript/clients/batch-settlement/.env-local

@@ -1,6 +1,8 @@
 RESOURCE_SERVER_URL=http://localhost:4021
 ENDPOINT_PATH=/api/generate
 NUMBER_OF_REQUESTS=
+REFUND_AFTER_REQUESTS=
+REFUND_AMOUNT=
 
 EVM_PRIVATE_KEY=
 EVM_VOUCHER_SIGNER_PRIVATE_KEY=

examples/typescript/clients/batch-settlement/README.md

@@ -2,7 +2,6 @@
 
 Fetch-based client that pays for a sequence of `GET /api/generate` requests over a single payment channel using the **batch-settlement** EVM scheme. The first request opens the channel with a deposit; subsequent requests pay with a fresh cumulative voucher.
 
-Optionally requests a cooperative refund on the last call (`REFUND_ON_LAST_REQUEST=true`), which signals the server to claim outstanding vouchers and return the unclaimed balance.
 
 See the [scheme specification](../../../../specs/schemes/batch-settlement/scheme_batch_settlement_evm.md) and the [scheme README](../../../../typescript/packages/mechanisms/evm/src/batch-settlement/README.md) for protocol details.
 
@@ -50,4 +49,4 @@ pnpm start
 | `CHANNEL_SALT` | no | `bytes32` salt for channel id; change to open a fresh channel |
 | `STORAGE_DIR` | no | Persist client session state (defaults to in-memory) |
 | `NUMBER_OF_REQUESTS` | no | How many paid requests to issue (default 3) |
-| `REFUND_ON_LAST_REQUEST` | no | If `true`, request a cooperative refund on the last call |
+| `REFUND_AFTER_REQUESTS` | no | If `true`, issue a self-contained refund via `scheme.refund(url)` after the request loop |

examples/typescript/clients/batch-settlement/index.ts

@@ -32,7 +32,8 @@ const storageDir = process.env.STORAGE_DIR ?? process.env.STORAGE_DIR_DIR;
 const channelSalt = (process.env.CHANNEL_SALT ??
   "0x0000000000000000000000000000000000000000000000000000000000000000") as `0x${string}`;
 const numberOfRequests = Number(process.env.NUMBER_OF_REQUESTS ?? "3");
-const refundOnLastRequest = process.env.REFUND_ON_LAST_REQUEST === "true";
+const refundAfterRequests = process.env.REFUND_AFTER_REQUESTS === "true";
+const refundAmount = process.env.REFUND_AMOUNT;
 
 /**
  * Runs sequential paid requests against the configured resource server endpoint.
@@ -68,38 +69,42 @@ async function main(): Promise<void> {
   const fetchWithPayment = wrapFetchWithPayment(fetch, client);
   const httpClient = new x402HTTPClient(client);
 
-  let channelId: string | undefined;
-
   console.log(`Base URL: ${baseURL}, endpoint: ${endpointPath}`);
   console.log("payer:", signer.address);
   console.log("payerAuthorizer:", voucherSigner?.address ?? signer.address, "\n");
 
   for (let i = 0; i < numberOfRequests; i++) {
     const requestT0 = performance.now();
 
-    if (refundOnLastRequest && i === numberOfRequests - 1 && channelId) {
-      console.log(`REQUESTING REFUND`);
-      batchedScheme.requestRefund(channelId);
-    }
-
     const response = await fetchWithPayment(url, { method: "GET" });
     const result = await httpClient.processResponse(response);
 
     if (result.kind === "success") {
       console.log(`Request ${i + 1} — RESPONSE`);
       console.log(result.body);
       console.log(JSON.stringify(result.settleResponse, null, 2));
-      if (
-        result.settleResponse.extra &&
-        typeof result.settleResponse.extra.channelId === "string"
-      ) {
-        channelId = result.settleResponse.extra.channelId;
-      }
+    } else {
+      console.log(`Request ${i + 1} — ${result.kind}`);
+      console.log(JSON.stringify(result, null, 2));
     }
     console.log(
       `Request ${i + 1} — completed in ${formatSeconds(performance.now() - requestT0)}s\n`,
     );
   }
+
+  if (refundAfterRequests) {
+    console.log(
+      refundAmount
+        ? `REQUESTING PARTIAL REFUND of ${refundAmount} base units`
+        : "REQUESTING FULL REFUND of remaining channel balance",
+    );
+    const refundT0 = performance.now();
+    const settle = await batchedScheme.refund(url, {
+      ...(refundAmount ? { amount: refundAmount } : {}),
+    });
+    console.log(JSON.stringify(settle, null, 2));
+    console.log(`Refund completed in ${formatSeconds(performance.now() - refundT0)}s`);
+  }
 }
 
 main().catch(error => {

typescript/packages/core/src/http/x402HTTPResourceServer.ts

@@ -1,4 +1,4 @@
-import { x402ResourceServer, SettlementOverrides } from "../server";
+import { x402ResourceServer, SettlementOverrides, SkipHandlerDirective } from "../server";
 import {
   decodePaymentSignatureHeader,
   encodePaymentRequiredHeader,
@@ -546,6 +546,17 @@ export class x402HTTPResourceServer {
         };
       }
 
+      // Bypass the resource handler
+      if (verifyResult.skipHandler) {
+        return await this.processSkipHandlerSettlement(
+          paymentPayload,
+          matchingRequirements,
+          routeConfig.extensions,
+          transportContext,
+          verifyResult.skipHandler,
+        );
+      }
+
       // Payment is valid, return data needed for settlement
       return {
         type: "payment-verified",
@@ -694,6 +705,56 @@ export class x402HTTPResourceServer {
     return this.getRouteConfig(context.path, method) !== undefined;
   }
 
+  /**
+   * Settle a verified payment that requested `skipHandler`, packaging the
+   * result as a `payment-error` HTTPProcessResult so framework adapters can
+   * write the response without invoking the route handler.
+   *
+   * - On success: status 200 + PAYMENT-RESPONSE header + configured body.
+   * - On failure: the standard 402 settlement-failure response.
+   *
+   * @param paymentPayload - Verified payment payload.
+   * @param requirements - Matched payment requirements.
+   * @param declaredExtensions - Optional declared extensions for the route.
+   * @param transportContext - Optional HTTP transport context.
+   * @param skipHandlerResponse - Optional content type + body to return on success.
+   * @returns A `payment-error` HTTPProcessResult carrying the final response.
+   */
+  private async processSkipHandlerSettlement(
+    paymentPayload: PaymentPayload,
+    requirements: PaymentRequirements,
+    declaredExtensions: Record<string, unknown> | undefined,
+    transportContext: HTTPTransportContext,
+    skipHandlerResponse: SkipHandlerDirective | undefined,
+  ): Promise<HTTPProcessResult> {
+    const settleResult = await this.processSettlement(
+      paymentPayload,
+      requirements,
+      declaredExtensions,
+      transportContext,
+    );
+
+    if (!settleResult.success) {
+      return { type: "payment-error", response: settleResult.response };
+    }
+
+    const contentType = skipHandlerResponse?.contentType ?? "application/json";
+    const body = skipHandlerResponse?.body ?? {};
+
+    return {
+      type: "payment-error",
+      response: {
+        status: 200,
+        headers: {
+          "Content-Type": contentType,
+          ...settleResult.headers,
+        },
+        body,
+        isHtml: contentType.includes("text/html"),
+      },
+    };
+  }
+
   /**
    * Build HTTPResponseInstructions for settlement failure.
    * Uses settlementFailedResponseBody hook if configured, otherwise defaults to empty body.

typescript/packages/core/src/server/index.ts

@@ -9,6 +9,7 @@ export type {
   SettleResultContext,
   SettleFailureContext,
   SettlementOverrides,
+  SkipHandlerDirective,
   BeforeVerifyHook,
   AfterVerifyHook,
   OnVerifyFailureHook,

typescript/packages/core/src/server/x402ResourceServer.ts

@@ -51,6 +51,16 @@ export interface VerifyResultContext extends VerifyContext {
   result: VerifyResponse;
 }
 
+/**
+ * Optional acknowledgement body returned to the caller when an `AfterVerifyHook`
+ * requests that the resource handler be skipped for a self-contained operation
+ * (e.g. cooperative refund). Travels in-process only — never on the facilitator wire.
+ */
+export interface SkipHandlerDirective {
+  contentType?: string;
+  body?: unknown;
+}
+
 export interface VerifyFailureContext extends VerifyContext {
   error: Error;
 }
@@ -77,7 +87,9 @@ export type BeforeVerifyHook = (
   context: VerifyContext,
 ) => Promise<void | { abort: true; reason: string; message?: string }>;
 
-export type AfterVerifyHook = (context: VerifyResultContext) => Promise<void>;
+export type AfterVerifyHook = (
+  context: VerifyResultContext,
+) => Promise<void | { skipHandler: true; response?: SkipHandlerDirective }>;
 
 export type OnVerifyFailureHook = (
   context: VerifyFailureContext,
@@ -678,16 +690,22 @@ export class x402ResourceServer {
   }
 
   /**
-   * Verify a payment against requirements
+   * Verify a payment against requirements.
+   *
+   * The returned object is a {@link VerifyResponse} (the wire-level type),
+   * optionally extended with an in-process `skipHandler` directive when an
+   * `AfterVerifyHook` requested that the resource handler be bypassed. The
+   * extra property is invisible to callers that only read standard fields and
+   * is never serialized to the facilitator wire.
    *
    * @param paymentPayload - The payment payload to verify
    * @param requirements - The payment requirements
-   * @returns Verification response
+   * @returns Verification response, optionally carrying a `skipHandler` directive
    */
   async verifyPayment(
     paymentPayload: PaymentPayload,
     requirements: PaymentRequirements,
-  ): Promise<VerifyResponse> {
+  ): Promise<VerifyResponse & { skipHandler?: SkipHandlerDirective }> {
     const context: VerifyContext = {
       paymentPayload,
       requirements,
@@ -749,17 +767,26 @@ export class x402ResourceServer {
         verifyResult = await facilitatorClient.verify(paymentPayload, requirements);
       }
 
-      // Execute afterVerify hooks
+      // Execute afterVerify hooks. The last hook to return a `skipHandler`
+      // directive wins; this lets schemes signal that a self-contained
+      // operation (e.g. cooperative refund) should bypass the resource
+      // handler and settle inline. The directive is attached as an extra
+      // optional property on the returned response — the wire-level
+      // `VerifyResponse` is never modified.
       const resultContext: VerifyResultContext = {
         ...context,
         result: verifyResult,
       };
 
+      let skipHandler: SkipHandlerDirective | undefined;
       for (const hook of this.afterVerifyHooks) {
-        await hook(resultContext);
+        const directive = await hook(resultContext);
+        if (directive && "skipHandler" in directive && directive.skipHandler) {
+          skipHandler = directive.response ?? {};
+        }
       }
 
-      return verifyResult;
+      return skipHandler ? { ...verifyResult, skipHandler } : verifyResult;
     } catch (error) {
       const failureContext: VerifyFailureContext = {
         ...context,