@agentcash/router 1.5.0 → 1.5.1

package/dist/index.js

@@ -420,7 +420,7 @@ import { NextResponse as NextResponse2 } from "next/server";
 
 // src/auth/normalize-wallet.ts
 function normalizeWalletAddress(address) {
-  return address.startsWith("0x") ? address.toLowerCase() : address;
+  return /^0x/i.test(address) ? address.toLowerCase() : address;
 }
 
 // src/plugin.ts
@@ -585,12 +585,13 @@ var HttpError = class extends Error {
 };
 
 // src/handler.ts
-async function safeCallHandler(handler, ctx) {
+async function safeCallHandler(handler, ctx, options = {}) {
   try {
     const result = await handler(ctx);
     if (result instanceof Response) return result;
     return NextResponse.json(result);
   } catch (error) {
+    options.onError?.(error);
     const status = error instanceof HttpError ? error.status : typeof error.status === "number" ? error.status : 500;
     const message = error instanceof Error ? error.message : "Internal error";
     return NextResponse.json({ success: false, error: message }, { status });
@@ -713,6 +714,9 @@ async function verifyX402Payment(opts) {
     throw err;
   }
   if (!verify.isValid) return invalidPaymentVerification();
+  if (typeof verify.payer !== "string" || verify.payer.length === 0) {
+    throw new Error("x402 verification succeeded without a payer address");
+  }
   return {
     valid: true,
     payer: verify.payer,
@@ -1007,6 +1011,17 @@ function getRequirementRecipient(requirements) {
   const payTo = requirements?.payTo;
   return typeof payTo === "string" ? payTo : void 0;
 }
+function errorStatus(error, fallback) {
+  const status = error?.status;
+  return typeof status === "number" ? status : fallback;
+}
+function errorMessage(error, fallback) {
+  return error instanceof Error ? error.message : fallback;
+}
+function handlerFailureError(response) {
+  const message = response.statusText || `Handler returned HTTP ${response.status}`;
+  return Object.assign(new Error(message), { status: response.status });
+}
 function siwxSignatureType(network) {
   return network.startsWith("solana:") ? "ed25519" : "eip191";
 }
@@ -1046,11 +1061,20 @@ function createRequestHandler(routeEntry, handler, deps) {
       setVerifiedWallet: (addr) => pluginCtx.setVerifiedWallet(addr)
     };
     let rawResult;
-    const response = await safeCallHandler(async (c) => {
-      rawResult = await handler(c);
-      return rawResult;
-    }, ctx);
-    return { response, rawResult };
+    let handlerError;
+    const response = await safeCallHandler(
+      async (c) => {
+        rawResult = await handler(c);
+        return rawResult;
+      },
+      ctx,
+      {
+        onError(error) {
+          handlerError = error;
+        }
+      }
+    );
+    return { response, rawResult, handlerError };
   }
   function finalize(response, rawResult, meta, pluginCtx, requestBody) {
     fireProviderQuota(routeEntry, response, rawResult, deps, pluginCtx);
@@ -1061,6 +1085,87 @@ function createRequestHandler(routeEntry, handler, deps) {
     firePluginResponse(deps, pluginCtx, meta, response, requestBody);
     return response;
   }
+  function settlementContext(scope) {
+    return {
+      route: routeEntry.key,
+      request: scope.request,
+      body: scope.parsedBody,
+      wallet: scope.wallet,
+      account: scope.account,
+      payment: scope.payment,
+      response: scope.response,
+      result: scope.rawResult
+    };
+  }
+  async function runBeforeSettle(scope) {
+    const hook = routeEntry.settlement?.beforeSettle;
+    if (!hook) return null;
+    try {
+      await hook(settlementContext(scope));
+      return null;
+    } catch (error) {
+      return fail(
+        errorStatus(error, 500),
+        errorMessage(error, "Pre-settlement validation failed"),
+        scope.meta,
+        scope.pluginCtx,
+        scope.parsedBody
+      );
+    }
+  }
+  async function runSettlementError(scope, error, phase) {
+    const hook = routeEntry.settlement?.onSettlementError;
+    if (!hook) return;
+    try {
+      await hook({
+        ...settlementContext(scope),
+        error,
+        phase
+      });
+    } catch (hookError) {
+      const message = errorMessage(hookError, "Settlement error hook failed");
+      console.error(`[router] ${routeEntry.key}: onSettlementError failed: ${message}`);
+      firePluginHook(deps.plugin, "onAlert", scope.pluginCtx, {
+        level: "error",
+        message: `Settlement error hook failed: ${message}`,
+        route: routeEntry.key
+      });
+    }
+  }
+  async function runAfterSettle(scope) {
+    const hook = routeEntry.settlement?.afterSettle;
+    if (!hook) return;
+    try {
+      await hook(settlementContext(scope));
+    } catch (error) {
+      const message = errorMessage(error, "Post-settlement hook failed");
+      console.error(`[router] ${routeEntry.key}: afterSettle failed: ${message}`);
+      firePluginHook(deps.plugin, "onAlert", scope.pluginCtx, {
+        level: "error",
+        message: `Post-settlement hook failed: ${message}`,
+        route: routeEntry.key
+      });
+      await runSettlementError(scope, error, "afterSettle");
+    }
+  }
+  async function runSettledHandlerError(scope, error = scope.handlerError ?? handlerFailureError(scope.response)) {
+    const hook = routeEntry.settlement?.onSettledHandlerError;
+    if (!hook) return;
+    try {
+      await hook({
+        ...settlementContext(scope),
+        error
+      });
+    } catch (hookError) {
+      const message = errorMessage(hookError, "Settled handler error hook failed");
+      console.error(`[router] ${routeEntry.key}: onSettledHandlerError failed: ${message}`);
+      firePluginHook(deps.plugin, "onAlert", scope.pluginCtx, {
+        level: "error",
+        message: `Settled handler error hook failed: ${message}`,
+        route: routeEntry.key
+      });
+    }
+  }
   return async (request) => {
     await deps.initPromise;
     const meta = buildMeta(request, routeEntry);
@@ -1316,18 +1421,9 @@ function createRequestHandler(routeEntry, handler, deps) {
         return fail(status, message, meta, pluginCtx, body.data);
       }
     }
-    let price;
-    try {
-      price = await resolvePrice(routeEntry.pricing, body.data);
-    } catch (err) {
-      return fail(
-        err.status ?? 500,
-        err instanceof Error ? err.message : "Price resolution failed",
-        meta,
-        pluginCtx,
-        body.data
-      );
-    }
+    const priceResult = await resolveDynamicPrice(body.data, routeEntry, deps, pluginCtx, meta);
+    if ("error" in priceResult) return priceResult.error;
+    const price = priceResult.price;
     if (!routeEntry.protocols.includes(protocol)) {
       const accepted = routeEntry.protocols.join(", ") || "none";
       console.warn(
@@ -1381,7 +1477,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         amount: price,
         network: matchedNetwork
       });
-      const { response, rawResult } = await invoke(
+      const { response, rawResult, handlerError } = await invoke(
         request,
         meta,
         pluginCtx,
@@ -1390,7 +1486,21 @@ function createRequestHandler(routeEntry, handler, deps) {
         body.data,
         payment
       );
+      const settleScope = {
+        request,
+        meta,
+        pluginCtx,
+        wallet,
+        account,
+        parsedBody: body.data,
+        payment,
+        response,
+        rawResult,
+        handlerError
+      };
       if (response.status < 400) {
+        const validationFailure = await runBeforeSettle(settleScope);
+        if (validationFailure) return validationFailure;
         try {
           const settle = await settleX402Payment(
             deps.x402Server,
@@ -1416,13 +1526,21 @@ function createRequestHandler(routeEntry, handler, deps) {
           }
           response.headers.set("PAYMENT-RESPONSE", settle.encoded);
           response.headers.set("Cache-Control", "private");
+          const transaction = String(settle.result?.transaction ?? "");
+          const settledPayment = {
+            ...payment,
+            status: "settled",
+            ...transaction ? { transaction } : {}
+          };
           firePluginHook(deps.plugin, "onPaymentSettled", pluginCtx, {
             protocol: "x402",
-            payer: verify.payer,
-            transaction: String(settle.result?.transaction ?? ""),
+            payer: wallet,
+            transaction,
             network: matchedNetwork
           });
+          await runAfterSettle({ ...settleScope, payment: settledPayment });
         } catch (err) {
+          await runSettlementError(settleScope, err, "settle");
           const errObj = err;
           console.error("Settlement failed", {
             message: err instanceof Error ? err.message : String(err),
@@ -1481,27 +1599,44 @@ function createRequestHandler(routeEntry, handler, deps) {
           amount: price,
           network: "tempo:4217"
         });
-        const { response: response2, rawResult: rawResult2 } = await invoke(
+        const mppRecipient2 = deps.mppRecipient ?? deps.payeeAddress;
+        const payment2 = {
+          protocol: "mpp",
+          status: "verified",
+          payer: wallet,
+          amount: price,
+          network: "tempo:4217",
+          ...mppRecipient2 ? { recipient: mppRecipient2 } : {}
+        };
+        const { response: response2, rawResult: rawResult2, handlerError: handlerError2 } = await invoke(
           request,
           meta,
           pluginCtx,
           wallet,
           account,
           body.data,
-          {
-            protocol: "mpp",
-            status: "verified",
-            payer: wallet,
-            amount: price,
-            network: "tempo:4217",
-            recipient: deps.payeeAddress
-          }
+          payment2
         );
+        const settleScope2 = {
+          request,
+          meta,
+          pluginCtx,
+          wallet,
+          account,
+          parsedBody: body.data,
+          payment: payment2,
+          response: response2,
+          rawResult: rawResult2,
+          handlerError: handlerError2
+        };
         if (response2.status < 400) {
+          const validationFailure = await runBeforeSettle(settleScope2);
+          if (validationFailure) return validationFailure;
           let mppResult2;
           try {
             mppResult2 = await deps.mppx.charge({ amount: price })(request);
           } catch (err) {
+            await runSettlementError(settleScope2, err, "settle");
             const message = err instanceof Error ? err.message : String(err);
             console.error(
               `[router] ${routeEntry.key}: MPP broadcast failed after handler: ${message}`
@@ -1530,6 +1665,13 @@ function createRequestHandler(routeEntry, handler, deps) {
             } catch {
             }
             const detail = rejectReason || "transaction reverted on-chain after handler execution";
+            const settlementError = Object.assign(new Error(detail), {
+              status: 402,
+              detail,
+              mppResult: mppResult2,
+              challenge: mppResult2.challenge
+            });
+            await runSettlementError(settleScope2, settlementError, "settle");
             console.error(
               `[router] ${routeEntry.key}: MPP payment failed after handler \u2014 ${detail}`
             );
@@ -1567,6 +1709,17 @@ function createRequestHandler(routeEntry, handler, deps) {
             transaction: txHash2,
             network: "tempo:4217"
           });
+          const settledPayment = {
+            ...payment2,
+            status: "settled",
+            ...txHash2 ? { transaction: txHash2 } : {},
+            ...receiptHeader2 ? { receipt: receiptHeader2 } : {}
+          };
+          await runAfterSettle({
+            ...settleScope2,
+            payment: settledPayment,
+            response: receiptResponse
+          });
           finalize(receiptResponse, rawResult2, meta, pluginCtx, body.data);
           return receiptResponse;
         }
@@ -1622,24 +1775,38 @@ function createRequestHandler(routeEntry, handler, deps) {
         amount: price,
         network: "tempo:4217"
       });
-      const { response, rawResult } = await invoke(
+      const mppRecipient = deps.mppRecipient ?? deps.payeeAddress;
+      const payment = {
+        protocol: "mpp",
+        status: "settled",
+        payer: wallet,
+        amount: price,
+        network: "tempo:4217",
+        ...mppRecipient ? { recipient: mppRecipient } : {},
+        ...txHash ? { transaction: txHash } : {},
+        ...receiptHeader ? { receipt: receiptHeader } : {}
+      };
+      const { response, rawResult, handlerError } = await invoke(
         request,
         meta,
         pluginCtx,
         wallet,
         account,
         body.data,
-        {
-          protocol: "mpp",
-          status: "settled",
-          payer: wallet,
-          amount: price,
-          network: "tempo:4217",
-          recipient: deps.payeeAddress,
-          ...txHash ? { transaction: txHash } : {},
-          ...receiptHeader ? { receipt: receiptHeader } : {}
-        }
+        payment
       );
+      const settleScope = {
+        request,
+        meta,
+        pluginCtx,
+        wallet,
+        account,
+        parsedBody: body.data,
+        payment,
+        response,
+        rawResult,
+        handlerError
+      };
       if (response.status < 400) {
         if (routeEntry.siwxEnabled) {
           try {
@@ -1660,9 +1827,11 @@ function createRequestHandler(routeEntry, handler, deps) {
           transaction: txHash,
           network: "tempo:4217"
         });
+        await runAfterSettle({ ...settleScope, response: receiptResponse });
         finalize(receiptResponse, rawResult, meta, pluginCtx, body.data);
         return receiptResponse;
       }
+      await runSettledHandlerError(settleScope);
       finalize(response, rawResult, meta, pluginCtx, body.data);
       return response;
     }
@@ -1735,9 +1904,10 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
       });
       return { price: routeEntry.maxPrice };
     } else {
+      const message = errorMessage(err, "Price calculation failed");
       const errorResponse = NextResponse2.json(
-        { success: false, error: "Price calculation failed" },
-        { status: 500 }
+        { success: false, error: message },
+        { status: errorStatus(err, 500) }
       );
       firePluginResponse(deps, pluginCtx, meta, errorResponse);
       return { error: errorResponse };
@@ -1910,22 +2080,13 @@ function fireProviderQuota(routeEntry, response, handlerResult, deps, pluginCtx)
 
 // src/validate-examples.ts
 function validateExamples(key, bodySchema, querySchema, outputSchema, inputExample, hasInputExample, outputExample, hasOutputExample) {
-  if (bodySchema && !hasInputExample) {
-    throw new Error(
-      `route '${key}': .body() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample body to advertise.`
-    );
-  }
-  if (querySchema && !hasInputExample) {
-    throw new Error(
-      `route '${key}': .query() requires a matching .inputExample() \u2014 the bazaar discovery extension needs a conforming sample query to advertise.`
-    );
+  const inputSchema = bodySchema ?? querySchema;
+  if (hasInputExample && !inputSchema) {
+    throw new Error(`route '${key}': .inputExample() requires .body() or .query()`);
   }
-  if (outputSchema && !hasOutputExample) {
-    throw new Error(
-      `route '${key}': .output() requires a matching .outputExample() \u2014 the bazaar discovery extension needs a conforming sample response to advertise.`
-    );
+  if (hasOutputExample && !outputSchema) {
+    throw new Error(`route '${key}': .outputExample() requires .output()`);
   }
-  const inputSchema = bodySchema ?? querySchema;
   if (inputSchema && hasInputExample) {
     const result = inputSchema.safeParse(inputExample);
     if (!result.success) {
@@ -1999,6 +2160,8 @@ var RouteBuilder = class {
   /** @internal */
   _validateFn;
   /** @internal */
+  _settlement;
+  /** @internal */
   _mppInfo;
   constructor(key, registry, deps) {
     this._key = key;
@@ -2012,11 +2175,21 @@ var RouteBuilder = class {
     return next;
   }
   paid(pricing, options) {
+    if (this._authMode === "unprotected") {
+      throw new Error(
+        `route '${this._key}': Cannot combine .unprotected() and .paid() on the same route.`
+      );
+    }
+    if (this._pricing !== void 0) {
+      throw new Error(
+        `route '${this._key}': Cannot call .paid() more than once on the same route.`
+      );
+    }
     const next = this.fork();
     next._authMode = "paid";
     next._pricing = pricing;
     if (options?.protocols) {
-      next._protocols = options.protocols;
+      next._protocols = [...options.protocols];
     } else if (next._protocols.length === 0) {
       next._protocols = ["x402"];
     }
@@ -2081,6 +2254,16 @@ var RouteBuilder = class {
     return next;
   }
   unprotected() {
+    if (this._authMode && this._authMode !== "unprotected") {
+      throw new Error(
+        `route '${this._key}': Cannot combine .unprotected() and .${this._authMode}() on the same route.`
+      );
+    }
+    if (this._pricing) {
+      throw new Error(
+        `route '${this._key}': Cannot combine .unprotected() and .paid() on the same route.`
+      );
+    }
     const next = this.fork();
     next._authMode = "unprotected";
     next._protocols = [];
@@ -2095,32 +2278,43 @@ var RouteBuilder = class {
     next._providerConfig = config ?? {};
     return next;
   }
-  // -------------------------------------------------------------------------
-  // Schema methods
-  // -------------------------------------------------------------------------
-  body(schema) {
+  body(schema, example) {
     const next = this.fork();
     next._bodySchema = schema;
+    if (example !== void 0) {
+      next._inputExample = example;
+      next._hasInputExample = true;
+    }
     return next;
   }
-  query(schema) {
+  query(schema, example) {
     const next = this.fork();
     next._querySchema = schema;
+    if (example !== void 0) {
+      next._inputExample = example;
+      next._hasInputExample = true;
+    }
     next._method = "GET";
     return next;
   }
-  output(schema) {
+  output(schema, example) {
     const next = this.fork();
     next._outputSchema = schema;
+    if (example !== void 0) {
+      next._outputExample = example;
+      next._hasOutputExample = true;
+    }
     return next;
   }
   /**
    * Provide a conforming example of the request input (body or query params).
    *
-   * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
-   * `.handler()` overloads, and at route-registration time via Zod validation of the
-   * example against the schema. The example is embedded in the bazaar discovery extension
-   * so indexers can advertise a working sample call.
+   * Optional. When provided, the example is validated against the request schema
+   * at route registration and embedded in the bazaar discovery extension so
+   * indexers can advertise a working sample call.
+   *
+   * For the common case, pass the example directly to `.body(schema, example)` or
+   * `.query(schema, example)` instead.
    *
    * @example
    * ```ts
@@ -2140,10 +2334,11 @@ var RouteBuilder = class {
   /**
    * Provide a conforming example of the response output.
    *
-   * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
-   * overloads, and at route-registration time via Zod validation of the example against
-   * the schema. The example is embedded in the bazaar discovery extension so indexers
-   * can advertise the response shape.
+   * Optional. When provided, the example is validated against the output schema
+   * at route registration and embedded in the bazaar discovery extension so
+   * indexers can advertise the response shape.
+   *
+   * For the common case, pass the example directly to `.output(schema, example)` instead.
    *
    * Accepts any JSON value (objects, arrays, or primitives) — top-level array
    * or primitive responses (e.g. `z.array(...)`) are supported alongside the
@@ -2216,15 +2411,39 @@ var RouteBuilder = class {
     return next;
   }
   // -------------------------------------------------------------------------
+  // Settlement lifecycle
+  // -------------------------------------------------------------------------
+  /**
+   * Add route-specific settlement hooks.
+   *
+   * `beforeSettle` runs after a successful handler response but before
+   * router-controlled settlement/broadcast, so it can still prevent the charge
+   * for x402 and MPP transaction-payload flows. `afterSettle` runs after
+   * settlement and is intended for durable ledgers or app-owned refund queues.
+   */
+  settlement(lifecycle) {
+    const next = this.fork();
+    next._settlement = lifecycle;
+    return next;
+  }
+  // -------------------------------------------------------------------------
   // Terminal method
   // -------------------------------------------------------------------------
   handler(fn) {
     const handlerFn = fn;
+    if (!this._authMode) {
+      throw new Error(
+        `route '${this._key}': Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()`
+      );
+    }
     if (this._validateFn && !this._bodySchema) {
       throw new Error(
         `route '${this._key}': .validate() requires .body() \u2014 validation runs on parsed body`
       );
     }
+    if (this._settlement && !this._pricing) {
+      throw new Error(`route '${this._key}': .settlement() requires a paid route`);
+    }
     validateExamples(
       this._key,
       this._bodySchema,
@@ -2256,6 +2475,7 @@ var RouteBuilder = class {
       providerName: this._providerName,
       providerConfig: this._providerConfig,
       validateFn: this._validateFn,
+      settlement: this._settlement,
       mppInfo: this._mppInfo
     };
     this._registry.register(entry);
@@ -2391,6 +2611,7 @@ function toDiscoveryResource(method, url, mode) {
 }
 
 // src/discovery/openapi.ts
+init_constants();
 import { NextResponse as NextResponse4 } from "next/server";
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
@@ -2533,7 +2754,7 @@ function toProtocolObject(protocol, mppInfo) {
       mpp: {
         method: mppInfo?.method ?? "tempo",
         intent: mppInfo?.intent ?? "charge",
-        currency: mppInfo?.currency ?? "0x20c0000000000000000000000000000000000001"
+        currency: mppInfo?.currency ?? TEMPO_USDC_CURRENCY
       }
     };
   }
@@ -2648,6 +2869,8 @@ function mppFromEnv(env, options = {}) {
   const secretKey = env.MPP_SECRET_KEY;
   const currency = env.MPP_CURRENCY;
   const rpcUrl = env.TEMPO_RPC_URL;
+  const feePayerKey = options.feePayerKey ?? env.MPP_FEE_PAYER_KEY;
+  const feePayerKeySource = options.feePayerKey !== void 0 ? "feePayerKey" : "MPP_FEE_PAYER_KEY";
   const hasAnyMppEnv = Boolean(secretKey || currency || rpcUrl || options.require);
   if (!hasAnyMppEnv) return void 0;
   const missing = [
@@ -2658,12 +2881,21 @@ function mppFromEnv(env, options = {}) {
   if (missing.length > 0) {
     throw new Error(`MPP env is incomplete. Missing: ${missing.join(", ")}`);
   }
+  if (!isEvmAddress(currency)) {
+    throw new Error("MPP_CURRENCY must be a 0x-prefixed 20-byte Tempo currency address");
+  }
+  if (options.recipient && !isEvmAddress(options.recipient)) {
+    throw new Error("MPP recipient must be a 0x-prefixed EVM address");
+  }
+  if (feePayerKey && !isEvmPrivateKey(feePayerKey)) {
+    throw new Error(`${feePayerKeySource} must be a 0x-prefixed 32-byte EVM private key`);
+  }
   return {
     secretKey,
     currency,
     rpcUrl,
     ...options.recipient ? { recipient: options.recipient } : {},
-    ...options.feePayerKey ? { feePayerKey: options.feePayerKey } : {},
+    ...feePayerKey ? { feePayerKey } : {},
     ...options.useDefaultStore !== void 0 ? { useDefaultStore: options.useDefaultStore } : {}
   };
 }
@@ -2801,13 +3033,26 @@ function validateMppConfig(config, env) {
       protocol: "mpp",
       message: "MPP requires currency. Set MPP_CURRENCY or pass mpp.currency."
     });
+  } else if (!isEvmAddress(mpp.currency)) {
+    issues.push({
+      code: "invalid_mpp_currency",
+      protocol: "mpp",
+      message: "MPP currency must be a 0x-prefixed 20-byte Tempo currency address. Use TEMPO_USDC_CURRENCY for Tempo USDC."
+    });
   }
-  if (!mpp.recipient && !config.payeeAddress) {
+  const mppRecipient = mpp.recipient ?? config.payeeAddress;
+  if (!mppRecipient) {
     issues.push({
       code: "missing_mpp_recipient",
       protocol: "mpp",
       message: "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config."
     });
+  } else if (!isEvmAddress(mppRecipient)) {
+    issues.push({
+      code: "invalid_mpp_recipient",
+      protocol: "mpp",
+      message: "MPP recipient must be a 0x-prefixed EVM address. Solana recipients require x402."
+    });
   }
   const placeholder = findPlaceholderPayee([mpp.recipient, config.payeeAddress]);
   if (placeholder) {
@@ -2824,6 +3069,13 @@ function validateMppConfig(config, env) {
       message: "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object."
     });
   }
+  if (mpp.feePayerKey && !isEvmPrivateKey(mpp.feePayerKey)) {
+    issues.push({
+      code: "invalid_mpp_fee_payer_key",
+      protocol: "mpp",
+      message: "MPP feePayerKey must be a 0x-prefixed 32-byte EVM private key."
+    });
+  }
   if (mpp.useDefaultStore && !mpp.store && (!env.KV_REST_API_URL || !env.KV_REST_API_TOKEN)) {
     issues.push({
       code: "missing_mpp_default_store_env",
@@ -2841,8 +3093,14 @@ function usesDefaultEvmFacilitator(config) {
 function isSupportedX402Network(network) {
   return isEvmNetwork(network) || isSolanaNetwork(network);
 }
+function isEvmAddress(value) {
+  return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+function isEvmPrivateKey(value) {
+  return /^0x[a-fA-F0-9]{64}$/.test(value);
+}
 function findPlaceholderPayee(values) {
-  return values.find((value) => value?.toLowerCase() === ZERO_EVM_ADDRESS) ?? null;
+  return values.find((value) => value !== void 0 && /^0x0{40}$/i.test(value)) ?? null;
 }
 
 // src/index.ts
@@ -2891,6 +3149,7 @@ function createRouter(config) {
     nonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
+    mppRecipient: config.mpp?.recipient ?? config.payeeAddress,
     network,
     x402FacilitatorsByNetwork: void 0,
     x402Accepts,