@agentcash/router 1.7.1 → 1.8.0

package/README.md

@@ -141,6 +141,8 @@ export const GET = router.openapi();
 
 The barrel forces every route module to load before the discovery handler walks the registry — Next.js otherwise lazy-loads route files on first hit, and unloaded routes don't appear in the spec.
 
+The `openapi.json` should be hosted at `GET <origin>/openapi.json`. 
+
 ## Auth modes
 
 | Method | Purpose |

package/dist/index.cjs

@@ -67,6 +67,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) => ({
@@ -362,9 +365,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") {
@@ -795,10 +807,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;
@@ -1231,6 +1240,7 @@ var DynamicPricing = class {
       const raw = await this.opts.fn(body);
       return 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
@@ -1753,7 +1763,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);
     }
@@ -1804,7 +1814,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;
@@ -2061,7 +2071,7 @@ function tagBareDecimalAsDollars(amount) {
 }
 
 // src/protocols/x402/verify.ts
-var import_types2 = require("@x402/core/types");
+var import_types3 = require("@x402/core/types");
 async function verifyX402Payment(opts) {
   const { server, request, price, accepts, report } = opts;
   const payload = await readPaymentPayload(request);
@@ -2080,7 +2090,7 @@ async function verifyX402Payment(opts) {
   try {
     verify = await server.verifyPayment(payload, matching);
   } catch (err) {
-    if (err instanceof import_types2.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
+    if (err instanceof import_types3.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
       return invalidPaymentVerification({
         reason: err.invalidReason ?? "verify_error",
         ...err.invalidMessage ? { message: err.invalidMessage } : {},
@@ -2181,7 +2191,7 @@ async function verifyX402(args) {
   const accepts = await resolveX402Accepts(
     request,
     routeEntry,
-    deps.x402Accepts,
+    selectRouteAccepts(deps.x402Accepts, routeEntry),
     deps.payeeAddress,
     body
   );
@@ -2229,7 +2239,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) {
@@ -2259,7 +2269,7 @@ async function buildX402ChallengeContribution(args) {
   const accepts = await resolveX402Accepts(
     request,
     routeEntry,
-    deps.x402Accepts,
+    selectRouteAccepts(deps.x402Accepts, routeEntry),
     deps.payeeAddress,
     body
   );
@@ -2352,9 +2362,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");
@@ -2521,10 +2529,7 @@ async function runDynamicChannelMgmtFlow(args) {
   });
 }
 
-// src/pipeline/flows/dynamic/dynamic-invoke.ts
-var import_server6 = require("next/server");
-
-// src/pricing/charge-context.ts
+// src/pricing/metered-charge.ts
 function createChargeContext(args) {
   const { tickCost, maxPrice, route } = args;
   const tickAtomic = decimalToAtomic(tickCost);
@@ -2559,15 +2564,10 @@ 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
+var import_server6 = require("next/server");
+function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
+  return {
     body,
     query: parseQuery(ctx.request, ctx.routeEntry),
     request: ctx.request,
@@ -2579,12 +2579,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 : import_server6.NextResponse.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: import_server6.NextResponse.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) {
@@ -2592,41 +2621,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 : import_server6.NextResponse.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: import_server6.NextResponse.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
@@ -2656,7 +2724,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,
@@ -2674,6 +2742,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) {
@@ -2746,13 +2827,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({
@@ -2774,6 +2849,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) {
@@ -2921,13 +3008,8 @@ 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
@@ -3325,7 +3407,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,
@@ -3356,39 +3438,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`);
@@ -3400,22 +3527,16 @@ var RouteBuilder = class _RouteBuilder {
         }
       }
     }
-    if (resolvedOptions?.maxPrice !== void 0 && !isPositiveDecimal(resolvedOptions.maxPrice)) {
+    if (next.#s.maxPrice !== void 0 && !isPositiveDecimal(next.#s.maxPrice)) {
       throw new Error(
-        `route '${this.#s.key}': maxPrice '${resolvedOptions.maxPrice}' must be a positive decimal string`
+        `route '${this.#s.key}': maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
       );
     }
-    if (resolvedOptions?.tickCost !== void 0 && !isPositiveDecimal(resolvedOptions.tickCost)) {
+    if (next.#s.tickCost !== void 0 && !isPositiveDecimal(next.#s.tickCost)) {
       throw new Error(
-        `route '${this.#s.key}': tickCost '${resolvedOptions.tickCost}' must be a positive decimal string`
+        `route '${this.#s.key}': tickCost '${next.#s.tickCost}' 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.dynamicPrice && !next.#s.tickCost) {
-      throw new Error(`route '${this.#s.key}': .paid({ dynamic: true }) requires tickCost`);
-    }
     return next;
   }
   /**
@@ -3697,13 +3818,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)) {
@@ -3719,7 +3840,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) {
@@ -3730,24 +3851,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.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.dynamicPrice && this.#s.protocols.includes("mpp")) {
+    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(
@@ -3765,7 +3896,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,
@@ -3792,16 +3923,59 @@ 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" };
+  }
+  if (typeof arg === "function") {
+    return {
+      pricing: arg,
+      resolvedOptions: options ?? {},
+      billing: "exact"
+    };
   }
-  return { pricing: pricingOrOptions, resolvedOptions: options };
+  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
@@ -4740,7 +4914,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);