@agentcash/router 1.7.1 → 1.9.0

package/dist/index.js

@@ -45,6 +45,9 @@ function getConfiguredX402Accepts(config) {
 function getConfiguredX402Networks(config) {
   return [...new Set(getConfiguredX402Accepts(config).map((accept) => accept.network))];
 }
+function selectRouteAccepts(accepts, routeEntry) {
+  return routeEntry.billing === "upto" ? accepts.filter((accept) => accept.scheme === "upto") : accepts.filter((accept) => (accept.scheme ?? "exact") !== "upto");
+}
 async function resolveX402Accepts(request, routeEntry, accepts, fallbackPayTo, body) {
   return Promise.all(
     accepts.map(async (accept) => ({
@@ -340,9 +343,18 @@ function withScopedKinds(client, kinds) {
   return {
     verify: client.verify.bind(client),
     settle: client.settle.bind(client),
-    getSupported: async () => ({ ...await client.getSupported(), kinds })
+    getSupported: async () => {
+      const live = await client.getSupported();
+      return { ...live, kinds: mergeKindExtras(kinds, live.kinds) };
+    }
   };
 }
+function mergeKindExtras(scoped, live) {
+  return scoped.map((kind) => {
+    const match = live.find((l) => l.scheme === kind.scheme && l.network === kind.network);
+    return match?.extra ? { ...kind, extra: { ...kind.extra, ...match.extra } } : kind;
+  });
+}
 function buildSupportedKinds(group) {
   return group.networks.flatMap((network) => {
     if (group.family === "solana") {
@@ -551,7 +563,8 @@ function preflight(routeEntry, handler, deps, request) {
     request,
     meta,
     pluginCtx,
-    report: createReporter(deps.plugin, pluginCtx, routeEntry.key)
+    report: createReporter(deps.plugin, pluginCtx, routeEntry.key),
+    query: void 0
   };
 }
 function buildMeta(request, routeEntry) {
@@ -574,13 +587,19 @@ function buildMeta(request, routeEntry) {
 import { NextResponse } from "next/server";
 
 // src/pipeline/body.ts
+var MalformedJsonError = class extends Error {
+  constructor() {
+    super("Invalid JSON");
+    this.name = "MalformedJsonError";
+  }
+};
 async function bufferBody(request) {
   const text = await request.text();
-  if (!text) return void 0;
+  if (!text.trim()) return void 0;
   try {
     return JSON.parse(text);
   } catch {
-    return void 0;
+    throw new MalformedJsonError();
   }
 }
 function validateBody(parsed, schema) {
@@ -661,7 +680,18 @@ function computeQuotaLevel(remaining, warn, critical) {
 // src/pipeline/steps/parse-body.ts
 async function parseBody(ctx, request = ctx.request) {
   if (!ctx.routeEntry.bodySchema) return { ok: true, data: void 0 };
-  const raw = await bufferBody(request);
+  let raw;
+  try {
+    raw = await bufferBody(request);
+  } catch (err) {
+    if (!(err instanceof MalformedJsonError)) throw err;
+    const response2 = NextResponse.json(
+      { success: false, error: "Invalid JSON", issues: [] },
+      { status: 400 }
+    );
+    firePluginResponse(ctx, response2);
+    return { ok: false, response: response2 };
+  }
   const result = validateBody(raw, ctx.routeEntry.bodySchema);
   if (result.success) return { ok: true, data: result.data };
   const response = NextResponse.json(
@@ -672,6 +702,22 @@ async function parseBody(ctx, request = ctx.request) {
   return { ok: false, response };
 }
 
+// src/pipeline/steps/parse-query.ts
+import { NextResponse as NextResponse2 } from "next/server";
+function validateQuery(ctx) {
+  const { querySchema } = ctx.routeEntry;
+  if (!querySchema) return { ok: true, data: void 0 };
+  const params = Object.fromEntries(ctx.request.nextUrl.searchParams.entries());
+  const result = validateBody(params, querySchema);
+  if (result.success) return { ok: true, data: result.data };
+  const response = NextResponse2.json(
+    { success: false, error: result.error, issues: result.issues },
+    { status: 400 }
+  );
+  firePluginResponse(ctx, response);
+  return { ok: false, response };
+}
+
 // src/pipeline/steps/errors.ts
 function errorStatus(error, fallback) {
   const status = error?.status;
@@ -686,9 +732,9 @@ function handlerFailureError(response) {
 }
 
 // src/pipeline/steps/fail.ts
-import { NextResponse as NextResponse2 } from "next/server";
+import { NextResponse as NextResponse3 } from "next/server";
 function fail(ctx, status, message, requestBody) {
-  const response = NextResponse2.json({ success: false, error: message }, { status });
+  const response = NextResponse3.json({ success: false, error: message }, { status });
   firePluginResponse(ctx, response, requestBody);
   return response;
 }
@@ -705,7 +751,7 @@ async function runValidate(ctx, body) {
 }
 
 // src/pipeline/flows/static/static-invoke.ts
-import { NextResponse as NextResponse3 } from "next/server";
+import { NextResponse as NextResponse4 } from "next/server";
 
 // src/types.ts
 var HttpError = class extends Error {
@@ -716,14 +762,6 @@ var HttpError = class extends Error {
   }
 };
 
-// src/pipeline/steps/parse-query.ts
-function parseQuery(request, routeEntry) {
-  if (!routeEntry.querySchema) return void 0;
-  const params = Object.fromEntries(request.nextUrl.searchParams.entries());
-  const result = routeEntry.querySchema.safeParse(params);
-  return result.success ? result.data : params;
-}
-
 // src/pipeline/flows/static/static-invoke.ts
 function invokePaidStatic(ctx, wallet, account, body, payment) {
   return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment));
@@ -734,7 +772,7 @@ function invokeUnauthed(ctx, wallet, account, body) {
 function buildHandlerCtx(ctx, wallet, account, body, payment) {
   return {
     body,
-    query: parseQuery(ctx.request, ctx.routeEntry),
+    query: ctx.query,
     request: ctx.request,
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
@@ -754,10 +792,7 @@ async function runHandler(ctx, handlerCtx) {
   }
   if (isAsyncIterable(returned) && !isThenable(returned)) {
     return errorResult(
-      new HttpError(
-        `route '${ctx.routeEntry.key}': streaming handlers require .paid({ dynamic: true })`,
-        500
-      )
+      new HttpError(`route '${ctx.routeEntry.key}': streaming handlers require .metered()`, 500)
     );
   }
   let rawResult;
@@ -766,14 +801,14 @@ async function runHandler(ctx, handlerCtx) {
   } catch (error) {
     return errorResult(error);
   }
-  const response = rawResult instanceof Response ? rawResult : NextResponse3.json(rawResult);
+  const response = rawResult instanceof Response ? rawResult : NextResponse4.json(rawResult);
   return { response, rawResult };
 }
 function errorResult(error) {
   const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
   const message = error instanceof Error ? error.message : "Internal error";
   return {
-    response: NextResponse3.json({ success: false, error: message }, { status }),
+    response: NextResponse4.json({ success: false, error: message }, { status }),
     rawResult: void 0,
     handlerError: error
   };
@@ -1186,10 +1221,12 @@ var DynamicPricing = class {
   }
   needsBody = true;
   async quote(body) {
+    let priced;
     try {
       const raw = await this.opts.fn(body);
-      return this.cap(raw, body);
+      priced = this.cap(raw, body);
     } catch (err) {
+      if (err instanceof HttpError) throw err;
       this.alert("error", `Pricing function failed: ${msg(err)}`, {
         error: err instanceof Error ? err.stack : String(err),
         body
@@ -1200,6 +1237,13 @@ var DynamicPricing = class {
       }
       throw err;
     }
+    if (!isPositiveDecimal(priced)) {
+      throw new HttpError(
+        `route '${this.opts.route ?? "unknown"}': dynamic pricing returned an invalid amount '${priced}'`,
+        500
+      );
+    }
+    return priced;
   }
   challengeQuote(body) {
     if (body === void 0) return Promise.resolve(this.opts.maxPrice ?? "0");
@@ -1274,14 +1318,14 @@ var TieredPricing = class {
       `Unknown tier '${tierKey}' for field '${field}'. Valid tiers: ${Object.keys(tiers).join(", ")}`
     );
   }
-  challengeQuote(body) {
+  async challengeQuote(body) {
     if (body !== void 0) {
       try {
-        return this.quote(body);
+        return await this.quote(body);
       } catch {
       }
     }
-    return Promise.resolve(this.maxTierPrice());
+    return this.maxTierPrice();
   }
   describe() {
     return {
@@ -1712,7 +1756,7 @@ var mppStrategy = {
   async verify(args) {
     const info = readMppCredential(args.request);
     if (!info) return { ok: false, kind: "invalid" };
-    if (args.routeEntry.dynamicPrice) {
+    if (args.routeEntry.billing === "metered") {
       if (!info.sessionAction) return { ok: false, kind: "invalid" };
       return verifySessionMode(args, info);
     }
@@ -1763,7 +1807,7 @@ var mppStrategy = {
   async buildChallenge(args) {
     if (!args.deps.mppx) return {};
     const sessionsConfigured = args.deps.mppSessionConfig && (args.deps.mppx.sessionRequest || args.deps.mppx.sessionStream);
-    if (args.routeEntry.dynamicPrice && sessionsConfigured) {
+    if (args.routeEntry.billing === "metered" && sessionsConfigured) {
       const tickCost = args.routeEntry.tickCost;
       const computedDeposit = tickCost !== void 0 ? multiplyDecimal(tickCost, args.deps.mppSessionConfig.depositMultiplier) : void 0;
       const suggestedDeposit = args.routeEntry.maxPrice ?? computedDeposit ?? args.price;
@@ -2015,7 +2059,7 @@ async function settleX402Payment(server, payload, requirements, amountOverride)
   };
 }
 function tagBareDecimalAsDollars(amount) {
-  if (/^\d+\.\d+$/.test(amount)) return `$${amount}`;
+  if (/^\d+(?:\.\d+)?$/.test(amount)) return `$${amount}`;
   return amount;
 }
 
@@ -2140,7 +2184,7 @@ async function verifyX402(args) {
   const accepts = await resolveX402Accepts(
     request,
     routeEntry,
-    deps.x402Accepts,
+    selectRouteAccepts(deps.x402Accepts, routeEntry),
     deps.payeeAddress,
     body
   );
@@ -2188,7 +2232,7 @@ async function verifyX402(args) {
 async function settleX402(args) {
   const { response, payment, token, deps, routeEntry, billedAmount, report } = args;
   const { payload, requirements } = token;
-  const override = routeEntry.dynamicPrice ? { amount: billedAmount } : void 0;
+  const override = routeEntry.billing === "exact" ? void 0 : { amount: billedAmount };
   try {
     const settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
     if (!settle.result?.success) {
@@ -2218,7 +2262,7 @@ async function buildX402ChallengeContribution(args) {
   const accepts = await resolveX402Accepts(
     request,
     routeEntry,
-    deps.x402Accepts,
+    selectRouteAccepts(deps.x402Accepts, routeEntry),
     deps.payeeAddress,
     body
   );
@@ -2262,8 +2306,8 @@ function getAllowedStrategies(allowed) {
   return allowed.map((name) => STRATEGIES[name]);
 }
 
-// src/pipeline/flows/build402.ts
-import { NextResponse as NextResponse4 } from "next/server";
+// src/pipeline/flows/challenge-response.ts
+import { NextResponse as NextResponse5 } from "next/server";
 
 // src/pipeline/challenge-extensions.ts
 init_evm();
@@ -2279,20 +2323,17 @@ async function buildChallengeExtensions(ctx) {
     });
     const inputSchema = routeEntry.bodySchema ? toJSON(routeEntry.bodySchema) : routeEntry.querySchema ? toJSON(routeEntry.querySchema) : void 0;
     const outputSchema = routeEntry.outputSchema ? toJSON(routeEntry.outputSchema) : void 0;
-    if (inputSchema) {
-      const config = {
-        method: routeEntry.method,
-        bodyType: routeEntry.bodySchema ? "json" : void 0,
-        inputSchema
-      };
-      if (routeEntry.inputExample !== void 0) {
-        config.input = routeEntry.inputExample;
-      }
-      if (outputSchema && routeEntry.outputExample !== void 0) {
-        config.output = { schema: outputSchema, example: routeEntry.outputExample };
-      }
-      extensions = declareDiscoveryExtension(config);
+    const isBodyMethod = routeEntry.method === "POST" || routeEntry.method === "PUT" || routeEntry.method === "PATCH";
+    const config = { method: routeEntry.method };
+    if (isBodyMethod) config.bodyType = "json";
+    if (inputSchema) config.inputSchema = inputSchema;
+    if (routeEntry.inputExample !== void 0) {
+      config.input = routeEntry.inputExample;
+    }
+    if (outputSchema && routeEntry.outputExample !== void 0) {
+      config.output = { schema: outputSchema, example: routeEntry.outputExample };
     }
+    extensions = declareDiscoveryExtension(config);
   } catch (err) {
     ctx.report(
       "warn",
@@ -2311,9 +2352,7 @@ async function buildChallengeExtensions(ctx) {
     } catch {
     }
   }
-  const hasEvmUpto = ctx.deps.x402Accepts.some(
-    (accept) => accept.scheme === "upto" && isEvmNetwork(accept.network)
-  );
+  const hasEvmUpto = ctx.routeEntry.billing === "upto" && ctx.deps.x402Accepts.some((accept) => accept.scheme === "upto" && isEvmNetwork(accept.network));
   if (hasEvmUpto) {
     try {
       const { declareEip2612GasSponsoringExtension } = await import("@x402/extensions");
@@ -2331,14 +2370,14 @@ async function buildChallengeExtensions(ctx) {
   return extensions;
 }
 
-// src/pipeline/flows/build402.ts
-async function build402(ctx, pricing, body, failure) {
+// src/pipeline/flows/challenge-response.ts
+async function buildChallengeResponse(ctx, pricing, body, failure) {
   let challengePrice;
   try {
     challengePrice = pricing ? await pricing.challengeQuote(body) : "0";
   } catch (err) {
     const message = errorMessage(err, "Price calculation failed");
-    const errorResponse = NextResponse4.json(
+    const errorResponse = NextResponse5.json(
       { success: false, error: message },
       { status: errorStatus(err, 500) }
     );
@@ -2347,7 +2386,7 @@ async function build402(ctx, pricing, body, failure) {
   }
   const extensions = await buildChallengeExtensions(ctx);
   const responseBody = failure ? JSON.stringify({ error: failure.message ?? null, reason: failure.reason }) : null;
-  const response = new NextResponse4(responseBody, {
+  const response = new NextResponse5(responseBody, {
     status: 402,
     headers: {
       "Content-Type": "application/json",
@@ -2374,7 +2413,7 @@ async function build402(ctx, pricing, body, failure) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
       if (strategy.protocol === "x402") {
-        const errorResponse = NextResponse4.json(
+        const errorResponse = NextResponse5.json(
           { success: false, error: message },
           { status: 500 }
         );
@@ -2426,7 +2465,7 @@ function surrogatePriceForSkippedBody(routeEntry) {
 }
 
 // src/pipeline/flows/dynamic/dynamic-channel-mgmt.ts
-import { NextResponse as NextResponse5 } from "next/server";
+import { NextResponse as NextResponse6 } from "next/server";
 async function runDynamicChannelMgmtFlow(args) {
   const { ctx, strategy, account, pricing, skipBody } = args;
   const { request, routeEntry, deps, report } = ctx;
@@ -2445,7 +2484,7 @@ async function runDynamicChannelMgmtFlow(args) {
     if (verifyOutcome.kind === "config") {
       return fail(ctx, 500, verifyOutcome.message, parsedBody);
     }
-    return build402(ctx, pricing, parsedBody, verifyOutcome.failure);
+    return buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure);
   }
   ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
   firePaymentVerified(ctx, {
@@ -2454,7 +2493,7 @@ async function runDynamicChannelMgmtFlow(args) {
     amount: price,
     network: verifyOutcome.payment.network
   });
-  const synthetic = new NextResponse5(null, { status: 200 });
+  const synthetic = new NextResponse6(null, { status: 200 });
   const settleScope = {
     wallet: verifyOutcome.wallet,
     account,
@@ -2480,10 +2519,7 @@ async function runDynamicChannelMgmtFlow(args) {
   });
 }
 
-// src/pipeline/flows/dynamic/dynamic-invoke.ts
-import { NextResponse as NextResponse6 } from "next/server";
-
-// src/pricing/charge-context.ts
+// src/pricing/metered-charge.ts
 function createChargeContext(args) {
   const { tickCost, maxPrice, route } = args;
   const tickAtomic = decimalToAtomic(tickCost);
@@ -2518,17 +2554,12 @@ function createChargeContext(args) {
   };
 }
 
-// src/pipeline/flows/dynamic/dynamic-invoke.ts
-async function invokeDynamic(ctx, wallet, account, body, payment) {
-  const streaming = ctx.routeEntry.streaming === true;
-  const chargeContext = streaming ? createChargeContext({
-    tickCost: ctx.routeEntry.tickCost,
-    maxPrice: ctx.routeEntry.maxPrice,
-    route: ctx.routeEntry.key
-  }) : null;
-  const baseHandlerCtx = {
+// src/pipeline/flows/dynamic/dynamic-invoke/shared.ts
+import { NextResponse as NextResponse7 } from "next/server";
+function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
+  return {
     body,
-    query: parseQuery(ctx.request, ctx.routeEntry),
+    query: ctx.query,
     request: ctx.request,
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
@@ -2538,12 +2569,41 @@ async function invokeDynamic(ctx, wallet, account, body, payment) {
     alert: ctx.report,
     setVerifiedWallet: (addr) => ctx.pluginCtx.setVerifiedWallet(addr)
   };
+}
+function toResponse(rawResult) {
+  return rawResult instanceof Response ? rawResult : NextResponse7.json(rawResult);
+}
+function errorResult2(error) {
+  const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
+  const message = error instanceof Error ? error.message : "Internal error";
+  return {
+    kind: "request",
+    response: NextResponse7.json({ success: false, error: message }, { status }),
+    rawResult: void 0,
+    handlerError: error
+  };
+}
+function isAsyncIterable2(value) {
+  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function isThenable2(value) {
+  return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+
+// src/pipeline/flows/dynamic/dynamic-invoke/metered-invoke.ts
+async function invokeMetered(ctx, wallet, account, body, payment) {
+  const chargeContext = ctx.routeEntry.streaming ? createChargeContext({
+    tickCost: ctx.routeEntry.tickCost,
+    maxPrice: ctx.routeEntry.maxPrice,
+    route: ctx.routeEntry.key
+  }) : null;
+  const baseHandlerCtx = buildBaseHandlerCtx(ctx, wallet, account, body, payment);
   const handlerCtx = chargeContext !== null ? { ...baseHandlerCtx, charge: chargeContext.charge } : baseHandlerCtx;
   let returned;
   try {
     returned = ctx.handler(handlerCtx);
   } catch (error) {
-    return errorResult2(error, chargeContext);
+    return errorResult2(error);
   }
   if (isAsyncIterable2(returned) && !isThenable2(returned)) {
     if (!chargeContext) {
@@ -2551,41 +2611,80 @@ async function invokeDynamic(ctx, wallet, account, body, payment) {
         new HttpError(
           "route returned an async iterable from a non-streaming handler \u2014 use .stream(async function*(...)) instead of .handler() to opt into streaming",
           500
-        ),
-        null
+        )
       );
     }
-    return {
-      kind: "stream",
-      source: returned,
-      chargeContext
-    };
+    return { kind: "stream", source: returned, chargeContext };
   }
   let rawResult;
   try {
     rawResult = await returned;
   } catch (error) {
-    return errorResult2(error, chargeContext);
+    return errorResult2(error);
   }
-  const response = rawResult instanceof Response ? rawResult : NextResponse6.json(rawResult);
-  return { kind: "request", response, rawResult };
+  return { kind: "request", response: toResponse(rawResult), rawResult };
 }
-function errorResult2(error, chargeContext) {
-  const status = error instanceof HttpError ? error.status : typeof error?.status === "number" ? error.status : 500;
-  const message = error instanceof Error ? error.message : "Internal error";
-  void chargeContext;
+
+// src/pricing/upto-charge.ts
+function createUptoChargeContext(args) {
+  const { maxPrice, route } = args;
+  const capAtomic = decimalToAtomic(maxPrice);
+  if (capAtomic <= 0n) {
+    throw new Error(`route '${route}': maxPrice '${maxPrice}' must be a positive decimal string`);
+  }
+  let calls = 0;
+  let atomic = 0n;
+  const charge = async (amount) => {
+    const nextAtomic = atomic + decimalToAtomic(amount);
+    if (nextAtomic > capAtomic) {
+      throw Object.assign(
+        new Error(
+          `route '${route}': charge() running total ($${atomicToDecimal(nextAtomic)}) exceeds maxPrice ($${atomicToDecimal(capAtomic)})`
+        ),
+        { status: 400, code: "CHARGE_OVER_CAP" }
+      );
+    }
+    calls += 1;
+    atomic = nextAtomic;
+  };
   return {
-    kind: "request",
-    response: NextResponse6.json({ success: false, error: message }, { status }),
-    rawResult: void 0,
-    handlerError: error
+    charge,
+    callCount: () => calls,
+    atomicTotal: () => atomic
   };
 }
-function isAsyncIterable2(value) {
-  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
-}
-function isThenable2(value) {
-  return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+
+// src/pipeline/flows/dynamic/dynamic-invoke/upto-invoke.ts
+async function invokeUpto(ctx, wallet, account, body, payment) {
+  const uptoCtx = createUptoChargeContext({
+    maxPrice: ctx.routeEntry.maxPrice,
+    route: ctx.routeEntry.key
+  });
+  const handlerCtx = {
+    ...buildBaseHandlerCtx(ctx, wallet, account, body, payment),
+    charge: uptoCtx.charge
+  };
+  let returned;
+  try {
+    returned = ctx.handler(handlerCtx);
+  } catch (error) {
+    return errorResult2(error);
+  }
+  if (isAsyncIterable2(returned) && !isThenable2(returned)) {
+    return errorResult2(
+      new HttpError(
+        "streaming is not supported on .upTo() routes \u2014 return a value from .handler() instead",
+        500
+      )
+    );
+  }
+  let rawResult;
+  try {
+    rawResult = await returned;
+  } catch (error) {
+    return errorResult2(error);
+  }
+  return { kind: "request", response: toResponse(rawResult), rawResult, uptoContext: uptoCtx };
 }
 
 // src/pipeline/flows/dynamic/dynamic-preflight.ts
@@ -2615,7 +2714,7 @@ async function runDynamicRequestFlow(args) {
   }
   const beforeErr = await runBeforeSettle(ctx, settleScope);
   if (beforeErr) return beforeErr;
-  const billedAmount = routeEntry.tickCost;
+  const billedAmount = computeBilledAmount(routeEntry, result);
   return settleAndFinalizeRequest({
     ctx,
     strategy,
@@ -2633,6 +2732,19 @@ async function runDynamicRequestFlow(args) {
     }
   });
 }
+function computeBilledAmount(routeEntry, result) {
+  if (routeEntry.billing === "upto") {
+    const total = result.uptoContext?.atomicTotal() ?? 0n;
+    if (total <= 0n) {
+      throw new HttpError(
+        `route '${routeEntry.key}': handler did not call charge(amount) \u2014 upto routes must accumulate a non-zero billed amount`,
+        500
+      );
+    }
+    return atomicToDecimal(total);
+  }
+  return routeEntry.tickCost;
+}
 
 // src/pipeline/flows/dynamic/dynamic-stream.ts
 async function runDynamicStreamFlow(args) {
@@ -2669,7 +2781,7 @@ async function runDynamicPaidFlow(ctx) {
   if (!incomingStrategy) {
     const initError = protocolInitError(routeEntry, deps);
     if (initError) return fail(ctx, 500, initError);
-    return build402(ctx, pricing, earlyBody);
+    return buildChallengeResponse(ctx, pricing, earlyBody);
   }
   const { skipBody, skipHandler } = resolveDynamicPreflight(incomingStrategy, request, routeEntry);
   if (skipHandler) {
@@ -2696,7 +2808,7 @@ async function runDynamicPaidFlow(ctx) {
     if (verifyOutcome.kind === "config") {
       return fail(ctx, 500, verifyOutcome.message, parsedBody);
     }
-    return build402(ctx, pricing, parsedBody, verifyOutcome.failure);
+    return buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure);
   }
   ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
   firePaymentVerified(ctx, {
@@ -2705,13 +2817,7 @@ async function runDynamicPaidFlow(ctx) {
     amount: price,
     network: verifyOutcome.payment.network
   });
-  const result = await invokeDynamic(
-    ctx,
-    verifyOutcome.wallet,
-    account,
-    parsedBody,
-    verifyOutcome.payment
-  );
+  const result = await invokeDynamic(ctx, verifyOutcome, account, parsedBody);
   switch (result.kind) {
     case "stream":
       return runDynamicStreamFlow({
@@ -2733,6 +2839,18 @@ async function runDynamicPaidFlow(ctx) {
       });
   }
 }
+async function invokeDynamic(ctx, verifyOutcome, account, parsedBody) {
+  switch (ctx.routeEntry.billing) {
+    case "upto":
+      return invokeUpto(ctx, verifyOutcome.wallet, account, parsedBody, verifyOutcome.payment);
+    case "metered":
+      return invokeMetered(ctx, verifyOutcome.wallet, account, parsedBody, verifyOutcome.payment);
+    case "exact":
+      throw new Error(
+        `route '${ctx.routeEntry.key}': exact billing must not reach the dynamic paid flow`
+      );
+  }
+}
 
 // src/pipeline/flows/static/static-body-and-price.ts
 async function resolveStaticBodyAndPrice(args) {
@@ -2834,7 +2952,7 @@ async function runStaticPaidFlow(ctx) {
   if (!incomingStrategy) {
     const initError = protocolInitError(routeEntry, deps);
     if (initError) return fail(ctx, 500, initError);
-    return build402(ctx, pricing, earlyBody);
+    return buildChallengeResponse(ctx, pricing, earlyBody);
   }
   const bodyAndPrice = await resolveStaticBodyAndPrice({ ctx, pricing });
   if (!bodyAndPrice.ok) return bodyAndPrice.response;
@@ -2851,7 +2969,7 @@ async function runStaticPaidFlow(ctx) {
     if (verifyOutcome.kind === "config") {
       return fail(ctx, 500, verifyOutcome.message, parsedBody);
     }
-    return build402(ctx, pricing, parsedBody, verifyOutcome.failure);
+    return buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure);
   }
   ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
   firePaymentVerified(ctx, {
@@ -2880,17 +2998,12 @@ async function runStaticPaidFlow(ctx) {
 
 // src/pipeline/flows/paid.ts
 async function runPaidFlow(ctx) {
-  const dynamicPrice = ctx.routeEntry.dynamicPrice ?? false;
-  switch (dynamicPrice) {
-    case true:
-      return runDynamicPaidFlow(ctx);
-    case false:
-      return runStaticPaidFlow(ctx);
-  }
+  const handlerCharged = ctx.routeEntry.billing !== "exact";
+  return handlerCharged ? runDynamicPaidFlow(ctx) : runStaticPaidFlow(ctx);
 }
 
 // src/pipeline/flows/siwx-only.ts
-import { NextResponse as NextResponse7 } from "next/server";
+import { NextResponse as NextResponse8 } from "next/server";
 
 // src/kv-store/client.ts
 var BIGINT_SUFFIX = "#__bigint";
@@ -3124,7 +3237,7 @@ async function runSiwxOnlyFlow(ctx) {
   }
   const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
   if (!siwx.valid) {
-    const response = NextResponse7.json(
+    const response = NextResponse8.json(
       { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
       { status: 402 }
     );
@@ -3185,7 +3298,7 @@ async function buildSiwxChallenge(ctx) {
       `SIWX challenge header encoding failed: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  const response = new NextResponse7(JSON.stringify(paymentRequired), {
+  const response = new NextResponse8(JSON.stringify(paymentRequired), {
     status: 402,
     headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
   });
@@ -3231,6 +3344,9 @@ function createRequestHandler(routeEntry, handler, deps) {
   return async (request) => {
     await deps.initPromise;
     const ctx = preflight(routeEntry, handler, deps, request);
+    const query = validateQuery(ctx);
+    if (!query.ok) return query.response;
+    ctx.query = query.data;
     if (routeEntry.authMode === "unprotected") return runUnprotectedFlow(ctx);
     if (routeEntry.authMode === "siwx") return runSiwxOnlyFlow(ctx);
     if (routeEntry.pricing) return runPaidFlow(ctx);
@@ -3284,7 +3400,7 @@ var RouteBuilder = class _RouteBuilder {
       protocols: defaults?.protocols ? [...defaults.protocols] : ["x402"],
       maxPrice: void 0,
       minPrice: void 0,
-      dynamicPrice: false,
+      billing: "exact",
       tickCost: void 0,
       unitType: void 0,
       payTo: void 0,
@@ -3315,39 +3431,84 @@ var RouteBuilder = class _RouteBuilder {
     next.#s = { ...this.#s, protocols: [...this.#s.protocols] };
     return next;
   }
-  paid(pricingOrOptions, options) {
-    const { pricing, resolvedOptions } = resolvePaidArgs(this.#s.key, pricingOrOptions, options);
+  paid(arg, options) {
+    return this.applyPaid(normalizePaidArg(this.#s.key, arg, options), "paid");
+  }
+  /**
+   * x402-only handler-computed billing. The handler receives `charge(amount)`
+   * and the request settles once for the accumulated total, capped at
+   * `maxPrice`. Requires an `'upto'` accept on at least one configured network.
+   * Pass a bare string as sugar for `{ maxPrice }`.
+   *
+   * @example
+   * ```ts
+   * router.route('llm')
+   *   .upTo('0.05')
+   *   .body(schema)
+   *   .handler(async ({ body, charge }) => { await charge('0.001'); ... });
+   * ```
+   */
+  upTo(arg) {
+    return this.applyPaid(normalizeUpToArg(this.#s.key, arg), "upTo");
+  }
+  /**
+   * MPP-only per-tick billing. `.handler()` bills exactly `tickCost`;
+   * `.stream()` calls `charge()` (no-arg) per yield, settling per tick up to
+   * `maxPrice`. Requires `RouterConfig.mpp.session`.
+   *
+   * @example
+   * ```ts
+   * router.route('llm/stream')
+   *   .metered({ tickCost: '0.0001', maxPrice: '0.05', unitType: 'token' })
+   *   .stream(async function* ({ charge }) { await charge(); yield 'hi'; });
+   * ```
+   */
+  metered(options) {
+    return this.applyPaid(normalizeMeteredArg(this.#s.key, options), "metered");
+  }
+  applyPaid(normalized, method) {
+    const { pricing, resolvedOptions, billing, tickCost, unitType, maxPrice } = normalized;
     if (this.#s.authMode === "unprotected") {
       throw new Error(
-        `route '${this.#s.key}': Cannot combine .unprotected() and .paid() on the same route.`
+        `route '${this.#s.key}': Cannot combine .unprotected() and .${method}() on the same route.`
       );
     }
     if (this.#s.pricing !== void 0) {
       throw new Error(
-        `route '${this.#s.key}': Cannot call .paid() more than once on the same route.`
+        `route '${this.#s.key}': Cannot combine .paid(), .upTo(), and .metered() \u2014 pick one pricing mode.`
       );
     }
     const next = this.fork();
     next.#s.authMode = "paid";
     next.#s.pricing = pricing;
-    if (resolvedOptions?.protocols) {
+    if (billing === "upto") {
+      if (resolvedOptions.protocols?.some((p) => p !== "x402")) {
+        throw new Error(
+          `route '${this.#s.key}': .upTo() is x402-only \u2014 remove the conflicting protocols override.`
+        );
+      }
+      next.#s.protocols = ["x402"];
+    } else if (billing === "metered") {
+      if (resolvedOptions.protocols?.some((p) => p !== "mpp")) {
+        throw new Error(
+          `route '${this.#s.key}': .metered() is MPP-only \u2014 remove the conflicting protocols override.`
+        );
+      }
+      next.#s.protocols = ["mpp"];
+    } else if (resolvedOptions.protocols) {
       next.#s.protocols = [...resolvedOptions.protocols];
     } else if (next.#s.protocols.length === 0) {
       next.#s.protocols = ["x402"];
     }
-    if (resolvedOptions?.maxPrice) next.#s.maxPrice = resolvedOptions.maxPrice;
-    if (resolvedOptions?.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
-    if (resolvedOptions?.payTo) next.#s.payTo = resolvedOptions.payTo;
-    if (resolvedOptions?.mpp) next.#s.mppInfo = resolvedOptions.mpp;
-    if (resolvedOptions?.dynamic) next.#s.dynamicPrice = true;
-    if (resolvedOptions?.tickCost) next.#s.tickCost = resolvedOptions.tickCost;
-    if (resolvedOptions?.unitType) next.#s.unitType = resolvedOptions.unitType;
+    if (resolvedOptions.maxPrice) next.#s.maxPrice = resolvedOptions.maxPrice;
+    if (maxPrice) next.#s.maxPrice = maxPrice;
+    if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
+    if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
+    if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    next.#s.billing = billing;
+    if (tickCost) next.#s.tickCost = tickCost;
+    if (unitType) next.#s.unitType = unitType;
     if (typeof pricing === "object" && "tiers" in pricing) {
-      if (next.#s.dynamicPrice) {
-        throw new Error(
-          `route '${this.#s.key}': .paid({ dynamic: true }) is incompatible with tiered pricing`
-        );
-      }
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
           throw new Error(`route '${this.#s.key}': tier key cannot be empty`);
@@ -3359,21 +3520,25 @@ var RouteBuilder = class _RouteBuilder {
         }
       }
     }
-    if (resolvedOptions?.maxPrice !== void 0 && !isPositiveDecimal(resolvedOptions.maxPrice)) {
+    if (billing === "exact" && typeof pricing === "string" && !isPositiveDecimal(pricing)) {
       throw new Error(
-        `route '${this.#s.key}': maxPrice '${resolvedOptions.maxPrice}' must be a positive decimal string`
+        `route '${this.#s.key}': price '${pricing}' must be a positive decimal string`
       );
     }
-    if (resolvedOptions?.tickCost !== void 0 && !isPositiveDecimal(resolvedOptions.tickCost)) {
+    if (next.#s.maxPrice !== void 0 && !isPositiveDecimal(next.#s.maxPrice)) {
       throw new Error(
-        `route '${this.#s.key}': tickCost '${resolvedOptions.tickCost}' must be a positive decimal string`
+        `route '${this.#s.key}': maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
       );
     }
-    if (next.#s.dynamicPrice && !next.#s.maxPrice) {
-      throw new Error(`route '${this.#s.key}': .paid({ dynamic: true }) requires maxPrice`);
+    if (next.#s.minPrice !== void 0 && !isPositiveDecimal(next.#s.minPrice)) {
+      throw new Error(
+        `route '${this.#s.key}': minPrice '${next.#s.minPrice}' must be a positive decimal string`
+      );
     }
-    if (next.#s.dynamicPrice && !next.#s.tickCost) {
-      throw new Error(`route '${this.#s.key}': .paid({ dynamic: true }) requires tickCost`);
+    if (next.#s.tickCost !== void 0 && !isPositiveDecimal(next.#s.tickCost)) {
+      throw new Error(
+        `route '${this.#s.key}': tickCost '${next.#s.tickCost}' must be a positive decimal string`
+      );
     }
     return next;
   }
@@ -3656,13 +3821,13 @@ var RouteBuilder = class _RouteBuilder {
   /**
    * Register a streaming handler (`async function*`) and return the Next.js
    * route function. Each `charge()` call bills one tick (`tickCost` USDC) up
-   * to `maxPrice`; requires `.paid({ dynamic: true, ... })` and MPP session mode.
+   * to `maxPrice`; requires `.metered({ ... })` and MPP session mode.
    *
    * @example
    * ```ts
    * export const POST = router
    *   .route('llm/stream')
-   *   .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05' })
+   *   .metered({ tickCost: '0.0001', maxPrice: '0.05', unitType: 'token' })
    *   .body(schema)
    *   .stream(async function* ({ body, charge }) {
    *     for await (const token of streamLLM(body.prompt)) {
@@ -3678,7 +3843,7 @@ var RouteBuilder = class _RouteBuilder {
   register(handlerFn, streaming) {
     if (!this.#s.authMode) {
       throw new Error(
-        `route '${this.#s.key}': Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()`
+        `route '${this.#s.key}': Select an auth mode: .paid(pricing), .upTo(maxPrice), .metered(options), .siwx(), .apiKey(resolver), or .unprotected()`
       );
     }
     if (this.#s.validateFn && !this.#s.bodySchema) {
@@ -3689,24 +3854,34 @@ var RouteBuilder = class _RouteBuilder {
     if (this.#s.settlement && !this.#s.pricing) {
       throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
     }
-    if (this.#s.dynamicPrice && this.#s.protocols.includes("x402")) {
+    if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {
         throw new Error(
-          `route '${this.#s.key}': .paid({ dynamic: true }) on an x402 route requires an 'upto' accept on at least one configured network. Add { scheme: 'upto', network, asset } to RouterConfig.x402.accepts.`
+          `route '${this.#s.key}': .upTo() requires an 'upto' accept on at least one configured network. Add { scheme: 'upto', network, asset } to RouterConfig.x402.accepts.`
         );
       }
     }
-    if (this.#s.dynamicPrice && this.#s.protocols.includes("mpp")) {
+    if (this.#s.pricing !== void 0 && this.#s.billing === "exact" && this.#s.protocols.includes("x402")) {
+      const hasExact = this.#s.deps.x402Accepts.some(
+        (accept) => (accept.scheme ?? "exact") !== "upto"
+      );
+      if (!hasExact) {
+        throw new Error(
+          `route '${this.#s.key}': .paid() needs a non-'upto' x402 accept \u2014 an 'upto'-only accept list cannot serve a fixed-price route. Add { scheme: 'exact', network } to RouterConfig.x402.accepts, or use .upTo() for handler-computed billing.`
+        );
+      }
+    }
+    if (this.#s.billing === "metered") {
       if (!this.#s.deps.mppSessionConfig) {
         throw new Error(
-          `route '${this.#s.key}': .paid({ dynamic: true }) on an MPP route requires session mode. Set RouterConfig.mpp.session = {} and provide mpp.operatorKey.`
+          `route '${this.#s.key}': .metered() requires MPP session mode. Set RouterConfig.mpp.session = {} and provide mpp.operatorKey.`
         );
       }
     }
-    if (streaming && !this.#s.dynamicPrice) {
+    if (streaming && this.#s.billing !== "metered") {
       throw new Error(
-        `route '${this.#s.key}': .stream() requires .paid({ dynamic: true }) \u2014 static/free routes can't meter per-chunk billing.`
+        `route '${this.#s.key}': .stream() requires .metered() \u2014 static/free/upto routes can't meter per-chunk billing.`
       );
     }
     validateExamples(
@@ -3724,7 +3899,7 @@ var RouteBuilder = class _RouteBuilder {
       authMode: this.#s.authMode,
       siwxEnabled: this.#s.siwxEnabled,
       pricing: this.#s.pricing,
-      dynamicPrice: this.#s.dynamicPrice ? true : void 0,
+      billing: this.#s.billing,
       streaming: streaming ? true : void 0,
       protocols: this.#s.protocols,
       bodySchema: this.#s.bodySchema,
@@ -3751,20 +3926,63 @@ var RouteBuilder = class _RouteBuilder {
     return createRequestHandler(entry, handlerFn, this.#s.deps);
   }
 };
-function resolvePaidArgs(routeKey, pricingOrOptions, options) {
-  const isHandlerDynamicShape = typeof pricingOrOptions === "object" && pricingOrOptions !== null && typeof pricingOrOptions !== "function" && !("tiers" in pricingOrOptions) && "dynamic" in pricingOrOptions && pricingOrOptions.dynamic;
-  if (isHandlerDynamicShape) {
-    const opts = pricingOrOptions;
-    if (!opts.maxPrice) {
-      throw new Error(`route '${routeKey}': .paid({ dynamic: true }) requires maxPrice`);
-    }
-    return { pricing: opts.maxPrice, resolvedOptions: opts };
+function normalizePaidArg(routeKey, arg, options) {
+  if (typeof arg === "string") {
+    return { pricing: arg, resolvedOptions: options ?? {}, billing: "exact" };
   }
-  return { pricing: pricingOrOptions, resolvedOptions: options };
+  if (typeof arg === "function") {
+    return {
+      pricing: arg,
+      resolvedOptions: options ?? {},
+      billing: "exact"
+    };
+  }
+  if ("tiers" in arg && "field" in arg) {
+    return {
+      pricing: { field: arg.field, tiers: arg.tiers, default: arg.default },
+      resolvedOptions: arg,
+      billing: "exact"
+    };
+  }
+  if ("price" in arg && typeof arg.price === "string") {
+    return { pricing: arg.price, resolvedOptions: arg, billing: "exact" };
+  }
+  throw new Error(
+    `route '${routeKey}': .paid() requires one of: a price string, a (body) => string function, { price }, or { field, tiers }. For handler-computed billing use .upTo(); for per-tick billing use .metered().`
+  );
+}
+function normalizeUpToArg(routeKey, arg) {
+  const options = typeof arg === "string" ? { maxPrice: arg } : arg;
+  if (!options.maxPrice) {
+    throw new Error(`route '${routeKey}': .upTo() requires maxPrice`);
+  }
+  return {
+    pricing: options.maxPrice,
+    resolvedOptions: options,
+    billing: "upto",
+    unitType: options.unitType,
+    maxPrice: options.maxPrice
+  };
+}
+function normalizeMeteredArg(routeKey, options) {
+  if (!options.maxPrice) {
+    throw new Error(`route '${routeKey}': .metered() requires maxPrice`);
+  }
+  if (!options.tickCost) {
+    throw new Error(`route '${routeKey}': .metered() requires tickCost`);
+  }
+  return {
+    pricing: options.maxPrice,
+    resolvedOptions: options,
+    billing: "metered",
+    tickCost: options.tickCost,
+    unitType: options.unitType,
+    maxPrice: options.maxPrice
+  };
 }
 
 // src/discovery/well-known.ts
-import { NextResponse as NextResponse8 } from "next/server";
+import { NextResponse as NextResponse9 } from "next/server";
 
 // src/discovery/utils/guidance.ts
 async function resolveGuidance(discovery) {
@@ -3808,7 +4026,7 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, discovery) {
     if (instructions) {
       body.instructions = instructions;
     }
-    return NextResponse8.json(body, {
+    return NextResponse9.json(body, {
       headers: {
         "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET",
@@ -3826,13 +4044,13 @@ function toDiscoveryResource(method, url, mode) {
 
 // src/discovery/openapi.ts
 init_constants();
-import { NextResponse as NextResponse9 } from "next/server";
+import { NextResponse as NextResponse10 } from "next/server";
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
   let validated = false;
   return async (_request) => {
-    if (cached) return NextResponse9.json(cached);
+    if (cached) return NextResponse10.json(cached);
     if (!validated && pricesKeys) {
       registry.validate(pricesKeys);
       validated = true;
@@ -3895,7 +4113,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
       paths
     };
     cached = createDocument(openApiDocument);
-    return NextResponse9.json(cached);
+    return NextResponse10.json(cached);
   };
 }
 function deriveTag(routeKey) {
@@ -4031,11 +4249,11 @@ function tierExtrema(prices) {
 }
 
 // src/discovery/llms-txt.ts
-import { NextResponse as NextResponse10 } from "next/server";
+import { NextResponse as NextResponse11 } from "next/server";
 function createLlmsTxtHandler(discovery) {
   return async (_request) => {
     const guidance = await resolveGuidance(discovery) ?? "";
-    return new NextResponse10(guidance, {
+    return new NextResponse11(guidance, {
       headers: {
         "Content-Type": "text/plain; charset=utf-8",
         "Access-Control-Allow-Origin": "*"
@@ -4085,10 +4303,14 @@ var isPlaceholderEvm = (v) => ZERO_EVM_ADDRESS_RE.test(v);
 var isSolanaAddress = (v) => SOLANA_ADDRESS_RE.test(v);
 var isX402Network = (v) => v.startsWith("eip155:") || v.startsWith("solana:");
 var canonicalizeEvm = (addr) => addr.toLowerCase();
+function evmAddressFromKey(key) {
+  if (!key || !isEvmPrivateKey(key)) return null;
+  return privateKeyToAccount(key).address.toLowerCase();
+}
 function operatorAddressesCollide(opKey, fpKey) {
-  if (!opKey || !fpKey || !isEvmPrivateKey(opKey) || !isEvmPrivateKey(fpKey)) return null;
-  const op = privateKeyToAccount(opKey).address.toLowerCase();
-  const fp = privateKeyToAccount(fpKey).address.toLowerCase();
+  const op = evmAddressFromKey(opKey);
+  const fp = evmAddressFromKey(fpKey);
+  if (!op || !fp) return null;
   return op === fp ? op : null;
 }
 function trimAll(raw) {
@@ -4250,7 +4472,7 @@ function getConfiguredX402Accepts2(config) {
     }
   ];
 }
-function validateX402Config(config, env, options) {
+function validateX402Config(config, env) {
   const accepts = getConfiguredX402Accepts2(config);
   const issues = [];
   const push = (code, message) => issues.push({ code, protocol: "x402", message });
@@ -4292,23 +4514,21 @@ function validateX402Config(config, env, options) {
       `x402 payee '${placeholder}' is a placeholder address and cannot receive payments.`
     );
   }
-  if (options.requireCdpKeys !== false) {
-    const hasEvm = accepts.some(
-      (a) => typeof a.network === "string" && a.network.startsWith("eip155:")
-    );
-    if (hasEvm) {
-      const missing = ["CDP_API_KEY_ID", "CDP_API_KEY_SECRET"].filter((k) => !env[k]);
-      if (missing.length > 0) {
-        push(
-          "missing_cdp_keys",
-          `x402 EVM facilitator (Coinbase) requires ${missing.join(" and ")}.`
-        );
-      }
+  const hasEvm = accepts.some(
+    (a) => typeof a.network === "string" && a.network.startsWith("eip155:")
+  );
+  if (hasEvm) {
+    const missing = ["CDP_API_KEY_ID", "CDP_API_KEY_SECRET"].filter((k) => !env[k]);
+    if (missing.length > 0) {
+      push(
+        "missing_cdp_keys",
+        `x402 EVM facilitator (Coinbase) requires ${missing.join(" and ")}. Create an API key at https://portal.cdp.coinbase.com and set it via env.`
+      );
     }
   }
   return issues;
 }
-function validateMppConfig(config) {
+function validateMppConfig(config, env) {
   const m = config.mpp;
   if (!m) {
     return [
@@ -4356,7 +4576,7 @@ function validateMppConfig(config) {
       `MPP recipient '${placeholder}' is a placeholder address and cannot receive payments.`
     );
   }
-  if (!m.rpcUrl) {
+  if (!m.rpcUrl && !env.TEMPO_RPC_URL) {
     push(
       "missing_mpp_rpc_url",
       "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object."
@@ -4381,6 +4601,15 @@ function validateMppConfig(config) {
       `MPP operatorKey and feePayerKey resolve to the same address (${collision}). Tempo rejects fee-delegated txs with sender === feePayer, so channel close/settle would fail at runtime. Either use two distinct wallets, or omit feePayerKey to disable gas sponsorship (clients then pay their own gas).`
     );
   }
+  if (m.session && recipient && isEvmAddress(recipient)) {
+    const operatorAddress = evmAddressFromKey(m.operatorKey);
+    if (operatorAddress && operatorAddress !== recipient.toLowerCase()) {
+      push(
+        "mpp_operator_recipient_mismatch",
+        `MPP session operatorKey resolves to ${operatorAddress}, which must equal the recipient/payee ${recipient.toLowerCase()}. mppx's channel-close handler asserts sender === payee. Set mpp.operatorKey to the recipient\u2019s private key, or set mpp.recipient/payeeAddress to the operator address.`
+      );
+    }
+  }
   return issues;
 }
 function translateZodIssues(error) {
@@ -4509,8 +4738,8 @@ function getRouterConfigIssues(config, options = {}) {
       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));
+  if (protocols.includes("x402")) issues.push(...validateX402Config(config, env));
+  if (protocols.includes("mpp")) issues.push(...validateMppConfig(config, env));
   return issues;
 }
 
@@ -4595,9 +4824,6 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     const getClient = async () => tempoClient;
     const operatorAccount = config.mpp.operatorKey ? privateKeyToAccount2(config.mpp.operatorKey) : void 0;
     const feePayerAccount = config.mpp.feePayerKey ? privateKeyToAccount2(config.mpp.feePayerKey) : void 0;
-    if (config.mpp.session && operatorAccount) {
-      assertOperatorMatchesRecipient(config, operatorAccount.address);
-    }
     const resolvedStore = kvStore ? await createKvMppStore(kvStore) : void 0;
     const realm = new URL(resolvedBaseUrl).host;
     const mppConfig = config.mpp;
@@ -4635,15 +4861,6 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     return { initError: err instanceof Error ? err.message : String(err) };
   }
 }
-function assertOperatorMatchesRecipient(config, operatorAddress) {
-  const recipient = (config.mpp?.recipient ?? config.payeeAddress)?.toLowerCase();
-  const opAddr = operatorAddress.toLowerCase();
-  if (recipient && opAddr !== recipient) {
-    throw new Error(
-      `MPP session config mismatch: operator address ${operatorAddress} must equal recipient/payee ${recipient}. mppx's channel-close handler asserts sender === payee. Set mpp.operatorKey to the private key for ${recipient}, or set mpp.recipient/payeeAddress to ${operatorAddress}.`
-    );
-  }
-}
 
 // src/index.ts
 init_constants();
@@ -4654,10 +4871,7 @@ function createRouter(config) {
   const entitlementStore = kvStore ? createKvEntitlementStore(kvStore) : new MemoryEntitlementStore();
   const network = config.network ?? BASE_MAINNET_NETWORK;
   const x402Accepts = getConfiguredX402Accepts(config);
-  const configIssues = getRouterConfigIssues(config, {
-    env: process.env,
-    requireCdpKeys: process.env.NODE_ENV === "production"
-  });
+  const configIssues = getRouterConfigIssues(config, { env: process.env });
   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");
@@ -4670,10 +4884,7 @@ function createRouter(config) {
   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 RouterConfigError(protocolConfigIssues);
-    }
+    throw new RouterConfigError(protocolConfigIssues);
   }
   const resolvedBaseUrl = config.baseUrl.replace(/\/+$/, "");
   if (config.plugin?.init) {
@@ -4699,7 +4910,7 @@ function createRouter(config) {
     x402Accepts,
     mppx: null,
     tempoClient: null,
-    mppSessionConfig: config.mpp?.session ? { depositMultiplier: config.mpp.session.depositMultiplier ?? 10 } : null
+    mppSessionConfig: config.mpp?.session && config.mpp.operatorKey ? { depositMultiplier: config.mpp.session.depositMultiplier ?? 10 } : null
   };
   deps.initPromise = (async () => {
     const x402Result = await initX402(config, kvStore, x402ConfigError);