@agentcash/router 1.4.1 → 1.5.0

package/README.md

@@ -46,7 +46,51 @@ export const env = createEnv({
 });
 ```
 
-Without these keys, x402 routes will fail to initialize (empty 402 responses, no payment header).
+Without these keys, x402 routes that use the default EVM facilitator will fail to initialize.
+Run `validateRouterConfig(config)` during startup if you want missing facilitator, MPP, or store
+configuration to throw immediately in every environment.
+
+### Recommended strict setup
+
+```typescript
+import {
+  createRouter,
+  mppFromEnv,
+  validateRouterConfig,
+  x402AcceptsFromEnv,
+  type ProtocolType,
+} from '@agentcash/router';
+
+const accepts = x402AcceptsFromEnv(process.env);
+const protocols: ProtocolType[] = process.env.MPP_SECRET_KEY ? ['x402', 'mpp'] : ['x402'];
+
+const config = {
+  payeeAddress: process.env.X402_WALLET_ADDRESS!,
+  baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
+  strictRoutes: true,
+  protocols,
+  x402: { accepts },
+  mpp: mppFromEnv(process.env, {
+    recipient: process.env.X402_WALLET_ADDRESS,
+    useDefaultStore: true,
+  }),
+  discovery: {
+    title: 'My API',
+    version: '1.0.0',
+  },
+};
+
+validateRouterConfig(config);
+export const router = createRouter(config);
+```
+
+`x402AcceptsFromEnv()` always adds Base (`BASE_NETWORK`) and also adds Solana
+mainnet (`SOLANA_MAINNET_NETWORK`) when `SOLANA_PAYEE_ADDRESS` is set. Solana
+addresses are case-sensitive and are preserved as-is.
+
+`mppFromEnv()` returns `undefined` when no MPP env vars are present. If any MPP
+env var is present, the full trio is required: `MPP_SECRET_KEY`, `MPP_CURRENCY`,
+and `TEMPO_RPC_URL`.
 
 ## Quick Start
 
@@ -143,9 +187,36 @@ Creates a `ServiceRouter` instance.
 | `plugin` | `RouterPlugin` | `undefined` | Observability plugin |
 | `prices` | `Record<string, string>` | `undefined` | Central pricing map (auto-applied) |
 | `siwx.nonceStore` | `NonceStore` | `MemoryNonceStore` | Custom nonce store |
-| `mpp` | `{ secretKey, currency, recipient? }` | `undefined` | MPP config |
+| `mpp` | `{ secretKey, currency, recipient?, rpcUrl?, useDefaultStore? }` | `undefined` | MPP config |
+| `protocols` | `('x402' \| 'mpp')[]` | `['x402']` | Default protocols for auto-priced routes |
 | `strictRoutes` | `boolean` | `false` | Enforce `route({ path })` and prevent key/path divergence |
 
+### Config validation helpers
+
+```typescript
+import {
+  BASE_NETWORK,
+  SOLANA_MAINNET_NETWORK,
+  TEMPO_USDC_CURRENCY,
+  getRouterConfigIssues,
+  mppFromEnv,
+  paidOptionsForProtocols,
+  validateRouterConfig,
+  x402AcceptsFromEnv,
+} from '@agentcash/router';
+```
+
+- `validateRouterConfig(config)` throws `RouterConfigError` with structured
+  issues. Use it when you want invalid env/config to fail at startup.
+- `getRouterConfigIssues(config)` returns the same structured issues without
+  throwing.
+- `x402AcceptsFromEnv(env)` builds Base and optional Solana x402 accepts from
+  `X402_WALLET_ADDRESS` and `SOLANA_PAYEE_ADDRESS`.
+- `mppFromEnv(env)` builds MPP config only when MPP env is present, and rejects
+  partial MPP env.
+- `paidOptionsForProtocols(protocols)` copies a protocol array into a
+  route-level `PaidOptions` object.
+
 ### Path-First Routing
 
 Use path-first route definitions to keep runtime, OpenAPI, and discovery aligned:
@@ -259,12 +330,19 @@ interface HandlerContext<TBody, TQuery> {
   query: TQuery;            // Parsed + validated
   request: NextRequest;     // Raw request
   wallet: string | null;    // Verified wallet address
+  payment: HandlerPaymentContext | null; // Payment metadata for this request
   account: unknown;         // From .apiKey() resolver
   alert: AlertFn;           // Fire observability alerts
   setVerifiedWallet: (addr: string) => void;
 }
 ```
 
+`payment` is `null` for unprotected, API-key-only, and SIWX-only requests. For
+paid requests it includes `protocol`, `status`, `payer`, `amount`, `network`,
+and best-effort recipient/transaction/receipt metadata when the protocol
+provides it. x402 handlers currently see `status: 'verified'` because settlement
+happens after a successful handler response.
+
 ### RouterPlugin
 
 Pluggable observability. All hooks are optional and fire-and-forget.

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);
 
@@ -1029,6 +1053,10 @@ 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 siwxSignatureType(network) {
   return network.startsWith("solana:") ? "ed25519" : "eip191";
 }
@@ -1047,7 +1075,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 +1083,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       requestId: meta.requestId,
       route: routeEntry.key,
       wallet,
+      payment,
       account,
       alert(level, message, alertMeta) {
         firePluginHook(deps.plugin, "onAlert", pluginCtx, {
@@ -1107,7 +1136,8 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account2,
-        body2.data
+        body2.data,
+        null
       );
       finalize(response, rawResult, meta, pluginCtx, body2.data);
       return response;
@@ -1384,7 +1414,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",
@@ -1398,7 +1437,8 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account,
-        body.data
+        body.data,
+        payment
       );
       if (response.status < 400) {
         try {
@@ -1497,7 +1537,15 @@ function createRequestHandler(routeEntry, handler, deps) {
           pluginCtx,
           wallet,
           account,
-          body.data
+          body.data,
+          {
+            protocol: "mpp",
+            status: "verified",
+            payer: wallet,
+            amount: price,
+            network: "tempo:4217",
+            recipient: deps.payeeAddress
+          }
         );
         if (response2.status < 400) {
           let mppResult2;
@@ -1630,7 +1678,17 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account,
-        body.data
+        body.data,
+        {
+          protocol: "mpp",
+          status: "settled",
+          payer: wallet,
+          amount: price,
+          network: "tempo:4217",
+          recipient: deps.payeeAddress,
+          ...txHash ? { transaction: txHash } : {},
+          ...receiptHeader ? { receipt: receiptHeader } : {}
+        }
       );
       if (response.status < 400) {
         if (routeEntry.siwxEnabled) {
@@ -2590,61 +2648,282 @@ 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 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(", ")}`);
+  }
+  return {
+    secretKey,
+    currency,
+    rpcUrl,
+    ...options.recipient ? { recipient: options.recipient } : {},
+    ...options.feePayerKey ? { feePayerKey: options.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."
+    });
+  }
+  if (!mpp.recipient && !config.payeeAddress) {
+    issues.push({
+      code: "missing_mpp_recipient",
+      protocol: "mpp",
+      message: "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config."
+    });
+  }
+  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.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 findPlaceholderPayee(values) {
+  return values.find((value) => value?.toLowerCase() === ZERO_EVM_ADDRESS) ?? 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 });
@@ -2789,9 +3068,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 +3076,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
 });

package/dist/index.d.cts

@@ -260,6 +260,17 @@ interface PaidOptions {
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
 }
+type PaymentStatus = 'verified' | 'settled';
+interface HandlerPaymentContext {
+    protocol: ProtocolType;
+    status: PaymentStatus;
+    payer: string;
+    amount: string;
+    network: string;
+    recipient?: string;
+    transaction?: string;
+    receipt?: string;
+}
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
     query: TQuery;
@@ -267,6 +278,7 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     requestId: string;
     route: string;
     wallet: string | null;
+    payment: HandlerPaymentContext | null;
     account: unknown;
     alert: AlertFn;
     setVerifiedWallet: (addr: string) => void;
@@ -640,6 +652,44 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>): (request: NextRequest) => Promise<Response>;
 }
 
+declare const BASE_NETWORK = "eip155:8453";
+declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+declare const TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50";
+declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
+
+type RouterEnv = Record<string, string | undefined>;
+type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'missing_mpp_recipient' | 'missing_mpp_rpc_url' | 'missing_mpp_default_store_env';
+interface RouterConfigIssue {
+    code: RouterConfigIssueCode;
+    message: string;
+    protocol?: ProtocolType;
+}
+interface RouterConfigValidationOptions {
+    env?: RouterEnv;
+    requireCdpKeys?: boolean;
+}
+declare class RouterConfigError extends Error {
+    readonly issues: RouterConfigIssue[];
+    constructor(issues: RouterConfigIssue[]);
+}
+declare function validateRouterConfig(config: RouterConfig, options?: RouterConfigValidationOptions): void;
+declare function getRouterConfigIssues(config: RouterConfig, options?: RouterConfigValidationOptions): RouterConfigIssue[];
+declare function formatRouterConfigIssues(issues: readonly RouterConfigIssue[]): string;
+declare function mppFromEnv(env: RouterEnv, options?: {
+    recipient?: string;
+    require?: boolean;
+    useDefaultStore?: boolean;
+    feePayerKey?: string;
+}): RouterConfig['mpp'] | undefined;
+declare function x402AcceptsFromEnv(env: RouterEnv, options?: {
+    payeeAddress?: string;
+    payeeEnv?: string;
+    network?: string;
+    solanaPayeeAddress?: string;
+    solanaPayeeEnv?: string;
+}): X402AcceptConfig[];
+declare function paidOptionsForProtocols(protocols: readonly ProtocolType[]): PaidOptions;
+
 interface MonitorEntry {
     provider: string;
     route: string;
@@ -660,4 +710,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementEvent, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, x402AcceptsFromEnv };

package/dist/index.d.ts

@@ -260,6 +260,17 @@ interface PaidOptions {
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
 }
+type PaymentStatus = 'verified' | 'settled';
+interface HandlerPaymentContext {
+    protocol: ProtocolType;
+    status: PaymentStatus;
+    payer: string;
+    amount: string;
+    network: string;
+    recipient?: string;
+    transaction?: string;
+    receipt?: string;
+}
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
     query: TQuery;
@@ -267,6 +278,7 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     requestId: string;
     route: string;
     wallet: string | null;
+    payment: HandlerPaymentContext | null;
     account: unknown;
     alert: AlertFn;
     setVerifiedWallet: (addr: string) => void;
@@ -640,6 +652,44 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>): (request: NextRequest) => Promise<Response>;
 }
 
+declare const BASE_NETWORK = "eip155:8453";
+declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+declare const TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50";
+declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
+
+type RouterEnv = Record<string, string | undefined>;
+type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'missing_mpp_recipient' | 'missing_mpp_rpc_url' | 'missing_mpp_default_store_env';
+interface RouterConfigIssue {
+    code: RouterConfigIssueCode;
+    message: string;
+    protocol?: ProtocolType;
+}
+interface RouterConfigValidationOptions {
+    env?: RouterEnv;
+    requireCdpKeys?: boolean;
+}
+declare class RouterConfigError extends Error {
+    readonly issues: RouterConfigIssue[];
+    constructor(issues: RouterConfigIssue[]);
+}
+declare function validateRouterConfig(config: RouterConfig, options?: RouterConfigValidationOptions): void;
+declare function getRouterConfigIssues(config: RouterConfig, options?: RouterConfigValidationOptions): RouterConfigIssue[];
+declare function formatRouterConfigIssues(issues: readonly RouterConfigIssue[]): string;
+declare function mppFromEnv(env: RouterEnv, options?: {
+    recipient?: string;
+    require?: boolean;
+    useDefaultStore?: boolean;
+    feePayerKey?: string;
+}): RouterConfig['mpp'] | undefined;
+declare function x402AcceptsFromEnv(env: RouterEnv, options?: {
+    payeeAddress?: string;
+    payeeEnv?: string;
+    network?: string;
+    solanaPayeeAddress?: string;
+    solanaPayeeEnv?: string;
+}): X402AcceptConfig[];
+declare function paidOptionsForProtocols(protocols: readonly ProtocolType[]): PaidOptions;
+
 interface MonitorEntry {
     provider: string;
     route: string;
@@ -660,4 +710,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementEvent, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, x402AcceptsFromEnv };

package/dist/index.js

@@ -166,6 +166,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;
@@ -179,7 +191,7 @@ function getConfiguredX402Accepts(config) {
   return [
     {
       scheme: "exact",
-      network: config.network ?? "eip155:8453",
+      network: config.network ?? BASE_NETWORK,
       payTo: config.payeeAddress
     }
   ];
@@ -208,6 +220,7 @@ async function resolveX402Accepts(request, routeEntry, accepts, fallbackPayTo, b
 var init_x402_config = __esm({
   "src/x402-config.ts"() {
     "use strict";
+    init_constants();
   }
 });
 
@@ -990,6 +1003,10 @@ 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 siwxSignatureType(network) {
   return network.startsWith("solana:") ? "ed25519" : "eip191";
 }
@@ -1008,7 +1025,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),
@@ -1016,6 +1033,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       requestId: meta.requestId,
       route: routeEntry.key,
       wallet,
+      payment,
       account,
       alert(level, message, alertMeta) {
         firePluginHook(deps.plugin, "onAlert", pluginCtx, {
@@ -1068,7 +1086,8 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account2,
-        body2.data
+        body2.data,
+        null
       );
       finalize(response, rawResult, meta, pluginCtx, body2.data);
       return response;
@@ -1345,7 +1364,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",
@@ -1359,7 +1387,8 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account,
-        body.data
+        body.data,
+        payment
       );
       if (response.status < 400) {
         try {
@@ -1458,7 +1487,15 @@ function createRequestHandler(routeEntry, handler, deps) {
           pluginCtx,
           wallet,
           account,
-          body.data
+          body.data,
+          {
+            protocol: "mpp",
+            status: "verified",
+            payer: wallet,
+            amount: price,
+            network: "tempo:4217",
+            recipient: deps.payeeAddress
+          }
         );
         if (response2.status < 400) {
           let mppResult2;
@@ -1591,7 +1628,17 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx,
         wallet,
         account,
-        body.data
+        body.data,
+        {
+          protocol: "mpp",
+          status: "settled",
+          payer: wallet,
+          amount: price,
+          network: "tempo:4217",
+          recipient: deps.payeeAddress,
+          ...txHash ? { transaction: txHash } : {},
+          ...receiptHeader ? { receipt: receiptHeader } : {}
+        }
       );
       if (response.status < 400) {
         if (routeEntry.siwxEnabled) {
@@ -2551,61 +2598,282 @@ 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 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(", ")}`);
+  }
+  return {
+    secretKey,
+    currency,
+    rpcUrl,
+    ...options.recipient ? { recipient: options.recipient } : {},
+    ...options.feePayerKey ? { feePayerKey: options.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."
+    });
+  }
+  if (!mpp.recipient && !config.payeeAddress) {
+    issues.push({
+      code: "missing_mpp_recipient",
+      protocol: "mpp",
+      message: "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config."
+    });
+  }
+  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.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 findPlaceholderPayee(values) {
+  return values.find((value) => value?.toLowerCase() === ZERO_EVM_ADDRESS) ?? 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 });
@@ -2750,9 +3018,6 @@ function createRouter(config) {
     registry
   };
 }
-function isSupportedX402Network(network) {
-  return isEvmNetwork(network) || isSolanaNetwork(network);
-}
 function normalizePath(path) {
   let normalized = path.trim();
   normalized = normalized.replace(/^\/+/, "");
@@ -2760,15 +3025,26 @@ function normalizePath(path) {
   return normalized.replace(/\/+$/, "");
 }
 export {
+  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
 };

package/package.json

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