@agentcash/router 1.4.1 → 1.5.1

package/dist/index.cjs

@@ -188,6 +188,18 @@ var init_x402_facilitators = __esm({
   }
 });
 
+// src/constants.ts
+var BASE_NETWORK, SOLANA_MAINNET_NETWORK, TEMPO_USDC_CURRENCY, ZERO_EVM_ADDRESS;
+var init_constants = __esm({
+  "src/constants.ts"() {
+    "use strict";
+    BASE_NETWORK = "eip155:8453";
+    SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50";
+    ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
+  }
+});
+
 // src/x402-config.ts
 async function resolvePayToValue(payTo, request, fallback, body) {
   if (!payTo) return fallback;
@@ -201,7 +213,7 @@ function getConfiguredX402Accepts(config) {
   return [
     {
       scheme: "exact",
-      network: config.network ?? "eip155:8453",
+      network: config.network ?? BASE_NETWORK,
       payTo: config.payeeAddress
     }
   ];
@@ -230,6 +242,7 @@ async function resolveX402Accepts(request, routeEntry, accepts, fallbackPayTo, b
 var init_x402_config = __esm({
   "src/x402-config.ts"() {
     "use strict";
+    init_constants();
   }
 });
 
@@ -376,17 +389,28 @@ var init_upstash_rest = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BASE_NETWORK: () => BASE_NETWORK,
   HttpError: () => HttpError,
   MemoryEntitlementStore: () => MemoryEntitlementStore,
   MemoryNonceStore: () => MemoryNonceStore,
   RouteBuilder: () => RouteBuilder,
   RouteRegistry: () => RouteRegistry,
+  RouterConfigError: () => RouterConfigError,
   SIWX_CHALLENGE_EXPIRY_MS: () => SIWX_CHALLENGE_EXPIRY_MS,
   SIWX_ERROR_MESSAGES: () => SIWX_ERROR_MESSAGES,
+  SOLANA_MAINNET_NETWORK: () => SOLANA_MAINNET_NETWORK,
+  TEMPO_USDC_CURRENCY: () => TEMPO_USDC_CURRENCY,
+  ZERO_EVM_ADDRESS: () => ZERO_EVM_ADDRESS,
   consolePlugin: () => consolePlugin,
   createRedisEntitlementStore: () => createRedisEntitlementStore,
   createRedisNonceStore: () => createRedisNonceStore,
-  createRouter: () => createRouter
+  createRouter: () => createRouter,
+  formatRouterConfigIssues: () => formatRouterConfigIssues,
+  getRouterConfigIssues: () => getRouterConfigIssues,
+  mppFromEnv: () => mppFromEnv,
+  paidOptionsForProtocols: () => paidOptionsForProtocols,
+  validateRouterConfig: () => validateRouterConfig,
+  x402AcceptsFromEnv: () => x402AcceptsFromEnv
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -446,7 +470,7 @@ var import_server2 = require("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
@@ -611,12 +635,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 import_server.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 import_server.NextResponse.json({ success: false, error: message }, { status });
@@ -739,6 +764,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,
@@ -1029,6 +1057,21 @@ function getRequirementNetwork(requirements, fallback) {
   const network = requirements?.network;
   return typeof network === "string" ? network : fallback;
 }
+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";
 }
@@ -1047,7 +1090,7 @@ function getSupportedChains(x402Accepts, fallbackNetwork) {
   return chains;
 }
 function createRequestHandler(routeEntry, handler, deps) {
-  async function invoke(request, meta, pluginCtx, wallet, account, parsedBody) {
+  async function invoke(request, meta, pluginCtx, wallet, account, parsedBody, payment) {
     const ctx = {
       body: parsedBody,
       query: parseQuery(request, routeEntry),
@@ -1055,6 +1098,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       requestId: meta.requestId,
       route: routeEntry.key,
       wallet,
+      payment,
       account,
       alert(level, message, alertMeta) {
         firePluginHook(deps.plugin, "onAlert", pluginCtx, {
@@ -1067,11 +1111,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);
@@ -1082,6 +1135,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);
@@ -1107,7 +1241,8 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account2,
-        body2.data
+        body2.data,
+        null
       );
       finalize(response, rawResult, meta, pluginCtx, body2.data);
       return response;
@@ -1336,18 +1471,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(
@@ -1384,7 +1510,16 @@ function createRequestHandler(routeEntry, handler, deps) {
         return await build402(request, routeEntry, deps, meta, pluginCtx, body.data);
       const { payload: verifyPayload, requirements: verifyRequirements } = verify;
       const matchedNetwork = getRequirementNetwork(verifyRequirements, deps.network);
+      const matchedRecipient = getRequirementRecipient(verifyRequirements);
       const wallet = normalizeWalletAddress(verify.payer);
+      const payment = {
+        protocol: "x402",
+        status: "verified",
+        payer: wallet,
+        amount: price,
+        network: matchedNetwork,
+        ...matchedRecipient ? { recipient: matchedRecipient } : {}
+      };
       pluginCtx.setVerifiedWallet(wallet);
       firePluginHook(deps.plugin, "onPaymentVerified", pluginCtx, {
         protocol: "x402",
@@ -1392,15 +1527,30 @@ function createRequestHandler(routeEntry, handler, deps) {
         amount: price,
         network: matchedNetwork
       });
-      const { response, rawResult } = await invoke(
+      const { response, rawResult, handlerError } = await invoke(
         request,
         meta,
         pluginCtx,
         wallet,
         account,
-        body.data
+        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,
@@ -1426,13 +1576,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),
@@ -1491,19 +1649,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
+          body.data,
+          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}`
@@ -1532,6 +1715,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}`
             );
@@ -1569,6 +1759,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;
         }
@@ -1624,14 +1825,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
+        body.data,
+        payment
       );
+      const settleScope = {
+        request,
+        meta,
+        pluginCtx,
+        wallet,
+        account,
+        parsedBody: body.data,
+        payment,
+        response,
+        rawResult,
+        handlerError
+      };
       if (response.status < 400) {
         if (routeEntry.siwxEnabled) {
           try {
@@ -1652,9 +1877,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;
     }
@@ -1727,9 +1954,10 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
       });
       return { price: routeEntry.maxPrice };
     } else {
+      const message = errorMessage(err, "Price calculation failed");
       const errorResponse = import_server2.NextResponse.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 };
@@ -1902,22 +2130,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) {
@@ -1991,6 +2210,8 @@ var RouteBuilder = class {
   /** @internal */
   _validateFn;
   /** @internal */
+  _settlement;
+  /** @internal */
   _mppInfo;
   constructor(key, registry, deps) {
     this._key = key;
@@ -2004,11 +2225,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"];
     }
@@ -2073,6 +2304,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 = [];
@@ -2087,32 +2328,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
@@ -2132,10 +2384,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
@@ -2208,15 +2461,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,
@@ -2248,6 +2525,7 @@ var RouteBuilder = class {
       providerName: this._providerName,
       providerConfig: this._providerConfig,
       validateFn: this._validateFn,
+      settlement: this._settlement,
       mppInfo: this._mppInfo
     };
     this._registry.register(entry);
@@ -2384,6 +2662,7 @@ function toDiscoveryResource(method, url, mode) {
 
 // src/discovery/openapi.ts
 var import_server4 = require("next/server");
+init_constants();
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
@@ -2525,7 +2804,7 @@ function toProtocolObject(protocol, mppInfo) {
       mpp: {
         method: mppInfo?.method ?? "tempo",
         intent: mppInfo?.intent ?? "charge",
-        currency: mppInfo?.currency ?? "0x20c0000000000000000000000000000000000001"
+        currency: mppInfo?.currency ?? TEMPO_USDC_CURRENCY
       }
     };
   }
@@ -2590,61 +2869,319 @@ function createLlmsTxtHandler(discovery) {
 
 // src/index.ts
 init_x402_config();
+init_constants();
+
+// src/config.ts
+init_constants();
 init_evm();
 init_solana();
+init_x402_config();
+var RouterConfigError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(formatRouterConfigIssues(issues));
+    this.name = "RouterConfigError";
+    this.issues = issues;
+  }
+};
+function validateRouterConfig(config, options = {}) {
+  const issues = getRouterConfigIssues(config, options);
+  if (issues.length > 0) throw new RouterConfigError(issues);
+}
+function getRouterConfigIssues(config, options = {}) {
+  const env = options.env ?? process.env;
+  const issues = [];
+  const protocols = config.protocols ?? ["x402"];
+  if (!config.baseUrl) {
+    issues.push({
+      code: "missing_base_url",
+      message: '[router] baseUrl is required in RouterConfig. Set it to your production domain (e.g., "https://api.example.com"). The realm is used for payment matching and must be correct.'
+    });
+  }
+  if (config.protocols && config.protocols.length === 0) {
+    issues.push({
+      code: "empty_protocols",
+      message: "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+    });
+  }
+  if (protocols.includes("x402")) {
+    issues.push(...validateX402Config(config, env, options));
+  }
+  if (protocols.includes("mpp")) {
+    issues.push(...validateMppConfig(config, env));
+  }
+  return issues;
+}
+function formatRouterConfigIssues(issues) {
+  return issues.map((issue) => issue.message).join("\n");
+}
+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 = [
+    secretKey ? null : "MPP_SECRET_KEY",
+    currency ? null : "MPP_CURRENCY",
+    rpcUrl ? null : "TEMPO_RPC_URL"
+  ].filter(Boolean);
+  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 } : {},
+    ...feePayerKey ? { feePayerKey } : {},
+    ...options.useDefaultStore !== void 0 ? { useDefaultStore: options.useDefaultStore } : {}
+  };
+}
+function x402AcceptsFromEnv(env, options = {}) {
+  const payeeEnv = options.payeeEnv ?? "X402_WALLET_ADDRESS";
+  const solanaPayeeEnv = options.solanaPayeeEnv ?? "SOLANA_PAYEE_ADDRESS";
+  const payeeAddress = options.payeeAddress ?? env[payeeEnv];
+  if (!payeeAddress) {
+    throw new Error(`${payeeEnv} is required to build x402 accepts`);
+  }
+  const accepts = [
+    {
+      scheme: "exact",
+      network: options.network ?? BASE_NETWORK,
+      payTo: payeeAddress
+    }
+  ];
+  const solanaPayeeAddress = options.solanaPayeeAddress ?? env[solanaPayeeEnv];
+  if (solanaPayeeAddress) {
+    accepts.push({
+      scheme: "exact",
+      network: SOLANA_MAINNET_NETWORK,
+      payTo: solanaPayeeAddress
+    });
+  }
+  return accepts;
+}
+function paidOptionsForProtocols(protocols) {
+  return { protocols: [...protocols] };
+}
+function validateX402Config(config, env, options) {
+  const issues = [];
+  const accepts = getConfiguredX402Accepts(config);
+  if (accepts.length === 0) {
+    issues.push({
+      code: "missing_x402_accepts",
+      protocol: "x402",
+      message: "x402 requires at least one accept configuration."
+    });
+    return issues;
+  }
+  const acceptWithoutNetwork = accepts.find((accept) => !accept.network);
+  if (acceptWithoutNetwork) {
+    issues.push({
+      code: "missing_x402_network",
+      protocol: "x402",
+      message: "x402 accepts require a network."
+    });
+  }
+  const unsupported = accepts.find(
+    (accept) => accept.network && !isSupportedX402Network(accept.network)
+  );
+  if (unsupported) {
+    issues.push({
+      code: "unsupported_x402_network",
+      protocol: "x402",
+      message: `unsupported x402 network '${unsupported.network}'. Use eip155:* or solana:*.`
+    });
+  }
+  const missingAsset = accepts.find(
+    (accept) => (accept.scheme ?? "exact") !== "exact" && !accept.asset
+  );
+  if (missingAsset) {
+    issues.push({
+      code: "missing_x402_asset",
+      protocol: "x402",
+      message: "non-exact x402 accepts require an asset."
+    });
+  }
+  const invalidDecimals = accepts.find(
+    (accept) => accept.decimals !== void 0 && (!Number.isInteger(accept.decimals) || accept.decimals < 0)
+  );
+  if (invalidDecimals) {
+    issues.push({
+      code: "invalid_x402_decimals",
+      protocol: "x402",
+      message: "x402 accept decimals must be a non-negative integer."
+    });
+  }
+  if (accepts.some((accept) => !accept.payTo) && !config.payeeAddress) {
+    issues.push({
+      code: "missing_x402_payee",
+      protocol: "x402",
+      message: "x402 requires payeeAddress in router config or payTo on every x402 accept."
+    });
+  }
+  const placeholder = findPlaceholderPayee([
+    config.payeeAddress,
+    ...accepts.map((accept) => typeof accept.payTo === "string" ? accept.payTo : void 0)
+  ]);
+  if (placeholder) {
+    issues.push({
+      code: "placeholder_payee",
+      protocol: "x402",
+      message: `x402 payee '${placeholder}' is a placeholder address and cannot receive payments.`
+    });
+  }
+  if (options.requireCdpKeys !== false && usesDefaultEvmFacilitator(config)) {
+    const missing = [
+      env.CDP_API_KEY_ID ? null : "CDP_API_KEY_ID",
+      env.CDP_API_KEY_SECRET ? null : "CDP_API_KEY_SECRET"
+    ].filter(Boolean);
+    if (missing.length > 0) {
+      issues.push({
+        code: "missing_cdp_keys",
+        protocol: "x402",
+        message: `default EVM x402 facilitator requires ${missing.join(" and ")}.`
+      });
+    }
+  }
+  return issues;
+}
+function validateMppConfig(config, env) {
+  const issues = [];
+  const mpp = config.mpp;
+  if (!mpp) {
+    return [
+      {
+        code: "missing_mpp_config",
+        protocol: "mpp",
+        message: 'protocols includes "mpp" but mpp config is missing. Add mpp: { secretKey, currency, recipient } to your router config.'
+      }
+    ];
+  }
+  if (!mpp.secretKey) {
+    issues.push({
+      code: "missing_mpp_secret_key",
+      protocol: "mpp",
+      message: "MPP requires secretKey. Set MPP_SECRET_KEY or pass mpp.secretKey."
+    });
+  }
+  if (!mpp.currency) {
+    issues.push({
+      code: "missing_mpp_currency",
+      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."
+    });
+  }
+  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) {
+    issues.push({
+      code: "placeholder_payee",
+      protocol: "mpp",
+      message: `MPP recipient '${placeholder}' is a placeholder address and cannot receive payments.`
+    });
+  }
+  if (!(mpp.rpcUrl ?? env.TEMPO_RPC_URL)) {
+    issues.push({
+      code: "missing_mpp_rpc_url",
+      protocol: "mpp",
+      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",
+      protocol: "mpp",
+      message: "mpp.useDefaultStore requires KV_REST_API_URL and KV_REST_API_TOKEN environment variables. These are automatically set by Vercel KV."
+    });
+  }
+  return issues;
+}
+function usesDefaultEvmFacilitator(config) {
+  return getConfiguredX402Networks(config).some(
+    (network) => typeof network === "string" && isEvmNetwork(network)
+  ) && config.x402?.facilitators?.evm === void 0;
+}
+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 !== void 0 && /^0x0{40}$/i.test(value)) ?? null;
+}
+
+// src/index.ts
+init_constants();
 function createRouter(config) {
   const registry = new RouteRegistry();
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const entitlementStore = config.siwx?.entitlementStore ?? new MemoryEntitlementStore();
-  const network = config.network ?? "eip155:8453";
+  const network = config.network ?? BASE_NETWORK;
   const x402Accepts = getConfiguredX402Accepts(config);
-  if (!config.baseUrl) {
-    throw new Error(
-      '[router] baseUrl is required in RouterConfig. Set it to your production domain (e.g., "https://api.example.com"). The realm is used for payment matching and must be correct.'
-    );
-  }
-  if (config.protocols && config.protocols.length === 0) {
-    throw new Error(
-      "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
-    );
-  }
-  const resolvedBaseUrl = config.baseUrl.replace(/\/+$/, "");
-  let x402ConfigError;
-  let mppConfigError;
-  if (!config.protocols || config.protocols.includes("x402")) {
-    if (x402Accepts.length === 0) {
-      x402ConfigError = "x402 requires at least one accept configuration.";
-    } else if (x402Accepts.some((accept) => !accept.network)) {
-      x402ConfigError = "x402 accepts require a network.";
-    } else if (x402Accepts.some((accept) => !isSupportedX402Network(accept.network))) {
-      const unsupported = x402Accepts.find((accept) => !isSupportedX402Network(accept.network));
-      x402ConfigError = `unsupported x402 network '${unsupported?.network}'. Use eip155:* or solana:*.`;
-    } else if (x402Accepts.some((accept) => (accept.scheme ?? "exact") !== "exact" && !accept.asset)) {
-      x402ConfigError = "non-exact x402 accepts require an asset.";
-    } else if (x402Accepts.some(
-      (accept) => accept.decimals !== void 0 && (!Number.isInteger(accept.decimals) || accept.decimals < 0)
-    )) {
-      x402ConfigError = "x402 accept decimals must be a non-negative integer.";
-    } else if (x402Accepts.some((accept) => !accept.payTo) && !config.payeeAddress) {
-      x402ConfigError = "x402 requires payeeAddress in router config or payTo on every x402 accept.";
-    }
-  }
-  if (config.protocols?.includes("mpp")) {
-    if (!config.mpp) {
-      mppConfigError = 'protocols includes "mpp" but mpp config is missing. Add mpp: { secretKey, currency, recipient } to your router config.';
-    } else if (!config.mpp.recipient && !config.payeeAddress) {
-      mppConfigError = "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config.";
-    } else if (!(config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL)) {
-      mppConfigError = "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object.";
-    }
-  }
-  const allConfigErrors = [x402ConfigError, mppConfigError].filter(Boolean);
-  if (allConfigErrors.length > 0) {
-    for (const err of allConfigErrors) console.error(`[router] ${err}`);
+  const configIssues = getRouterConfigIssues(config, {
+    requireCdpKeys: process.env.NODE_ENV === "production"
+  });
+  const baseUrlIssue = configIssues.find((issue) => issue.code === "missing_base_url");
+  if (baseUrlIssue) throw new RouterConfigError([baseUrlIssue]);
+  const emptyProtocolsIssue = configIssues.find((issue) => issue.code === "empty_protocols");
+  if (emptyProtocolsIssue) throw new RouterConfigError([emptyProtocolsIssue]);
+  const protocolConfigIssues = configIssues.filter(
+    (issue) => issue.code !== "missing_base_url" && issue.code !== "empty_protocols"
+  );
+  const x402ConfigIssues = protocolConfigIssues.filter((issue) => issue.protocol === "x402");
+  const mppConfigIssues = protocolConfigIssues.filter((issue) => issue.protocol === "mpp");
+  const x402ConfigError = x402ConfigIssues.length > 0 ? formatRouterConfigIssues(x402ConfigIssues) : void 0;
+  const mppConfigError = mppConfigIssues.length > 0 ? formatRouterConfigIssues(mppConfigIssues) : void 0;
+  if (protocolConfigIssues.length > 0) {
+    for (const issue of protocolConfigIssues) console.error(`[router] ${issue.message}`);
     if (process.env.NODE_ENV === "production") {
-      throw new Error(allConfigErrors.join("\n"));
+      throw new RouterConfigError(protocolConfigIssues);
     }
   }
+  const resolvedBaseUrl = config.baseUrl.replace(/\/+$/, "");
   if (config.plugin?.init) {
     try {
       const result = config.plugin.init({ origin: resolvedBaseUrl });
@@ -2662,6 +3199,7 @@ function createRouter(config) {
     nonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
+    mppRecipient: config.mpp?.recipient ?? config.payeeAddress,
     network,
     x402FacilitatorsByNetwork: void 0,
     x402Accepts,
@@ -2789,9 +3327,6 @@ function createRouter(config) {
     registry
   };
 }
-function isSupportedX402Network(network) {
-  return isEvmNetwork(network) || isSolanaNetwork(network);
-}
 function normalizePath(path) {
   let normalized = path.trim();
   normalized = normalized.replace(/^\/+/, "");
@@ -2800,15 +3335,26 @@ function normalizePath(path) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BASE_NETWORK,
   HttpError,
   MemoryEntitlementStore,
   MemoryNonceStore,
   RouteBuilder,
   RouteRegistry,
+  RouterConfigError,
   SIWX_CHALLENGE_EXPIRY_MS,
   SIWX_ERROR_MESSAGES,
+  SOLANA_MAINNET_NETWORK,
+  TEMPO_USDC_CURRENCY,
+  ZERO_EVM_ADDRESS,
   consolePlugin,
   createRedisEntitlementStore,
   createRedisNonceStore,
-  createRouter
+  createRouter,
+  formatRouterConfigIssues,
+  getRouterConfigIssues,
+  mppFromEnv,
+  paidOptionsForProtocols,
+  validateRouterConfig,
+  x402AcceptsFromEnv
 });