@agentcash/router 1.10.2 → 1.10.4

package/README.md

@@ -57,7 +57,7 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 |-----|----------|---------|
 | `MPP_SECRET_KEY` | when MPP is enabled | Server-side MPP secret. Presence toggles MPP on. |
 | `MPP_CURRENCY` | when MPP is enabled | Tempo currency address. Use `TEMPO_USDC_ADDRESS` for Tempo USDC. |
-| `TEMPO_RPC_URL` | when MPP is enabled | Authenticated Tempo JSON-RPC endpoint. Public `rpc.tempo.xyz` returns 401. |
+| `TEMPO_RPC_URL` | no | Tempo JSON-RPC endpoint for MPP on-chain verification. Defaults to the public `DEFAULT_TEMPO_RPC_URL` (`https://rpc.tempo.xyz`). Override only if you have a dedicated endpoint. |
 | `MPP_OPERATOR_KEY` | no | Signs server-side close/settle. When set, MPP session mode is enabled automatically (required for `.metered()`: both streaming and request-mode per-tick billing). Address must equal the payee. |
 | `MPP_FEE_PAYER_KEY` | no | Sponsors client gas for channel open/topUp. Must resolve to a different address than `MPP_OPERATOR_KEY` (Tempo rejects fee-delegated txs where `sender === feePayer`). |
 

package/dist/index.cjs

@@ -31,7 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/constants.ts
-var BASE_MAINNET_NETWORK, SOLANA_MAINNET_NETWORK, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, ZERO_EVM_ADDRESS, DEFAULT_SOLANA_FACILITATOR_URL;
+var BASE_MAINNET_NETWORK, SOLANA_MAINNET_NETWORK, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, ZERO_EVM_ADDRESS, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -43,6 +43,7 @@ var init_constants = __esm({
     BASE_USDC_DECIMALS = 6;
     ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
     DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
+    DEFAULT_TEMPO_RPC_URL = "https://rpc.tempo.xyz";
   }
 });
 
@@ -470,6 +471,7 @@ __export(index_exports, {
   BASE_USDC_ADDRESS: () => BASE_USDC_ADDRESS,
   BASE_USDC_DECIMALS: () => BASE_USDC_DECIMALS,
   DEFAULT_SOLANA_FACILITATOR_URL: () => DEFAULT_SOLANA_FACILITATOR_URL,
+  DEFAULT_TEMPO_RPC_URL: () => DEFAULT_TEMPO_RPC_URL,
   HttpError: () => HttpError,
   RouterConfigError: () => RouterConfigError,
   SOLANA_MAINNET_NETWORK: () => SOLANA_MAINNET_NETWORK,
@@ -539,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 ",
@@ -569,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) {
@@ -672,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,
@@ -683,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) {
@@ -719,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) {
@@ -728,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 };
 }
 
@@ -753,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 };
 }
 
@@ -776,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;
 }
 
@@ -854,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
   };
 }
@@ -868,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;
 }
 
@@ -956,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,
@@ -991,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,
@@ -1018,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
@@ -1574,7 +1649,7 @@ async function verifyHashMode(args, info) {
   }
   if (chargeResult.status === 402) {
     const reason = await readChallengeReason(chargeResult.challenge);
-    const detail = reason || "credential may be invalid, or check TEMPO_RPC_URL configuration";
+    const detail = reason || "credential may be invalid, or check your TEMPO_RPC_URL endpoint";
     report("warn", `MPP credential rejected: ${detail}`);
     return { ok: false, kind: "invalid" };
   }
@@ -2457,11 +2532,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);
@@ -2493,11 +2566,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;
       }
     }
@@ -2656,10 +2727,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
   };
 }
@@ -2790,7 +2862,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;
@@ -2812,6 +2890,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;
@@ -2976,7 +3057,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,
@@ -2989,7 +3076,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;
@@ -3010,6 +3103,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) {
@@ -4464,7 +4560,7 @@ var envShape = {
   }).optional(),
   TEMPO_RPC_URL: import_zod.z.string().refine(isUrl, {
     params: { code: "invalid_mpp_rpc_url", ...mpp },
-    message: "TEMPO_RPC_URL must be a valid URL \u2014 authenticated Tempo JSON-RPC endpoint. Public rpc.tempo.xyz returns 401."
+    message: "TEMPO_RPC_URL must be a valid URL \u2014 the Tempo JSON-RPC endpoint used for MPP on-chain verification. Optional; defaults to the public DEFAULT_TEMPO_RPC_URL."
   }).optional(),
   MPP_OPERATOR_KEY: import_zod.z.string().refine(isEvmPrivateKey, {
     params: { code: "invalid_mpp_operator_key", ...mpp },
@@ -4505,14 +4601,6 @@ var EnvInputSchema = import_zod.z.object(envShape).passthrough().superRefine((en
         ["MPP_CURRENCY"]
       );
     }
-    if (env.TEMPO_RPC_URL === void 0) {
-      addIssue(
-        ctx,
-        { code: "missing_mpp_rpc_url", ...mpp },
-        "TEMPO_RPC_URL is required when MPP is enabled \u2014 authenticated Tempo JSON-RPC endpoint. Public rpc.tempo.xyz returns 401.",
-        ["TEMPO_RPC_URL"]
-      );
-    }
   }
   const collision = operatorAddressesCollide(env.MPP_OPERATOR_KEY, env.MPP_FEE_PAYER_KEY);
   if (collision) {
@@ -4644,7 +4732,7 @@ function validateX402Config(config, env) {
   }
   return issues;
 }
-function validateMppConfig(config, env) {
+function validateMppConfig(config) {
   const m = config.mpp;
   if (!m) {
     return [
@@ -4692,12 +4780,6 @@ function validateMppConfig(config, env) {
       `MPP recipient '${placeholder}' is a placeholder address and cannot receive payments.`
     );
   }
-  if (!m.rpcUrl && !env.TEMPO_RPC_URL) {
-    push(
-      "missing_mpp_rpc_url",
-      "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object."
-    );
-  }
   if (m.feePayerKey && !isEvmPrivateKey(m.feePayerKey)) {
     push(
       "invalid_mpp_fee_payer_key",
@@ -4804,7 +4886,7 @@ function routerConfigFromEnv(options) {
   const mppConfig = mppEnabled ? {
     secretKey: env.MPP_SECRET_KEY,
     currency: canonicalizeEvm(env.MPP_CURRENCY),
-    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrl: env.TEMPO_RPC_URL ?? DEFAULT_TEMPO_RPC_URL,
     recipient: payeeAddress,
     ...env.MPP_FEE_PAYER_KEY ? { feePayerKey: env.MPP_FEE_PAYER_KEY } : {},
     ...env.MPP_OPERATOR_KEY ? { operatorKey: env.MPP_OPERATOR_KEY, session: {} } : {}
@@ -4855,7 +4937,7 @@ function getRouterConfigIssues(config, options = {}) {
     });
   }
   if (protocols.includes("x402")) issues.push(...validateX402Config(config, env));
-  if (protocols.includes("mpp")) issues.push(...validateMppConfig(config, env));
+  if (protocols.includes("mpp")) issues.push(...validateMppConfig(config));
   return issues;
 }
 
@@ -4927,6 +5009,7 @@ function getMppxStreamingContext(args) {
 }
 
 // src/init/mpp.ts
+init_constants();
 async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
   if (configError) return { initError: configError };
   if (!config.mpp) return {};
@@ -4935,7 +5018,7 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     const { createClient, http } = await import("viem");
     const { tempo: tempoChain } = await import("viem/chains");
     const { privateKeyToAccount: privateKeyToAccount2 } = await import("viem/accounts");
-    const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+    const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL ?? DEFAULT_TEMPO_RPC_URL;
     const tempoClient = createClient({ chain: tempoChain, transport: http(rpcUrl) });
     const getClient = async () => tempoClient;
     const operatorAccount = config.mpp.operatorKey ? privateKeyToAccount2(config.mpp.operatorKey) : void 0;
@@ -5113,6 +5196,7 @@ function createRouterFromEnv(options) {
   BASE_USDC_ADDRESS,
   BASE_USDC_DECIMALS,
   DEFAULT_SOLANA_FACILITATOR_URL,
+  DEFAULT_TEMPO_RPC_URL,
   HttpError,
   RouterConfigError,
   SOLANA_MAINNET_NETWORK,

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 */
@@ -411,7 +422,7 @@ interface RouterConfig {
         currency: string;
         /** MPP payee address (EVM). Overrides `payeeAddress` for MPP only. Required when `payeeAddress` is unset. MUST equal `operatorKey`'s derived address when `session` is enabled. */
         recipient?: string;
-        /** Tempo RPC URL for on-chain verification. Falls back to `TEMPO_RPC_URL`. */
+        /** Tempo RPC URL for on-chain verification. Falls back to `TEMPO_RPC_URL`, then to the public `DEFAULT_TEMPO_RPC_URL`. */
         rpcUrl?: string;
         /** Hex private key. Signs channel close/settle; required for `session`. Address MUST equal `recipient`/payee — mppx asserts sender===payee on settle. Validated at init. */
         operatorKey?: string;
@@ -793,7 +804,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private register;
 }
 
-type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'mpp_operator_recipient_mismatch' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
+type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'mpp_operator_recipient_mismatch' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
 type RouterConfigIssueSeverity = 'error' | 'warning';
 interface RouterConfigIssue {
     code: RouterConfigIssueCode;
@@ -870,6 +881,8 @@ declare const BASE_USDC_DECIMALS = 6;
 declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
 /** Public Solana x402 facilitator. Override per-deployment via `SOLANA_FACILITATOR_URL`. */
 declare const DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
+/** Public Tempo JSON-RPC endpoint used for MPP on-chain verification. Override per-deployment via `TEMPO_RPC_URL`. */
+declare const DEFAULT_TEMPO_RPC_URL = "https://rpc.tempo.xyz";
 
 interface MonitorEntry {
     provider: string;
@@ -912,4 +925,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

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 */
@@ -411,7 +422,7 @@ interface RouterConfig {
         currency: string;
         /** MPP payee address (EVM). Overrides `payeeAddress` for MPP only. Required when `payeeAddress` is unset. MUST equal `operatorKey`'s derived address when `session` is enabled. */
         recipient?: string;
-        /** Tempo RPC URL for on-chain verification. Falls back to `TEMPO_RPC_URL`. */
+        /** Tempo RPC URL for on-chain verification. Falls back to `TEMPO_RPC_URL`, then to the public `DEFAULT_TEMPO_RPC_URL`. */
         rpcUrl?: string;
         /** Hex private key. Signs channel close/settle; required for `session`. Address MUST equal `recipient`/payee — mppx asserts sender===payee on settle. Validated at init. */
         operatorKey?: string;
@@ -793,7 +804,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private register;
 }
 
-type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'mpp_operator_recipient_mismatch' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
+type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'mpp_operator_recipient_mismatch' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
 type RouterConfigIssueSeverity = 'error' | 'warning';
 interface RouterConfigIssue {
     code: RouterConfigIssueCode;
@@ -870,6 +881,8 @@ declare const BASE_USDC_DECIMALS = 6;
 declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
 /** Public Solana x402 facilitator. Override per-deployment via `SOLANA_FACILITATOR_URL`. */
 declare const DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
+/** Public Tempo JSON-RPC endpoint used for MPP on-chain verification. Override per-deployment via `TEMPO_RPC_URL`. */
+declare const DEFAULT_TEMPO_RPC_URL = "https://rpc.tempo.xyz";
 
 interface MonitorEntry {
     provider: string;
@@ -912,4 +925,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.js

@@ -9,7 +9,7 @@ var __export = (target, all) => {
 };
 
 // src/constants.ts
-var BASE_MAINNET_NETWORK, SOLANA_MAINNET_NETWORK, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, ZERO_EVM_ADDRESS, DEFAULT_SOLANA_FACILITATOR_URL;
+var BASE_MAINNET_NETWORK, SOLANA_MAINNET_NETWORK, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, ZERO_EVM_ADDRESS, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -21,6 +21,7 @@ var init_constants = __esm({
     BASE_USDC_DECIMALS = 6;
     ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
     DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
+    DEFAULT_TEMPO_RPC_URL = "https://rpc.tempo.xyz";
   }
 });
 
@@ -498,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 ",
@@ -528,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) {
@@ -631,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,
@@ -642,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) {
@@ -678,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) {
@@ -687,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 };
 }
 
@@ -712,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 };
 }
 
@@ -735,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;
 }
 
@@ -813,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
   };
 }
@@ -827,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;
 }
 
@@ -915,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,
@@ -950,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,
@@ -977,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
@@ -1533,7 +1607,7 @@ async function verifyHashMode(args, info) {
   }
   if (chargeResult.status === 402) {
     const reason = await readChallengeReason(chargeResult.challenge);
-    const detail = reason || "credential may be invalid, or check TEMPO_RPC_URL configuration";
+    const detail = reason || "credential may be invalid, or check your TEMPO_RPC_URL endpoint";
     report("warn", `MPP credential rejected: ${detail}`);
     return { ok: false, kind: "invalid" };
   }
@@ -2416,11 +2490,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);
@@ -2452,11 +2524,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;
       }
     }
@@ -2615,10 +2685,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
   };
 }
@@ -2749,7 +2820,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;
@@ -2771,6 +2848,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;
@@ -2935,7 +3015,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,
@@ -2948,7 +3034,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;
@@ -2969,6 +3061,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) {
@@ -4423,7 +4518,7 @@ var envShape = {
   }).optional(),
   TEMPO_RPC_URL: z.string().refine(isUrl, {
     params: { code: "invalid_mpp_rpc_url", ...mpp },
-    message: "TEMPO_RPC_URL must be a valid URL \u2014 authenticated Tempo JSON-RPC endpoint. Public rpc.tempo.xyz returns 401."
+    message: "TEMPO_RPC_URL must be a valid URL \u2014 the Tempo JSON-RPC endpoint used for MPP on-chain verification. Optional; defaults to the public DEFAULT_TEMPO_RPC_URL."
   }).optional(),
   MPP_OPERATOR_KEY: z.string().refine(isEvmPrivateKey, {
     params: { code: "invalid_mpp_operator_key", ...mpp },
@@ -4464,14 +4559,6 @@ var EnvInputSchema = z.object(envShape).passthrough().superRefine((env, ctx) =>
         ["MPP_CURRENCY"]
       );
     }
-    if (env.TEMPO_RPC_URL === void 0) {
-      addIssue(
-        ctx,
-        { code: "missing_mpp_rpc_url", ...mpp },
-        "TEMPO_RPC_URL is required when MPP is enabled \u2014 authenticated Tempo JSON-RPC endpoint. Public rpc.tempo.xyz returns 401.",
-        ["TEMPO_RPC_URL"]
-      );
-    }
   }
   const collision = operatorAddressesCollide(env.MPP_OPERATOR_KEY, env.MPP_FEE_PAYER_KEY);
   if (collision) {
@@ -4603,7 +4690,7 @@ function validateX402Config(config, env) {
   }
   return issues;
 }
-function validateMppConfig(config, env) {
+function validateMppConfig(config) {
   const m = config.mpp;
   if (!m) {
     return [
@@ -4651,12 +4738,6 @@ function validateMppConfig(config, env) {
       `MPP recipient '${placeholder}' is a placeholder address and cannot receive payments.`
     );
   }
-  if (!m.rpcUrl && !env.TEMPO_RPC_URL) {
-    push(
-      "missing_mpp_rpc_url",
-      "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object."
-    );
-  }
   if (m.feePayerKey && !isEvmPrivateKey(m.feePayerKey)) {
     push(
       "invalid_mpp_fee_payer_key",
@@ -4763,7 +4844,7 @@ function routerConfigFromEnv(options) {
   const mppConfig = mppEnabled ? {
     secretKey: env.MPP_SECRET_KEY,
     currency: canonicalizeEvm(env.MPP_CURRENCY),
-    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrl: env.TEMPO_RPC_URL ?? DEFAULT_TEMPO_RPC_URL,
     recipient: payeeAddress,
     ...env.MPP_FEE_PAYER_KEY ? { feePayerKey: env.MPP_FEE_PAYER_KEY } : {},
     ...env.MPP_OPERATOR_KEY ? { operatorKey: env.MPP_OPERATOR_KEY, session: {} } : {}
@@ -4814,7 +4895,7 @@ function getRouterConfigIssues(config, options = {}) {
     });
   }
   if (protocols.includes("x402")) issues.push(...validateX402Config(config, env));
-  if (protocols.includes("mpp")) issues.push(...validateMppConfig(config, env));
+  if (protocols.includes("mpp")) issues.push(...validateMppConfig(config));
   return issues;
 }
 
@@ -4886,6 +4967,7 @@ function getMppxStreamingContext(args) {
 }
 
 // src/init/mpp.ts
+init_constants();
 async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
   if (configError) return { initError: configError };
   if (!config.mpp) return {};
@@ -4894,7 +4976,7 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     const { createClient, http } = await import("viem");
     const { tempo: tempoChain } = await import("viem/chains");
     const { privateKeyToAccount: privateKeyToAccount2 } = await import("viem/accounts");
-    const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+    const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL ?? DEFAULT_TEMPO_RPC_URL;
     const tempoClient = createClient({ chain: tempoChain, transport: http(rpcUrl) });
     const getClient = async () => tempoClient;
     const operatorAccount = config.mpp.operatorKey ? privateKeyToAccount2(config.mpp.operatorKey) : void 0;
@@ -5071,6 +5153,7 @@ export {
   BASE_USDC_ADDRESS,
   BASE_USDC_DECIMALS,
   DEFAULT_SOLANA_FACILITATOR_URL,
+  DEFAULT_TEMPO_RPC_URL,
   HttpError,
   RouterConfigError,
   SOLANA_MAINNET_NETWORK,

package/package.json

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