@agentcash/router 1.10.3 → 1.10.5

package/dist/index.cjs

@@ -541,7 +541,8 @@ var HEADERS = {
   X402_PAYMENT_LEGACY: "X-PAYMENT",
   X402_PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
   X402_PAYMENT_RESPONSE: "PAYMENT-RESPONSE",
-  MPP_PAYMENT_RECEIPT: "Payment-Receipt"
+  MPP_PAYMENT_RECEIPT: "Payment-Receipt",
+  REQUEST_ID: "X-Request-ID"
 };
 var AUTH_SCHEME = {
   BEARER: "Bearer ",
@@ -571,19 +572,19 @@ function firePluginHook(plugin, method, ...args) {
     const result = fn.apply(plugin, args);
     if (result && typeof result.catch === "function") {
       result.catch((error) => {
-        console.error(
-          `[router] ERROR ${method}: ${error instanceof Error ? error.message : String(error)}`
-        );
+        console.error(`[router] ERROR ${method}: ${formatUnknownError(error)}`);
       });
     }
     return result;
   } catch (error) {
-    console.error(
-      `[router] ERROR ${method}: ${error instanceof Error ? error.message : String(error)}`
-    );
+    console.error(`[router] ERROR ${method}: ${formatUnknownError(error)}`);
     return void 0;
   }
 }
+function formatUnknownError(error) {
+  if (error instanceof Error) return error.stack ?? error.message;
+  return String(error);
+}
 
 // src/plugin/reporter.ts
 function createReporter(plugin, pluginCtx, route) {
@@ -674,7 +675,8 @@ function firePaymentVerified(ctx, event) {
 function firePaymentSettled(ctx, event) {
   firePluginHook(ctx.deps.plugin, "onPaymentSettled", ctx.pluginCtx, event);
 }
-function firePluginResponse(ctx, response, requestBody, responseBody) {
+function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
+  attachRequestId(response, ctx.meta.requestId);
   firePluginHook(ctx.deps.plugin, "onResponse", ctx.pluginCtx, {
     statusCode: response.status,
     statusText: response.statusText,
@@ -685,11 +687,9 @@ function firePluginResponse(ctx, response, requestBody, responseBody) {
     responseBody
   });
   if (response.status >= 400 && response.status !== 402) {
-    firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, {
-      status: response.status,
-      message: response.statusText || `HTTP ${response.status}`,
-      settled: false
-    });
+    const error = buildErrorEvent(ctx, response, failure);
+    if (response.status >= 500) logRouterFailure(error);
+    firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, error);
   }
 }
 function fireProviderQuota(ctx, response, handlerResult) {
@@ -721,6 +721,67 @@ function computeQuotaLevel(remaining, warn, critical) {
   if (warn !== void 0 && remaining <= warn) return "warn";
   return "healthy";
 }
+function attachRequestId(response, requestId) {
+  try {
+    if (!response.headers.has(HEADERS.REQUEST_ID)) {
+      response.headers.set(HEADERS.REQUEST_ID, requestId);
+    }
+  } catch {
+  }
+}
+function buildErrorEvent(ctx, response, failure) {
+  const error = errorDetails(failure?.cause);
+  const responseMessage = response.statusText || `HTTP ${response.status}`;
+  const message = failure?.message ?? error.message ?? responseMessage;
+  return {
+    status: response.status,
+    message,
+    settled: failure?.settled ?? false,
+    requestId: ctx.meta.requestId,
+    route: ctx.meta.route,
+    method: ctx.meta.method,
+    duration: Date.now() - ctx.meta.startTime,
+    walletAddress: ctx.meta.walletAddress,
+    verifiedWallet: ctx.pluginCtx.verifiedWallet,
+    clientId: ctx.meta.clientId,
+    sessionId: ctx.meta.sessionId,
+    errorName: error.name,
+    stack: error.stack,
+    cause: failure?.cause
+  };
+}
+function errorDetails(error) {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    };
+  }
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    return {
+      message: typeof record.message === "string" ? record.message : void 0,
+      name: typeof record.name === "string" ? record.name : void 0,
+      stack: typeof record.stack === "string" ? record.stack : void 0
+    };
+  }
+  if (typeof error === "string") return { message: error };
+  return {};
+}
+function logRouterFailure(error) {
+  console.error(`[router] ERROR ${error.route ?? "unknown"} ${error.status}: ${error.message}`, {
+    requestId: error.requestId,
+    method: error.method,
+    duration: error.duration,
+    walletAddress: error.walletAddress,
+    verifiedWallet: error.verifiedWallet,
+    clientId: error.clientId,
+    sessionId: error.sessionId,
+    errorName: error.errorName,
+    stack: error.stack
+  });
+}
 
 // src/pipeline/steps/parse-body.ts
 async function parseBody(ctx, request = ctx.request) {
@@ -730,20 +791,19 @@ async function parseBody(ctx, request = ctx.request) {
     raw = await bufferBody(request);
   } catch (err) {
     if (!(err instanceof MalformedJsonError)) throw err;
-    const response2 = import_server.NextResponse.json(
-      { success: false, error: "Invalid JSON", issues: [] },
-      { status: 400 }
-    );
-    firePluginResponse(ctx, response2);
+    const responseBody2 = { success: false, error: "Invalid JSON", issues: [] };
+    const response2 = import_server.NextResponse.json(responseBody2, { status: 400 });
+    firePluginResponse(ctx, response2, void 0, responseBody2, {
+      message: responseBody2.error,
+      cause: err
+    });
     return { ok: false, response: response2 };
   }
   const result = validateBody(raw, ctx.routeEntry.bodySchema);
   if (result.success) return { ok: true, data: result.data };
-  const response = import_server.NextResponse.json(
-    { success: false, error: result.error, issues: result.issues },
-    { status: 400 }
-  );
-  firePluginResponse(ctx, response);
+  const responseBody = { success: false, error: result.error, issues: result.issues };
+  const response = import_server.NextResponse.json(responseBody, { status: 400 });
+  firePluginResponse(ctx, response, raw, responseBody, { message: result.error });
   return { ok: false, response };
 }
 
@@ -755,11 +815,9 @@ function validateQuery(ctx) {
   const params = Object.fromEntries(ctx.request.nextUrl.searchParams.entries());
   const result = validateBody(params, querySchema);
   if (result.success) return { ok: true, data: result.data };
-  const response = import_server2.NextResponse.json(
-    { success: false, error: result.error, issues: result.issues },
-    { status: 400 }
-  );
-  firePluginResponse(ctx, response);
+  const responseBody = { success: false, error: result.error, issues: result.issues };
+  const response = import_server2.NextResponse.json(responseBody, { status: 400 });
+  firePluginResponse(ctx, response, params, responseBody, { message: result.error });
   return { ok: false, response };
 }
 
@@ -778,9 +836,13 @@ function handlerFailureError(response) {
 
 // src/pipeline/steps/fail.ts
 var import_server3 = require("next/server");
-function fail(ctx, status, message, requestBody) {
-  const response = import_server3.NextResponse.json({ success: false, error: message }, { status });
-  firePluginResponse(ctx, response, requestBody);
+function fail(ctx, status, message, requestBody, failure) {
+  const responseBody = { success: false, error: message };
+  const response = import_server3.NextResponse.json(responseBody, { status });
+  firePluginResponse(ctx, response, requestBody, responseBody, {
+    ...failure,
+    message: failure?.message ?? message
+  });
   return response;
 }
 
@@ -856,9 +918,10 @@ async function runHandler(ctx, handlerCtx) {
 function errorResult(error) {
   const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
   const message = error instanceof Error ? error.message : "Internal error";
+  const responseBody = { success: false, error: message };
   return {
-    response: import_server4.NextResponse.json({ success: false, error: message }, { status }),
-    rawResult: void 0,
+    response: import_server4.NextResponse.json(responseBody, { status }),
+    rawResult: responseBody,
     handlerError: error
   };
 }
@@ -870,9 +933,9 @@ function isThenable(value) {
 }
 
 // src/pipeline/steps/finalize/response.ts
-function finalize(ctx, response, rawResult, requestBody) {
+function finalize(ctx, response, rawResult, requestBody, failure) {
   fireProviderQuota(ctx, response, rawResult);
-  firePluginResponse(ctx, response, requestBody, rawResult);
+  firePluginResponse(ctx, response, requestBody, rawResult, failure);
   return response;
 }
 
@@ -958,7 +1021,9 @@ async function settleAndFinalizeRequest(args) {
   });
   if (!settle.ok) {
     if (onSettleError) await onSettleError(settle.error, settle.failMessage);
-    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body);
+    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body, {
+      cause: settle.error
+    });
   }
   return runPostSettleEpilogue({
     ctx,
@@ -993,7 +1058,9 @@ async function settleAndFinalizeStream(args) {
     report
   });
   if (!settle.ok) {
-    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body);
+    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body, {
+      cause: settle.error
+    });
   }
   return runPostSettleEpilogue({
     ctx,
@@ -1020,7 +1087,13 @@ async function runHandlerOnly(ctx, wallet, account) {
   const validateErr = await runValidate(ctx, body.data);
   if (validateErr) return validateErr;
   const result = await invokeUnauthed(ctx, wallet, account, body.data);
-  return finalize(ctx, result.response, result.rawResult, body.data);
+  return finalize(
+    ctx,
+    result.response,
+    result.rawResult,
+    body.data,
+    result.handlerError === void 0 ? void 0 : { cause: result.handlerError }
+  );
 }
 
 // src/pipeline/steps/run-before-settle.ts
@@ -2033,6 +2106,7 @@ function invalidPaymentVerification(failure) {
 }
 
 // src/protocols/x402/strategy.ts
+var SETTLE_RETRY_DELAYS_MS = [500, 1e3];
 function formatVerifyFailureMessage(failure) {
   if (failure.reason === "permit2_allowance_required") {
     const wallet = failure.payer ?? "<the payer wallet>";
@@ -2123,7 +2197,17 @@ async function settleX402(args) {
   const { payload, requirements } = token;
   const override = routeEntry.billing === "exact" ? void 0 : { amount: billedAmount };
   try {
-    const settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    let settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    for (let attempt = 0; !settle.result?.success && attempt < SETTLE_RETRY_DELAYS_MS.length; attempt++) {
+      report("warn", "Retrying x402 settlement", {
+        attempt: attempt + 1,
+        errorReason: settle.result?.errorReason
+      });
+      await new Promise((resolve) => {
+        setTimeout(resolve, SETTLE_RETRY_DELAYS_MS[attempt]);
+      });
+      settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    }
     if (!settle.result?.success) {
       throw Object.assign(
         new Error(settle.result?.errorReason ?? "x402 settlement returned success=false"),
@@ -2459,11 +2543,9 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     challengePrice = pricing ? await pricing.challengeQuote(body) : "0";
   } catch (err) {
     const message = errorMessage(err, "Price calculation failed");
-    const errorResponse = import_server5.NextResponse.json(
-      { success: false, error: message },
-      { status: errorStatus(err, 500) }
-    );
-    firePluginResponse(ctx, errorResponse);
+    const responseBody2 = { success: false, error: message };
+    const errorResponse = import_server5.NextResponse.json(responseBody2, { status: errorStatus(err, 500) });
+    firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
@@ -2495,11 +2577,9 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
       if (strategy.protocol === "x402") {
-        const errorResponse = import_server5.NextResponse.json(
-          { success: false, error: message },
-          { status: 500 }
-        );
-        firePluginResponse(ctx, errorResponse);
+        const responseBody2 = { success: false, error: message };
+        const errorResponse = import_server5.NextResponse.json(responseBody2, { status: 500 });
+        firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
         return errorResponse;
       }
     }
@@ -2658,10 +2738,11 @@ function toResponse(rawResult) {
 function errorResult2(error) {
   const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
   const message = error instanceof Error ? error.message : "Internal error";
+  const responseBody = { success: false, error: message };
   return {
     kind: "request",
-    response: import_server7.NextResponse.json({ success: false, error: message }, { status }),
-    rawResult: void 0,
+    response: import_server7.NextResponse.json(responseBody, { status }),
+    rawResult: responseBody,
     handlerError: error
   };
 }
@@ -2792,7 +2873,13 @@ async function runDynamicRequestFlow(args) {
     handlerError: result.handlerError
   };
   if (result.response.status >= 400) {
-    return finalize(ctx, result.response, result.rawResult, body);
+    return finalize(
+      ctx,
+      result.response,
+      result.rawResult,
+      body,
+      failureFromCause(result.handlerError)
+    );
   }
   const beforeErr = await runBeforeSettle(ctx, settleScope);
   if (beforeErr) return beforeErr;
@@ -2814,6 +2901,9 @@ async function runDynamicRequestFlow(args) {
     }
   });
 }
+function failureFromCause(cause) {
+  return cause === void 0 ? void 0 : { cause };
+}
 function computeBilledAmount(routeEntry, result) {
   if (routeEntry.billing === "upto") {
     const total = result.uptoContext?.atomicTotal() ?? 0n;
@@ -2978,7 +3068,13 @@ async function runStaticRequestFlow(args) {
     if (result.response.status >= 400) {
       const settledScope = settleScope;
       await runSettledHandlerError(ctx, settledScope);
-      return finalize(ctx, result.response, result.rawResult, body);
+      return finalize(
+        ctx,
+        result.response,
+        result.rawResult,
+        body,
+        failureFromCause2(result.handlerError)
+      );
     }
     return settleAndFinalizeRequest({
       ctx,
@@ -2991,7 +3087,13 @@ async function runStaticRequestFlow(args) {
     });
   }
   if (result.response.status >= 400) {
-    return finalize(ctx, result.response, result.rawResult, body);
+    return finalize(
+      ctx,
+      result.response,
+      result.rawResult,
+      body,
+      failureFromCause2(result.handlerError)
+    );
   }
   const beforeErr = await runBeforeSettle(ctx, settleScope);
   if (beforeErr) return beforeErr;
@@ -3012,6 +3114,9 @@ async function runStaticRequestFlow(args) {
     }
   });
 }
+function failureFromCause2(cause) {
+  return cause === void 0 ? void 0 : { cause };
+}
 
 // src/pipeline/flows/static/static-paid.ts
 async function runStaticPaidFlow(ctx) {
@@ -3496,7 +3601,8 @@ var RouteBuilder = class _RouteBuilder {
       providerConfig: void 0,
       validateFn: void 0,
       settlement: void 0,
-      mppInfo: void 0
+      mppInfo: void 0,
+      hasCheckout: false
     };
   }
   fork() {
@@ -3587,6 +3693,7 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4020,6 +4127,7 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: this.#s.validateFn,
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
+      hasCheckout: this.#s.hasCheckout ? true : void 0,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4226,6 +4334,7 @@ function buildOperation(routeKey, entry, tag) {
   const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
   const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
   const pricingInfo = buildPricingInfo(entry);
+  const hasCheckout = entry.hasCheckout === true;
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -4251,10 +4360,11 @@ function buildOperation(routeKey, entry, tag) {
       }
     }
   };
-  if (paymentRequired && (pricingInfo || protocols)) {
+  if (paymentRequired && (pricingInfo || protocols || hasCheckout)) {
     operation["x-payment-info"] = {
       ...pricingInfo ?? {},
-      ...protocols && { protocols }
+      ...protocols && { protocols },
+      ...hasCheckout && { has_checkout: true }
     };
   }
   if (requiresSiwxScheme) {

package/dist/index.d.cts

@@ -77,13 +77,24 @@ interface ResponseMeta {
     headers: Record<string, string>;
     /** Parsed request body (when .body() was used). undefined when no body was parsed. */
     requestBody?: unknown;
-    /** Handler return value. undefined for raw Response returns (streams) or error paths. */
+    /** Handler return value or structured router-generated error body. */
     responseBody?: unknown;
 }
 interface ErrorEvent {
     status: number;
     message: string;
     settled: boolean;
+    requestId?: string;
+    route?: string;
+    method?: string;
+    duration?: number;
+    walletAddress?: string | null;
+    verifiedWallet?: string | null;
+    clientId?: string | null;
+    sessionId?: string | null;
+    errorName?: string;
+    stack?: string;
+    cause?: unknown;
 }
 interface AuthEvent {
     /** Authentication mode that was verified */
@@ -216,6 +227,8 @@ interface PaidOptions {
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
+    /** Signal in discovery that clients should use an explicit checkout flow before payment. */
+    checkout?: boolean;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -360,6 +373,7 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
+    hasCheckout?: boolean;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -543,7 +557,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`) live
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
      * alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *

package/dist/index.d.ts

@@ -77,13 +77,24 @@ interface ResponseMeta {
     headers: Record<string, string>;
     /** Parsed request body (when .body() was used). undefined when no body was parsed. */
     requestBody?: unknown;
-    /** Handler return value. undefined for raw Response returns (streams) or error paths. */
+    /** Handler return value or structured router-generated error body. */
     responseBody?: unknown;
 }
 interface ErrorEvent {
     status: number;
     message: string;
     settled: boolean;
+    requestId?: string;
+    route?: string;
+    method?: string;
+    duration?: number;
+    walletAddress?: string | null;
+    verifiedWallet?: string | null;
+    clientId?: string | null;
+    sessionId?: string | null;
+    errorName?: string;
+    stack?: string;
+    cause?: unknown;
 }
 interface AuthEvent {
     /** Authentication mode that was verified */
@@ -216,6 +227,8 @@ interface PaidOptions {
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
+    /** Signal in discovery that clients should use an explicit checkout flow before payment. */
+    checkout?: boolean;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -360,6 +373,7 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
+    hasCheckout?: boolean;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -543,7 +557,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`) live
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
      * alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *

package/dist/index.js

@@ -499,7 +499,8 @@ var HEADERS = {
   X402_PAYMENT_LEGACY: "X-PAYMENT",
   X402_PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
   X402_PAYMENT_RESPONSE: "PAYMENT-RESPONSE",
-  MPP_PAYMENT_RECEIPT: "Payment-Receipt"
+  MPP_PAYMENT_RECEIPT: "Payment-Receipt",
+  REQUEST_ID: "X-Request-ID"
 };
 var AUTH_SCHEME = {
   BEARER: "Bearer ",
@@ -529,19 +530,19 @@ function firePluginHook(plugin, method, ...args) {
     const result = fn.apply(plugin, args);
     if (result && typeof result.catch === "function") {
       result.catch((error) => {
-        console.error(
-          `[router] ERROR ${method}: ${error instanceof Error ? error.message : String(error)}`
-        );
+        console.error(`[router] ERROR ${method}: ${formatUnknownError(error)}`);
       });
     }
     return result;
   } catch (error) {
-    console.error(
-      `[router] ERROR ${method}: ${error instanceof Error ? error.message : String(error)}`
-    );
+    console.error(`[router] ERROR ${method}: ${formatUnknownError(error)}`);
     return void 0;
   }
 }
+function formatUnknownError(error) {
+  if (error instanceof Error) return error.stack ?? error.message;
+  return String(error);
+}
 
 // src/plugin/reporter.ts
 function createReporter(plugin, pluginCtx, route) {
@@ -632,7 +633,8 @@ function firePaymentVerified(ctx, event) {
 function firePaymentSettled(ctx, event) {
   firePluginHook(ctx.deps.plugin, "onPaymentSettled", ctx.pluginCtx, event);
 }
-function firePluginResponse(ctx, response, requestBody, responseBody) {
+function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
+  attachRequestId(response, ctx.meta.requestId);
   firePluginHook(ctx.deps.plugin, "onResponse", ctx.pluginCtx, {
     statusCode: response.status,
     statusText: response.statusText,
@@ -643,11 +645,9 @@ function firePluginResponse(ctx, response, requestBody, responseBody) {
     responseBody
   });
   if (response.status >= 400 && response.status !== 402) {
-    firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, {
-      status: response.status,
-      message: response.statusText || `HTTP ${response.status}`,
-      settled: false
-    });
+    const error = buildErrorEvent(ctx, response, failure);
+    if (response.status >= 500) logRouterFailure(error);
+    firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, error);
   }
 }
 function fireProviderQuota(ctx, response, handlerResult) {
@@ -679,6 +679,67 @@ function computeQuotaLevel(remaining, warn, critical) {
   if (warn !== void 0 && remaining <= warn) return "warn";
   return "healthy";
 }
+function attachRequestId(response, requestId) {
+  try {
+    if (!response.headers.has(HEADERS.REQUEST_ID)) {
+      response.headers.set(HEADERS.REQUEST_ID, requestId);
+    }
+  } catch {
+  }
+}
+function buildErrorEvent(ctx, response, failure) {
+  const error = errorDetails(failure?.cause);
+  const responseMessage = response.statusText || `HTTP ${response.status}`;
+  const message = failure?.message ?? error.message ?? responseMessage;
+  return {
+    status: response.status,
+    message,
+    settled: failure?.settled ?? false,
+    requestId: ctx.meta.requestId,
+    route: ctx.meta.route,
+    method: ctx.meta.method,
+    duration: Date.now() - ctx.meta.startTime,
+    walletAddress: ctx.meta.walletAddress,
+    verifiedWallet: ctx.pluginCtx.verifiedWallet,
+    clientId: ctx.meta.clientId,
+    sessionId: ctx.meta.sessionId,
+    errorName: error.name,
+    stack: error.stack,
+    cause: failure?.cause
+  };
+}
+function errorDetails(error) {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    };
+  }
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    return {
+      message: typeof record.message === "string" ? record.message : void 0,
+      name: typeof record.name === "string" ? record.name : void 0,
+      stack: typeof record.stack === "string" ? record.stack : void 0
+    };
+  }
+  if (typeof error === "string") return { message: error };
+  return {};
+}
+function logRouterFailure(error) {
+  console.error(`[router] ERROR ${error.route ?? "unknown"} ${error.status}: ${error.message}`, {
+    requestId: error.requestId,
+    method: error.method,
+    duration: error.duration,
+    walletAddress: error.walletAddress,
+    verifiedWallet: error.verifiedWallet,
+    clientId: error.clientId,
+    sessionId: error.sessionId,
+    errorName: error.errorName,
+    stack: error.stack
+  });
+}
 
 // src/pipeline/steps/parse-body.ts
 async function parseBody(ctx, request = ctx.request) {
@@ -688,20 +749,19 @@ async function parseBody(ctx, request = ctx.request) {
     raw = await bufferBody(request);
   } catch (err) {
     if (!(err instanceof MalformedJsonError)) throw err;
-    const response2 = NextResponse.json(
-      { success: false, error: "Invalid JSON", issues: [] },
-      { status: 400 }
-    );
-    firePluginResponse(ctx, response2);
+    const responseBody2 = { success: false, error: "Invalid JSON", issues: [] };
+    const response2 = NextResponse.json(responseBody2, { status: 400 });
+    firePluginResponse(ctx, response2, void 0, responseBody2, {
+      message: responseBody2.error,
+      cause: err
+    });
     return { ok: false, response: response2 };
   }
   const result = validateBody(raw, ctx.routeEntry.bodySchema);
   if (result.success) return { ok: true, data: result.data };
-  const response = NextResponse.json(
-    { success: false, error: result.error, issues: result.issues },
-    { status: 400 }
-  );
-  firePluginResponse(ctx, response);
+  const responseBody = { success: false, error: result.error, issues: result.issues };
+  const response = NextResponse.json(responseBody, { status: 400 });
+  firePluginResponse(ctx, response, raw, responseBody, { message: result.error });
   return { ok: false, response };
 }
 
@@ -713,11 +773,9 @@ function validateQuery(ctx) {
   const params = Object.fromEntries(ctx.request.nextUrl.searchParams.entries());
   const result = validateBody(params, querySchema);
   if (result.success) return { ok: true, data: result.data };
-  const response = NextResponse2.json(
-    { success: false, error: result.error, issues: result.issues },
-    { status: 400 }
-  );
-  firePluginResponse(ctx, response);
+  const responseBody = { success: false, error: result.error, issues: result.issues };
+  const response = NextResponse2.json(responseBody, { status: 400 });
+  firePluginResponse(ctx, response, params, responseBody, { message: result.error });
   return { ok: false, response };
 }
 
@@ -736,9 +794,13 @@ function handlerFailureError(response) {
 
 // src/pipeline/steps/fail.ts
 import { NextResponse as NextResponse3 } from "next/server";
-function fail(ctx, status, message, requestBody) {
-  const response = NextResponse3.json({ success: false, error: message }, { status });
-  firePluginResponse(ctx, response, requestBody);
+function fail(ctx, status, message, requestBody, failure) {
+  const responseBody = { success: false, error: message };
+  const response = NextResponse3.json(responseBody, { status });
+  firePluginResponse(ctx, response, requestBody, responseBody, {
+    ...failure,
+    message: failure?.message ?? message
+  });
   return response;
 }
 
@@ -814,9 +876,10 @@ async function runHandler(ctx, handlerCtx) {
 function errorResult(error) {
   const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
   const message = error instanceof Error ? error.message : "Internal error";
+  const responseBody = { success: false, error: message };
   return {
-    response: NextResponse4.json({ success: false, error: message }, { status }),
-    rawResult: void 0,
+    response: NextResponse4.json(responseBody, { status }),
+    rawResult: responseBody,
     handlerError: error
   };
 }
@@ -828,9 +891,9 @@ function isThenable(value) {
 }
 
 // src/pipeline/steps/finalize/response.ts
-function finalize(ctx, response, rawResult, requestBody) {
+function finalize(ctx, response, rawResult, requestBody, failure) {
   fireProviderQuota(ctx, response, rawResult);
-  firePluginResponse(ctx, response, requestBody, rawResult);
+  firePluginResponse(ctx, response, requestBody, rawResult, failure);
   return response;
 }
 
@@ -916,7 +979,9 @@ async function settleAndFinalizeRequest(args) {
   });
   if (!settle.ok) {
     if (onSettleError) await onSettleError(settle.error, settle.failMessage);
-    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body);
+    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body, {
+      cause: settle.error
+    });
   }
   return runPostSettleEpilogue({
     ctx,
@@ -951,7 +1016,9 @@ async function settleAndFinalizeStream(args) {
     report
   });
   if (!settle.ok) {
-    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body);
+    return fail(ctx, settle.failStatus ?? 500, settle.failMessage, body, {
+      cause: settle.error
+    });
   }
   return runPostSettleEpilogue({
     ctx,
@@ -978,7 +1045,13 @@ async function runHandlerOnly(ctx, wallet, account) {
   const validateErr = await runValidate(ctx, body.data);
   if (validateErr) return validateErr;
   const result = await invokeUnauthed(ctx, wallet, account, body.data);
-  return finalize(ctx, result.response, result.rawResult, body.data);
+  return finalize(
+    ctx,
+    result.response,
+    result.rawResult,
+    body.data,
+    result.handlerError === void 0 ? void 0 : { cause: result.handlerError }
+  );
 }
 
 // src/pipeline/steps/run-before-settle.ts
@@ -1991,6 +2064,7 @@ function invalidPaymentVerification(failure) {
 }
 
 // src/protocols/x402/strategy.ts
+var SETTLE_RETRY_DELAYS_MS = [500, 1e3];
 function formatVerifyFailureMessage(failure) {
   if (failure.reason === "permit2_allowance_required") {
     const wallet = failure.payer ?? "<the payer wallet>";
@@ -2081,7 +2155,17 @@ async function settleX402(args) {
   const { payload, requirements } = token;
   const override = routeEntry.billing === "exact" ? void 0 : { amount: billedAmount };
   try {
-    const settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    let settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    for (let attempt = 0; !settle.result?.success && attempt < SETTLE_RETRY_DELAYS_MS.length; attempt++) {
+      report("warn", "Retrying x402 settlement", {
+        attempt: attempt + 1,
+        errorReason: settle.result?.errorReason
+      });
+      await new Promise((resolve) => {
+        setTimeout(resolve, SETTLE_RETRY_DELAYS_MS[attempt]);
+      });
+      settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    }
     if (!settle.result?.success) {
       throw Object.assign(
         new Error(settle.result?.errorReason ?? "x402 settlement returned success=false"),
@@ -2417,11 +2501,9 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     challengePrice = pricing ? await pricing.challengeQuote(body) : "0";
   } catch (err) {
     const message = errorMessage(err, "Price calculation failed");
-    const errorResponse = NextResponse5.json(
-      { success: false, error: message },
-      { status: errorStatus(err, 500) }
-    );
-    firePluginResponse(ctx, errorResponse);
+    const responseBody2 = { success: false, error: message };
+    const errorResponse = NextResponse5.json(responseBody2, { status: errorStatus(err, 500) });
+    firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
@@ -2453,11 +2535,9 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
       if (strategy.protocol === "x402") {
-        const errorResponse = NextResponse5.json(
-          { success: false, error: message },
-          { status: 500 }
-        );
-        firePluginResponse(ctx, errorResponse);
+        const responseBody2 = { success: false, error: message };
+        const errorResponse = NextResponse5.json(responseBody2, { status: 500 });
+        firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
         return errorResponse;
       }
     }
@@ -2616,10 +2696,11 @@ function toResponse(rawResult) {
 function errorResult2(error) {
   const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
   const message = error instanceof Error ? error.message : "Internal error";
+  const responseBody = { success: false, error: message };
   return {
     kind: "request",
-    response: NextResponse7.json({ success: false, error: message }, { status }),
-    rawResult: void 0,
+    response: NextResponse7.json(responseBody, { status }),
+    rawResult: responseBody,
     handlerError: error
   };
 }
@@ -2750,7 +2831,13 @@ async function runDynamicRequestFlow(args) {
     handlerError: result.handlerError
   };
   if (result.response.status >= 400) {
-    return finalize(ctx, result.response, result.rawResult, body);
+    return finalize(
+      ctx,
+      result.response,
+      result.rawResult,
+      body,
+      failureFromCause(result.handlerError)
+    );
   }
   const beforeErr = await runBeforeSettle(ctx, settleScope);
   if (beforeErr) return beforeErr;
@@ -2772,6 +2859,9 @@ async function runDynamicRequestFlow(args) {
     }
   });
 }
+function failureFromCause(cause) {
+  return cause === void 0 ? void 0 : { cause };
+}
 function computeBilledAmount(routeEntry, result) {
   if (routeEntry.billing === "upto") {
     const total = result.uptoContext?.atomicTotal() ?? 0n;
@@ -2936,7 +3026,13 @@ async function runStaticRequestFlow(args) {
     if (result.response.status >= 400) {
       const settledScope = settleScope;
       await runSettledHandlerError(ctx, settledScope);
-      return finalize(ctx, result.response, result.rawResult, body);
+      return finalize(
+        ctx,
+        result.response,
+        result.rawResult,
+        body,
+        failureFromCause2(result.handlerError)
+      );
     }
     return settleAndFinalizeRequest({
       ctx,
@@ -2949,7 +3045,13 @@ async function runStaticRequestFlow(args) {
     });
   }
   if (result.response.status >= 400) {
-    return finalize(ctx, result.response, result.rawResult, body);
+    return finalize(
+      ctx,
+      result.response,
+      result.rawResult,
+      body,
+      failureFromCause2(result.handlerError)
+    );
   }
   const beforeErr = await runBeforeSettle(ctx, settleScope);
   if (beforeErr) return beforeErr;
@@ -2970,6 +3072,9 @@ async function runStaticRequestFlow(args) {
     }
   });
 }
+function failureFromCause2(cause) {
+  return cause === void 0 ? void 0 : { cause };
+}
 
 // src/pipeline/flows/static/static-paid.ts
 async function runStaticPaidFlow(ctx) {
@@ -3454,7 +3559,8 @@ var RouteBuilder = class _RouteBuilder {
       providerConfig: void 0,
       validateFn: void 0,
       settlement: void 0,
-      mppInfo: void 0
+      mppInfo: void 0,
+      hasCheckout: false
     };
   }
   fork() {
@@ -3545,6 +3651,7 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -3978,6 +4085,7 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: this.#s.validateFn,
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
+      hasCheckout: this.#s.hasCheckout ? true : void 0,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4184,6 +4292,7 @@ function buildOperation(routeKey, entry, tag) {
   const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
   const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
   const pricingInfo = buildPricingInfo(entry);
+  const hasCheckout = entry.hasCheckout === true;
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -4209,10 +4318,11 @@ function buildOperation(routeKey, entry, tag) {
       }
     }
   };
-  if (paymentRequired && (pricingInfo || protocols)) {
+  if (paymentRequired && (pricingInfo || protocols || hasCheckout)) {
     operation["x-payment-info"] = {
       ...pricingInfo ?? {},
-      ...protocols && { protocols }
+      ...protocols && { protocols },
+      ...hasCheckout && { has_checkout: true }
     };
   }
   if (requiresSiwxScheme) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.10.3",
+  "version": "1.10.5",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {