@agentcash/router 1.9.3 → 1.10.0

package/README.md

@@ -119,6 +119,7 @@ export const POST = router.route({ path: 'search' })
 // app/api/inbox/status/route.ts
 export const GET = router.route({ path: 'inbox/status' })
   .siwx()
+  .method('GET')
   .handler(async ({ wallet }) => getStatus(wallet));
 ```
 
@@ -163,6 +164,20 @@ router.route({ path: 'gated' })
   .handler(fn);
 ```
 
+### `.siwx()` on paid routes. Pay once, identity-gated replays
+
+`.paid()` and `.upTo()` compose with `.siwx()` for a pay-once-then-replay-for-free model. The first request settles normally (x402 payment); on success the wallet is recorded in the entitlement KV. Subsequent requests that present a valid SIWX signature for that wallet skip payment and run the handler directly. On `.upTo()` routes, `charge(amount)` becomes a no-op on the SIWX replay path. The handler can continue to call the route unconditionally.
+
+```typescript
+router.route({ path: 'inbox' })
+  .paid('0.01').siwx()  // first call pays $0.01, later calls present a SIWX sig instead
+  .handler(async ({ wallet }) => getInbox(wallet));
+```
+
+`.metered()` is mutually exclusive with `.siwx()` — per-tick MPP billing has no entitlement model — and the builder throws at registration if you combine them.
+
+> **Gotcha:** serverless / multi-instance deployments must provide a real `kvStore` (Upstash / Vercel KV). Without one the entitlement is kept in a per-process `Map`, so a wallet that paid on instance A is treated as unpaid on instance B and the user gets charged again.
+
 ## Pricing
 
 `.paid()`, `.upTo()`, and `.metered()` are mutually exclusive pricing modes: pick one per route.

package/dist/index.cjs

@@ -808,7 +808,11 @@ function invokePaidStatic(ctx, wallet, account, body, payment) {
   return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment));
 }
 function invokeUnauthed(ctx, wallet, account, body) {
-  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, null));
+  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+  if (ctx.routeEntry.billing !== "upto") return runHandler(ctx, base);
+  const uptoCtx = { ...base, charge: async () => {
+  } };
+  return runHandler(ctx, uptoCtx);
 }
 function buildHandlerCtx(ctx, wallet, account, body, payment) {
   return {
@@ -1137,7 +1141,7 @@ async function resolveEarlyBody(args) {
   }
   const earlyClone = ctx.request.clone();
   const earlyResult = await parseBody(ctx, earlyClone);
-  if (!earlyResult.ok) return { ok: false, response: earlyResult.response };
+  if (!earlyResult.ok) return { ok: true, earlyBody: void 0 };
   const validateErr = await runValidate(ctx, earlyResult.data);
   if (validateErr) return { ok: false, response: validateErr };
   return { ok: true, earlyBody: earlyResult.data };
@@ -1189,17 +1193,6 @@ function protocolInitError(routeEntry, deps) {
   return `Payment protocol initialization failed. ${errors.join("; ")}`;
 }
 
-// src/pipeline/flows/api-key-only.ts
-async function runApiKeyOnlyFlow(ctx) {
-  if (!ctx.routeEntry.apiKeyResolver) {
-    return fail(ctx, 401, "API key resolver not configured");
-  }
-  const result = await verifyApiKey(ctx.request, ctx.routeEntry.apiKeyResolver);
-  if (!result.valid) return fail(ctx, 401, "Invalid or missing API key");
-  fireAuthVerified(ctx, { authMode: "apiKey", wallet: null, account: result.account });
-  return runHandlerOnly(ctx, null, result.account);
-}
-
 // src/pricing/format.ts
 var USDC_DECIMALS = 6;
 var DECIMAL_RE = /^(\d+)(?:\.(\d+))?$/;
@@ -1255,169 +1248,6 @@ function multiplyDecimal(decimal, factor) {
   return fracPart ? `${intPart}.${fracPart}` : intPart;
 }
 
-// src/pricing/dynamic.ts
-var DynamicPricing = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  needsBody = true;
-  async quote(body) {
-    let priced;
-    try {
-      const raw = await this.opts.fn(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
-      });
-      if (this.opts.maxPrice) {
-        this.alert("warn", `Using maxPrice ${this.opts.maxPrice} as fallback after pricing error`);
-        return this.opts.maxPrice;
-      }
-      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");
-    return this.quote(body);
-  }
-  describe() {
-    return {
-      mode: "dynamic",
-      min: this.opts.minPrice ?? "0",
-      max: this.opts.maxPrice ?? "0"
-    };
-  }
-  cap(raw, body) {
-    if (!this.opts.maxPrice) return raw;
-    let overCap;
-    try {
-      overCap = compareDecimals(raw, this.opts.maxPrice) > 0;
-    } catch {
-      overCap = true;
-    }
-    if (overCap) {
-      this.alert("warn", `Price ${raw} exceeds maxPrice ${this.opts.maxPrice}, capping`, {
-        calculated: raw,
-        maxPrice: this.opts.maxPrice,
-        body
-      });
-      return this.opts.maxPrice;
-    }
-    return raw;
-  }
-  alert(level, message, meta) {
-    this.opts.alert?.(level, message, meta);
-  }
-};
-function msg(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
-// src/pricing/fixed.ts
-var FixedPricing = class {
-  constructor(price) {
-    this.price = price;
-  }
-  needsBody = false;
-  quote() {
-    return Promise.resolve(this.price);
-  }
-  challengeQuote() {
-    return Promise.resolve(this.price);
-  }
-  describe() {
-    return { mode: "fixed", amount: this.price };
-  }
-};
-
-// src/pricing/tiered.ts
-var TieredPricing = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  needsBody = true;
-  async quote(body) {
-    const { field, tiers, default: defaultTier } = this.opts;
-    const tierKey = body != null ? String(body[field] ?? "") : "";
-    if (tierKey && tiers[tierKey]) return tiers[tierKey].price;
-    if (defaultTier && tiers[defaultTier]) return tiers[defaultTier].price;
-    if (!tierKey) {
-      throw httpError(400, `Missing required field '${field}' for tier pricing`);
-    }
-    throw httpError(
-      400,
-      `Unknown tier '${tierKey}' for field '${field}'. Valid tiers: ${Object.keys(tiers).join(", ")}`
-    );
-  }
-  async challengeQuote(body) {
-    if (body !== void 0) {
-      try {
-        return await this.quote(body);
-      } catch {
-      }
-    }
-    return this.maxTierPrice();
-  }
-  describe() {
-    return {
-      mode: "tiered",
-      tiers: Object.entries(this.opts.tiers).map(([key, tier]) => ({
-        key,
-        price: tier.price,
-        ...tier.label !== void 0 ? { label: tier.label } : {}
-      })),
-      ...this.opts.default !== void 0 ? { default: this.opts.default } : {}
-    };
-  }
-  maxTierPrice() {
-    let max = "0";
-    for (const tier of Object.values(this.opts.tiers)) {
-      if (compareDecimals(tier.price, max) > 0) max = tier.price;
-    }
-    return max;
-  }
-};
-function httpError(status, message) {
-  return Object.assign(new Error(message), { status });
-}
-
-// src/pricing/index.ts
-function selectPricing(raw, deps = {}) {
-  if (raw == null) return null;
-  if (typeof raw === "string") {
-    return new FixedPricing(raw);
-  }
-  if (typeof raw === "function") {
-    return new DynamicPricing({
-      fn: raw,
-      maxPrice: deps.maxPrice,
-      minPrice: deps.minPrice,
-      route: deps.route,
-      alert: deps.alert
-    });
-  }
-  if (typeof raw === "object" && "tiers" in raw) {
-    return new TieredPricing({
-      field: raw.field,
-      tiers: raw.tiers,
-      default: raw.default,
-      maxPrice: deps.maxPrice,
-      minPrice: deps.minPrice
-    });
-  }
-  throw new Error(`Unknown pricing config: ${JSON.stringify(raw)}`);
-}
-
 // src/protocols/mpp/credential.ts
 var import_mppx = require("mppx");
 var import_viem = require("viem");
@@ -2105,7 +1935,7 @@ function tagBareDecimalAsDollars(amount) {
 }
 
 // src/protocols/x402/verify.ts
-var import_types3 = require("@x402/core/types");
+var import_types2 = require("@x402/core/types");
 async function verifyX402Payment(opts) {
   const { server, request, price, accepts, report } = opts;
   const payload = await readPaymentPayload(request);
@@ -2124,7 +1954,7 @@ async function verifyX402Payment(opts) {
   try {
     verify = await server.verifyPayment(payload, matching);
   } catch (err) {
-    if (err instanceof import_types3.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
+    if (err instanceof import_types2.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
       return invalidPaymentVerification({
         reason: err.invalidReason ?? "verify_error",
         ...err.invalidMessage ? { message: err.invalidMessage } : {},
@@ -2347,6 +2177,199 @@ function getAllowedStrategies(allowed) {
   return allowed.map((name) => STRATEGIES[name]);
 }
 
+// src/protocols/detect.ts
+function detectProtocol(request) {
+  if (request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)) {
+    return "x402";
+  }
+  const auth = request.headers.get(HEADERS.AUTHORIZATION);
+  if (auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT)) {
+    return "mpp";
+  }
+  if (request.headers.get(HEADERS.SIWX)) {
+    return "siwx";
+  }
+  return null;
+}
+
+// src/pipeline/flows/api-key-only.ts
+async function runApiKeyOnlyFlow(ctx) {
+  if (!ctx.routeEntry.apiKeyResolver) {
+    return fail(ctx, 401, "API key resolver not configured");
+  }
+  const result = await verifyApiKey(ctx.request, ctx.routeEntry.apiKeyResolver);
+  if (!result.valid) return fail(ctx, 401, "Invalid or missing API key");
+  fireAuthVerified(ctx, { authMode: "apiKey", wallet: null, account: result.account });
+  return runHandlerOnly(ctx, null, result.account);
+}
+
+// src/pricing/dynamic.ts
+var DynamicPricing = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!isPositiveDecimal(opts.maxPrice)) {
+      throw new Error(
+        `route '${opts.route ?? "unknown"}': dynamic pricing requires a positive maxPrice, got '${opts.maxPrice}'`
+      );
+    }
+  }
+  needsBody = true;
+  async quote(body) {
+    let priced;
+    try {
+      const raw = await this.opts.fn(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
+      });
+      this.alert("warn", `Using maxPrice ${this.opts.maxPrice} as fallback after pricing error`);
+      return this.opts.maxPrice;
+    }
+    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);
+    return this.quote(body);
+  }
+  describe() {
+    return {
+      mode: "dynamic",
+      min: this.opts.minPrice ?? "0",
+      max: this.opts.maxPrice
+    };
+  }
+  cap(raw, body) {
+    let overCap;
+    try {
+      overCap = compareDecimals(raw, this.opts.maxPrice) > 0;
+    } catch {
+      overCap = true;
+    }
+    if (overCap) {
+      this.alert("warn", `Price ${raw} exceeds maxPrice ${this.opts.maxPrice}, capping`, {
+        calculated: raw,
+        maxPrice: this.opts.maxPrice,
+        body
+      });
+      return this.opts.maxPrice;
+    }
+    return raw;
+  }
+  alert(level, message, meta) {
+    this.opts.alert?.(level, message, meta);
+  }
+};
+function msg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/pricing/fixed.ts
+var FixedPricing = class {
+  constructor(price) {
+    this.price = price;
+  }
+  needsBody = false;
+  quote() {
+    return Promise.resolve(this.price);
+  }
+  challengeQuote() {
+    return Promise.resolve(this.price);
+  }
+  describe() {
+    return { mode: "fixed", amount: this.price };
+  }
+};
+
+// src/pricing/tiered.ts
+var TieredPricing = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  needsBody = true;
+  async quote(body) {
+    const { field, tiers, default: defaultTier } = this.opts;
+    const tierKey = body != null ? String(body[field] ?? "") : "";
+    if (tierKey && tiers[tierKey]) return tiers[tierKey].price;
+    if (defaultTier && tiers[defaultTier]) return tiers[defaultTier].price;
+    if (!tierKey) {
+      throw httpError(400, `Missing required field '${field}' for tier pricing`);
+    }
+    throw httpError(
+      400,
+      `Unknown tier '${tierKey}' for field '${field}'. Valid tiers: ${Object.keys(tiers).join(", ")}`
+    );
+  }
+  async challengeQuote(body) {
+    if (body !== void 0) {
+      try {
+        return await this.quote(body);
+      } catch {
+      }
+    }
+    return this.maxTierPrice();
+  }
+  describe() {
+    return {
+      mode: "tiered",
+      tiers: Object.entries(this.opts.tiers).map(([key, tier]) => ({
+        key,
+        price: tier.price,
+        ...tier.label !== void 0 ? { label: tier.label } : {}
+      })),
+      ...this.opts.default !== void 0 ? { default: this.opts.default } : {}
+    };
+  }
+  maxTierPrice() {
+    let max = "0";
+    for (const tier of Object.values(this.opts.tiers)) {
+      if (compareDecimals(tier.price, max) > 0) max = tier.price;
+    }
+    return max;
+  }
+};
+function httpError(status, message) {
+  return Object.assign(new Error(message), { status });
+}
+
+// src/pricing/index.ts
+function selectPricing(raw, deps = {}) {
+  if (raw == null) return null;
+  if (typeof raw === "string") {
+    return new FixedPricing(raw);
+  }
+  if (typeof raw === "function") {
+    if (!deps.maxPrice) {
+      throw new Error(`route '${deps.route ?? "unknown"}': dynamic pricing requires maxPrice`);
+    }
+    return new DynamicPricing({
+      fn: raw,
+      maxPrice: deps.maxPrice,
+      minPrice: deps.minPrice,
+      route: deps.route,
+      alert: deps.alert
+    });
+  }
+  if (typeof raw === "object" && "tiers" in raw) {
+    return new TieredPricing({
+      field: raw.field,
+      tiers: raw.tiers,
+      default: raw.default,
+      maxPrice: deps.maxPrice,
+      minPrice: deps.minPrice
+    });
+  }
+  throw new Error(`Unknown pricing config: ${JSON.stringify(raw)}`);
+}
+
 // src/pipeline/flows/challenge-response.ts
 var import_server5 = require("next/server");
 
@@ -3211,21 +3234,6 @@ async function createKvMppStore(kv, options) {
   });
 }
 
-// src/protocols/detect.ts
-function detectProtocol(request) {
-  if (request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)) {
-    return "x402";
-  }
-  const auth = request.headers.get(HEADERS.AUTHORIZATION);
-  if (auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT)) {
-    return "mpp";
-  }
-  if (request.headers.get(HEADERS.SIWX)) {
-    return "siwx";
-  }
-  return null;
-}
-
 // src/protocols/mpp/siwx-mode.ts
 var import_mppx3 = require("mppx");
 async function verifyMppSiwx(request, mppx) {
@@ -3248,8 +3256,6 @@ async function runSiwxOnlyFlow(ctx) {
     if (earlyBody.ok) {
       const validateErr = await runValidate(ctx, earlyBody.data);
       if (validateErr) return validateErr;
-    } else {
-      return earlyBody.response;
     }
   }
   const siwxHeader = request.headers.get(HEADERS.SIWX);
@@ -3381,13 +3387,24 @@ async function runUnprotectedFlow(ctx) {
 }
 
 // src/pipeline/orchestrate.ts
+function shouldSkipQueryValidation(routeEntry, request) {
+  if (routeEntry.pricing || routeEntry.authMode === "paid") {
+    return selectIncomingStrategy(request, routeEntry.protocols) === null;
+  }
+  if (routeEntry.authMode === "siwx") {
+    return !request.headers.get(HEADERS.SIWX) && detectProtocol(request) !== "mpp";
+  }
+  return false;
+}
 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 (!shouldSkipQueryValidation(routeEntry, 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);
@@ -3519,6 +3536,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': Cannot combine .paid(), .upTo(), and .metered() \u2014 pick one pricing mode.`
       );
     }
+    if (this.#s.siwxEnabled && billing === "metered") {
+      throw new Error(
+        `route '${this.#s.key}': Cannot combine .siwx() and .metered() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+      );
+    }
     const next = this.fork();
     next.#s.authMode = "paid";
     next.#s.pricing = pricing;
@@ -3566,6 +3588,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': price '${pricing}' must be a positive decimal string`
       );
     }
+    if (typeof pricing === "function" && next.#s.maxPrice === void 0) {
+      throw new Error(
+        `route '${this.#s.key}': dynamic pricing requires maxPrice \u2014 without it, bare probes would advertise a $0 challenge`
+      );
+    }
     if (next.#s.maxPrice !== void 0 && !isPositiveDecimal(next.#s.maxPrice)) {
       throw new Error(
         `route '${this.#s.key}': maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
@@ -3585,12 +3612,16 @@ var RouteBuilder = class _RouteBuilder {
   }
   /**
    * Require Sign-In-with-X wallet identity on this route — clients prove
-   * control of a wallet via a signed challenge. Combine with `.paid()` to gate
-   * a paid route on a verified wallet identity.
+   * control of a wallet via a signed challenge. Composes with `.paid()` and
+   * `.upTo()` for pay-once-then-replay: the first request settles normally,
+   * subsequent requests with a valid SIWX signature for the same wallet skip
+   * payment (on `.upTo()`, `charge(amount)` becomes a no-op on the replay).
+   * Mutually exclusive with `.metered()`.
    *
    * @example
    * ```ts
    * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
+   * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
    * ```
    */
   siwx() {
@@ -3604,6 +3635,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': Combining .siwx() and .apiKey() is not supported on the same route.`
       );
     }
+    if (this.#s.billing === "metered") {
+      throw new Error(
+        `route '${this.#s.key}': Cannot combine .metered() and .siwx() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+      );
+    }
     const next = this.fork();
     next.#s.siwxEnabled = true;
     if (next.#s.authMode === "paid" || next.#s.pricing) {

package/dist/index.d.cts

@@ -588,12 +588,16 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private applyPaid;
     /**
      * Require Sign-In-with-X wallet identity on this route — clients prove
-     * control of a wallet via a signed challenge. Combine with `.paid()` to gate
-     * a paid route on a verified wallet identity.
+     * control of a wallet via a signed challenge. Composes with `.paid()` and
+     * `.upTo()` for pay-once-then-replay: the first request settles normally,
+     * subsequent requests with a valid SIWX signature for the same wallet skip
+     * payment (on `.upTo()`, `charge(amount)` becomes a no-op on the replay).
+     * Mutually exclusive with `.metered()`.
      *
      * @example
      * ```ts
      * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
+     * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
      * ```
      */
     siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, Bill>;

package/dist/index.d.ts

@@ -588,12 +588,16 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private applyPaid;
     /**
      * Require Sign-In-with-X wallet identity on this route — clients prove
-     * control of a wallet via a signed challenge. Combine with `.paid()` to gate
-     * a paid route on a verified wallet identity.
+     * control of a wallet via a signed challenge. Composes with `.paid()` and
+     * `.upTo()` for pay-once-then-replay: the first request settles normally,
+     * subsequent requests with a valid SIWX signature for the same wallet skip
+     * payment (on `.upTo()`, `charge(amount)` becomes a no-op on the replay).
+     * Mutually exclusive with `.metered()`.
      *
      * @example
      * ```ts
      * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
+     * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
      * ```
      */
     siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, Bill>;

package/dist/index.js

@@ -767,7 +767,11 @@ function invokePaidStatic(ctx, wallet, account, body, payment) {
   return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment));
 }
 function invokeUnauthed(ctx, wallet, account, body) {
-  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, null));
+  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+  if (ctx.routeEntry.billing !== "upto") return runHandler(ctx, base);
+  const uptoCtx = { ...base, charge: async () => {
+  } };
+  return runHandler(ctx, uptoCtx);
 }
 function buildHandlerCtx(ctx, wallet, account, body, payment) {
   return {
@@ -1096,7 +1100,7 @@ async function resolveEarlyBody(args) {
   }
   const earlyClone = ctx.request.clone();
   const earlyResult = await parseBody(ctx, earlyClone);
-  if (!earlyResult.ok) return { ok: false, response: earlyResult.response };
+  if (!earlyResult.ok) return { ok: true, earlyBody: void 0 };
   const validateErr = await runValidate(ctx, earlyResult.data);
   if (validateErr) return { ok: false, response: validateErr };
   return { ok: true, earlyBody: earlyResult.data };
@@ -1148,17 +1152,6 @@ function protocolInitError(routeEntry, deps) {
   return `Payment protocol initialization failed. ${errors.join("; ")}`;
 }
 
-// src/pipeline/flows/api-key-only.ts
-async function runApiKeyOnlyFlow(ctx) {
-  if (!ctx.routeEntry.apiKeyResolver) {
-    return fail(ctx, 401, "API key resolver not configured");
-  }
-  const result = await verifyApiKey(ctx.request, ctx.routeEntry.apiKeyResolver);
-  if (!result.valid) return fail(ctx, 401, "Invalid or missing API key");
-  fireAuthVerified(ctx, { authMode: "apiKey", wallet: null, account: result.account });
-  return runHandlerOnly(ctx, null, result.account);
-}
-
 // src/pricing/format.ts
 var USDC_DECIMALS = 6;
 var DECIMAL_RE = /^(\d+)(?:\.(\d+))?$/;
@@ -1214,169 +1207,6 @@ function multiplyDecimal(decimal, factor) {
   return fracPart ? `${intPart}.${fracPart}` : intPart;
 }
 
-// src/pricing/dynamic.ts
-var DynamicPricing = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  needsBody = true;
-  async quote(body) {
-    let priced;
-    try {
-      const raw = await this.opts.fn(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
-      });
-      if (this.opts.maxPrice) {
-        this.alert("warn", `Using maxPrice ${this.opts.maxPrice} as fallback after pricing error`);
-        return this.opts.maxPrice;
-      }
-      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");
-    return this.quote(body);
-  }
-  describe() {
-    return {
-      mode: "dynamic",
-      min: this.opts.minPrice ?? "0",
-      max: this.opts.maxPrice ?? "0"
-    };
-  }
-  cap(raw, body) {
-    if (!this.opts.maxPrice) return raw;
-    let overCap;
-    try {
-      overCap = compareDecimals(raw, this.opts.maxPrice) > 0;
-    } catch {
-      overCap = true;
-    }
-    if (overCap) {
-      this.alert("warn", `Price ${raw} exceeds maxPrice ${this.opts.maxPrice}, capping`, {
-        calculated: raw,
-        maxPrice: this.opts.maxPrice,
-        body
-      });
-      return this.opts.maxPrice;
-    }
-    return raw;
-  }
-  alert(level, message, meta) {
-    this.opts.alert?.(level, message, meta);
-  }
-};
-function msg(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
-// src/pricing/fixed.ts
-var FixedPricing = class {
-  constructor(price) {
-    this.price = price;
-  }
-  needsBody = false;
-  quote() {
-    return Promise.resolve(this.price);
-  }
-  challengeQuote() {
-    return Promise.resolve(this.price);
-  }
-  describe() {
-    return { mode: "fixed", amount: this.price };
-  }
-};
-
-// src/pricing/tiered.ts
-var TieredPricing = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  needsBody = true;
-  async quote(body) {
-    const { field, tiers, default: defaultTier } = this.opts;
-    const tierKey = body != null ? String(body[field] ?? "") : "";
-    if (tierKey && tiers[tierKey]) return tiers[tierKey].price;
-    if (defaultTier && tiers[defaultTier]) return tiers[defaultTier].price;
-    if (!tierKey) {
-      throw httpError(400, `Missing required field '${field}' for tier pricing`);
-    }
-    throw httpError(
-      400,
-      `Unknown tier '${tierKey}' for field '${field}'. Valid tiers: ${Object.keys(tiers).join(", ")}`
-    );
-  }
-  async challengeQuote(body) {
-    if (body !== void 0) {
-      try {
-        return await this.quote(body);
-      } catch {
-      }
-    }
-    return this.maxTierPrice();
-  }
-  describe() {
-    return {
-      mode: "tiered",
-      tiers: Object.entries(this.opts.tiers).map(([key, tier]) => ({
-        key,
-        price: tier.price,
-        ...tier.label !== void 0 ? { label: tier.label } : {}
-      })),
-      ...this.opts.default !== void 0 ? { default: this.opts.default } : {}
-    };
-  }
-  maxTierPrice() {
-    let max = "0";
-    for (const tier of Object.values(this.opts.tiers)) {
-      if (compareDecimals(tier.price, max) > 0) max = tier.price;
-    }
-    return max;
-  }
-};
-function httpError(status, message) {
-  return Object.assign(new Error(message), { status });
-}
-
-// src/pricing/index.ts
-function selectPricing(raw, deps = {}) {
-  if (raw == null) return null;
-  if (typeof raw === "string") {
-    return new FixedPricing(raw);
-  }
-  if (typeof raw === "function") {
-    return new DynamicPricing({
-      fn: raw,
-      maxPrice: deps.maxPrice,
-      minPrice: deps.minPrice,
-      route: deps.route,
-      alert: deps.alert
-    });
-  }
-  if (typeof raw === "object" && "tiers" in raw) {
-    return new TieredPricing({
-      field: raw.field,
-      tiers: raw.tiers,
-      default: raw.default,
-      maxPrice: deps.maxPrice,
-      minPrice: deps.minPrice
-    });
-  }
-  throw new Error(`Unknown pricing config: ${JSON.stringify(raw)}`);
-}
-
 // src/protocols/mpp/credential.ts
 import { Credential } from "mppx";
 import { getAddress, isAddress } from "viem";
@@ -2306,6 +2136,199 @@ function getAllowedStrategies(allowed) {
   return allowed.map((name) => STRATEGIES[name]);
 }
 
+// src/protocols/detect.ts
+function detectProtocol(request) {
+  if (request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)) {
+    return "x402";
+  }
+  const auth = request.headers.get(HEADERS.AUTHORIZATION);
+  if (auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT)) {
+    return "mpp";
+  }
+  if (request.headers.get(HEADERS.SIWX)) {
+    return "siwx";
+  }
+  return null;
+}
+
+// src/pipeline/flows/api-key-only.ts
+async function runApiKeyOnlyFlow(ctx) {
+  if (!ctx.routeEntry.apiKeyResolver) {
+    return fail(ctx, 401, "API key resolver not configured");
+  }
+  const result = await verifyApiKey(ctx.request, ctx.routeEntry.apiKeyResolver);
+  if (!result.valid) return fail(ctx, 401, "Invalid or missing API key");
+  fireAuthVerified(ctx, { authMode: "apiKey", wallet: null, account: result.account });
+  return runHandlerOnly(ctx, null, result.account);
+}
+
+// src/pricing/dynamic.ts
+var DynamicPricing = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!isPositiveDecimal(opts.maxPrice)) {
+      throw new Error(
+        `route '${opts.route ?? "unknown"}': dynamic pricing requires a positive maxPrice, got '${opts.maxPrice}'`
+      );
+    }
+  }
+  needsBody = true;
+  async quote(body) {
+    let priced;
+    try {
+      const raw = await this.opts.fn(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
+      });
+      this.alert("warn", `Using maxPrice ${this.opts.maxPrice} as fallback after pricing error`);
+      return this.opts.maxPrice;
+    }
+    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);
+    return this.quote(body);
+  }
+  describe() {
+    return {
+      mode: "dynamic",
+      min: this.opts.minPrice ?? "0",
+      max: this.opts.maxPrice
+    };
+  }
+  cap(raw, body) {
+    let overCap;
+    try {
+      overCap = compareDecimals(raw, this.opts.maxPrice) > 0;
+    } catch {
+      overCap = true;
+    }
+    if (overCap) {
+      this.alert("warn", `Price ${raw} exceeds maxPrice ${this.opts.maxPrice}, capping`, {
+        calculated: raw,
+        maxPrice: this.opts.maxPrice,
+        body
+      });
+      return this.opts.maxPrice;
+    }
+    return raw;
+  }
+  alert(level, message, meta) {
+    this.opts.alert?.(level, message, meta);
+  }
+};
+function msg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/pricing/fixed.ts
+var FixedPricing = class {
+  constructor(price) {
+    this.price = price;
+  }
+  needsBody = false;
+  quote() {
+    return Promise.resolve(this.price);
+  }
+  challengeQuote() {
+    return Promise.resolve(this.price);
+  }
+  describe() {
+    return { mode: "fixed", amount: this.price };
+  }
+};
+
+// src/pricing/tiered.ts
+var TieredPricing = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  needsBody = true;
+  async quote(body) {
+    const { field, tiers, default: defaultTier } = this.opts;
+    const tierKey = body != null ? String(body[field] ?? "") : "";
+    if (tierKey && tiers[tierKey]) return tiers[tierKey].price;
+    if (defaultTier && tiers[defaultTier]) return tiers[defaultTier].price;
+    if (!tierKey) {
+      throw httpError(400, `Missing required field '${field}' for tier pricing`);
+    }
+    throw httpError(
+      400,
+      `Unknown tier '${tierKey}' for field '${field}'. Valid tiers: ${Object.keys(tiers).join(", ")}`
+    );
+  }
+  async challengeQuote(body) {
+    if (body !== void 0) {
+      try {
+        return await this.quote(body);
+      } catch {
+      }
+    }
+    return this.maxTierPrice();
+  }
+  describe() {
+    return {
+      mode: "tiered",
+      tiers: Object.entries(this.opts.tiers).map(([key, tier]) => ({
+        key,
+        price: tier.price,
+        ...tier.label !== void 0 ? { label: tier.label } : {}
+      })),
+      ...this.opts.default !== void 0 ? { default: this.opts.default } : {}
+    };
+  }
+  maxTierPrice() {
+    let max = "0";
+    for (const tier of Object.values(this.opts.tiers)) {
+      if (compareDecimals(tier.price, max) > 0) max = tier.price;
+    }
+    return max;
+  }
+};
+function httpError(status, message) {
+  return Object.assign(new Error(message), { status });
+}
+
+// src/pricing/index.ts
+function selectPricing(raw, deps = {}) {
+  if (raw == null) return null;
+  if (typeof raw === "string") {
+    return new FixedPricing(raw);
+  }
+  if (typeof raw === "function") {
+    if (!deps.maxPrice) {
+      throw new Error(`route '${deps.route ?? "unknown"}': dynamic pricing requires maxPrice`);
+    }
+    return new DynamicPricing({
+      fn: raw,
+      maxPrice: deps.maxPrice,
+      minPrice: deps.minPrice,
+      route: deps.route,
+      alert: deps.alert
+    });
+  }
+  if (typeof raw === "object" && "tiers" in raw) {
+    return new TieredPricing({
+      field: raw.field,
+      tiers: raw.tiers,
+      default: raw.default,
+      maxPrice: deps.maxPrice,
+      minPrice: deps.minPrice
+    });
+  }
+  throw new Error(`Unknown pricing config: ${JSON.stringify(raw)}`);
+}
+
 // src/pipeline/flows/challenge-response.ts
 import { NextResponse as NextResponse5 } from "next/server";
 
@@ -3170,21 +3193,6 @@ async function createKvMppStore(kv, options) {
   });
 }
 
-// src/protocols/detect.ts
-function detectProtocol(request) {
-  if (request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)) {
-    return "x402";
-  }
-  const auth = request.headers.get(HEADERS.AUTHORIZATION);
-  if (auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT)) {
-    return "mpp";
-  }
-  if (request.headers.get(HEADERS.SIWX)) {
-    return "siwx";
-  }
-  return null;
-}
-
 // src/protocols/mpp/siwx-mode.ts
 import { Credential as Credential2 } from "mppx";
 async function verifyMppSiwx(request, mppx) {
@@ -3207,8 +3215,6 @@ async function runSiwxOnlyFlow(ctx) {
     if (earlyBody.ok) {
       const validateErr = await runValidate(ctx, earlyBody.data);
       if (validateErr) return validateErr;
-    } else {
-      return earlyBody.response;
     }
   }
   const siwxHeader = request.headers.get(HEADERS.SIWX);
@@ -3340,13 +3346,24 @@ async function runUnprotectedFlow(ctx) {
 }
 
 // src/pipeline/orchestrate.ts
+function shouldSkipQueryValidation(routeEntry, request) {
+  if (routeEntry.pricing || routeEntry.authMode === "paid") {
+    return selectIncomingStrategy(request, routeEntry.protocols) === null;
+  }
+  if (routeEntry.authMode === "siwx") {
+    return !request.headers.get(HEADERS.SIWX) && detectProtocol(request) !== "mpp";
+  }
+  return false;
+}
 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 (!shouldSkipQueryValidation(routeEntry, 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);
@@ -3478,6 +3495,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': Cannot combine .paid(), .upTo(), and .metered() \u2014 pick one pricing mode.`
       );
     }
+    if (this.#s.siwxEnabled && billing === "metered") {
+      throw new Error(
+        `route '${this.#s.key}': Cannot combine .siwx() and .metered() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+      );
+    }
     const next = this.fork();
     next.#s.authMode = "paid";
     next.#s.pricing = pricing;
@@ -3525,6 +3547,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': price '${pricing}' must be a positive decimal string`
       );
     }
+    if (typeof pricing === "function" && next.#s.maxPrice === void 0) {
+      throw new Error(
+        `route '${this.#s.key}': dynamic pricing requires maxPrice \u2014 without it, bare probes would advertise a $0 challenge`
+      );
+    }
     if (next.#s.maxPrice !== void 0 && !isPositiveDecimal(next.#s.maxPrice)) {
       throw new Error(
         `route '${this.#s.key}': maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
@@ -3544,12 +3571,16 @@ var RouteBuilder = class _RouteBuilder {
   }
   /**
    * Require Sign-In-with-X wallet identity on this route — clients prove
-   * control of a wallet via a signed challenge. Combine with `.paid()` to gate
-   * a paid route on a verified wallet identity.
+   * control of a wallet via a signed challenge. Composes with `.paid()` and
+   * `.upTo()` for pay-once-then-replay: the first request settles normally,
+   * subsequent requests with a valid SIWX signature for the same wallet skip
+   * payment (on `.upTo()`, `charge(amount)` becomes a no-op on the replay).
+   * Mutually exclusive with `.metered()`.
    *
    * @example
    * ```ts
    * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
+   * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
    * ```
    */
   siwx() {
@@ -3563,6 +3594,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': Combining .siwx() and .apiKey() is not supported on the same route.`
       );
     }
+    if (this.#s.billing === "metered") {
+      throw new Error(
+        `route '${this.#s.key}': Cannot combine .metered() and .siwx() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+      );
+    }
     const next = this.fork();
     next.#s.siwxEnabled = true;
     if (next.#s.authMode === "paid" || next.#s.pricing) {

package/package.json

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