@agentcash/router 0.4.7 → 0.4.9

package/.claude/CLAUDE.md

@@ -10,7 +10,7 @@ Protocol-agnostic route framework for Next.js App Router APIs with x402 payment,
 4. **Observability is pluggable via RouterPlugin.** Zero boilerplate.
 5. **The package owns the x402 server lifecycle.** Init, verify, settle.
 6. **Convention over configuration.** Sane defaults for Base, USDC, exact scheme.
-7. **Compose, don't reimplement.** Zero payment/auth protocol logic — delegates to `@x402/*` and `@coinbase/x402`.
+7. **Compose, don't reimplement.** Zero payment/auth protocol logic — delegates to `@x402/*`, `@coinbase/x402`, and `mppx`.
 
 ## Architecture
 
@@ -25,7 +25,7 @@ Protocol-agnostic route framework for Next.js App Router APIs with x402 payment,
 - `src/plugin.ts` — Plugin hook system
 - `src/server.ts` — x402 server initialization
 - `src/auth/` — Auth modules (siwx.ts, api-key.ts, nonce.ts)
-- `src/protocols/` — Protocol handlers (x402.ts, mpp.ts, detect.ts)
+- `src/protocols/` — Protocol handlers (x402.ts, detect.ts). MPP is handled via `mppx` high-level API (`Mppx.create` in index.ts)
 - `src/discovery/` — Auto-generated endpoints (well-known.ts, openapi.ts)
 
 ## Auth Modes
@@ -187,43 +187,6 @@ pnpm typecheck  # tsc --noEmit
 pnpm check      # format + lint + typecheck + build + test
 ```
 
-## Releasing
-
-**Release flow:** PR with version bump → merge → create GitHub Release → auto-publish to npm
-
-### When doing work that should be released:
-
-1. **Update `CHANGELOG.md`** — Add entry under new version heading with changes
-2. **Bump version in `package.json`** — Match the changelog version
-3. **Commit both** — e.g., `chore: bump to v0.6.0`
-4. **Merge PR to main**
-
-### To publish (human step):
-
-1. Go to [GitHub Releases](https://github.com/Merit-Systems/agentcash-router/releases)
-2. Click **Draft a new release**
-3. Create tag: `v0.6.0` (must match package.json version)
-4. Title: `v0.6.0`
-5. Description: Copy from CHANGELOG.md or click "Generate release notes"
-6. Click **Publish release**
-
-The `publish.yml` workflow will:
-- Run full test suite (`pnpm check`)
-- Verify package.json version matches tag
-- Publish to npm with `--access public`
-
-### Version format
-
-- **Patch** (`0.5.1`): Bug fixes, docs, internal changes
-- **Minor** (`0.6.0`): New features, non-breaking additions
-- **Major** (`1.0.0`): Breaking changes (holding until API stabilizes)
-
-### Troubleshooting
-
-- **Version mismatch error**: package.json version must exactly match the release tag (without `v` prefix)
-- **Publish fails**: Check `NPM_TOKEN` secret is set and has write access to `@agentcash` scope
-- **Tests fail**: Fix in a new PR, then re-create the release
-
 ## Development Record
 
 The `.claude/` directory contains design docs, decision records, and bug analyses that document the reasoning behind the router's architecture. See `.claude/INDEX.md` for a table of contents.

package/.claude/skills/router-guide/SKILL.md

@@ -31,7 +31,7 @@ Every paid API route in a Merit Systems service shared the same ~80-150 lines of
 
 7. **Self-registering routes + validated barrel (Approach B).** Routes self-register via `.handler()` at import time. A barrel file imports all route modules. Discovery endpoints (`.wellKnown()`, `.openapi()`) validate that the barrel is complete by comparing registered routes against the `prices` map. For routes in separate handler files (e.g., Next.js `route.ts` files), use **discovery stubs** — lightweight registrations that provide metadata for discovery without the real handler. Guard stubs with `registry.has()` to avoid unnecessary overwrites.
 
-8. **Both x402 and MPP ship from day one.** Dual-protocol support is not an afterthought. Routes declare `protocols: ['x402', 'mpp']` and the orchestration layer routes to the correct handler based on the request header. MPP uses low-level `mppx` primitives (`Challenge`, `Credential`, `tempo.charge`) — not the high-level `Mppx.create()` wrapper — because the router owns orchestration.
+8. **Both x402 and MPP ship from day one.** Dual-protocol support is not an afterthought. Routes declare `protocols: ['x402', 'mpp']` and the orchestration layer routes to the correct handler based on the request header. MPP uses `mppx`'s high-level `Mppx.create()` API — the router creates an instance at init time and calls `mppx.charge({ amount })(request)` at request time. This returns either a 402 challenge or a 200 with `withReceipt()` for attaching the payment receipt header.
 
 9. **`zod-openapi` for OpenAPI 3.1.** Zod schemas are the single source of truth for request/response types. OpenAPI docs are auto-generated from them. No manual spec maintenance.
 
@@ -80,7 +80,7 @@ Request in
   → protocol verify (x402 or MPP)
   → plugin.onPaymentVerified()
   → handler(ctx) → result
-  → if status < 400: settle payment (x402) or receipt (MPP)
+  → if status < 400: settle payment (x402) or withReceipt (MPP)
   → if provider configured: fireProviderQuota()
   → plugin.onResponse()
 Response out
@@ -101,7 +101,6 @@ Response out
 | `src/registry.ts` | `RouteRegistry` with barrel validation |
 | `src/protocols/detect.ts` | Header-based protocol detection |
 | `src/protocols/x402.ts` | x402 challenge/verify/settle wrappers |
-| `src/protocols/mpp.ts` | MPP challenge/verify/receipt wrappers (uses mppx low-level primitives) |
 | `src/server.ts` | x402 server initialization with retry |
 | `src/auth/siwx.ts` | SIWX verification |
 | `src/auth/api-key.ts` | API key verification |
@@ -159,7 +158,7 @@ TEMPO_RPC_URL=https://user:pass@rpc.mainnet.tempo.xyz  # Authenticated Tempo RPC
 
 **Tempo RPC requires authentication.** The default `rpc.tempo.xyz` returns 401. Get credentials from the Tempo team. The `rpcUrl` can be set in config or via `TEMPO_RPC_URL` env var (config takes precedence).
 
-**Peer dependencies for MPP:** `mppx` is an optional peer dep. It has `viem` as a peer dependency. Both are required for MPP support.
+**Peer dependency for MPP:** `mppx` is an optional peer dep. Required only when `protocols` includes `'mpp'`.
 
 ## Creating Routes
 
@@ -415,21 +414,26 @@ The type system (generic parameters `HasAuth`, `NeedsBody`, `HasBody`) prevents
 - `.siwx()` is mutually exclusive with `.paid()`
 - `.apiKey()` CAN compose with `.paid()`
 
-## MPP Internals (Critical Pitfalls)
+## MPP Internals
 
-The router uses mppx's **low-level primitives**, not the high-level `Mppx.create()` API. This matters because mppx's internals have subtle conventions:
+The router uses `mppx`'s high-level `Mppx.create()` API, which encapsulates the entire challenge-credential-receipt lifecycle.
 
-1. **NextRequest vs Request.** `Credential.fromRequest()` breaks with Next.js `NextRequest` due to subtle header handling differences. The router converts via `toStandardRequest()` — creating a new standard `Request` with the same URL, method, headers, and body.
+### How it works
 
-2. **`Challenge.fromIntent()` takes payment data, not an HTTP Request.** The `request` field in `fromIntent()` is the payment request object (`{ amount, currency, recipient, decimals }`), NOT the HTTP Request. Passing the wrong object causes silent challenge generation failures.
+1. **Init time** (`src/index.ts`): `Mppx.create({ methods: [tempo.charge({ currency, recipient, rpcUrl })], secretKey })` creates a server instance. This is done inside the async `initPromise` IIFE alongside x402 server init.
 
-3. **`tempo.charge().verify()` returns a receipt, not `{ valid, payer }`.** On success it returns `{ method, status, reference, timestamp }`. On failure it throws. Check `receipt.status === 'success'`, not `receipt.valid`.
+2. **Challenge** (`build402` in orchestrate.ts): `deps.mppx.charge({ amount })(request)` returns `{ status: 402, challenge: Response }`. The `WWW-Authenticate` header is extracted from the challenge `Response` and set on the router's 402 response.
 
-4. **`tempo.charge()` constructor takes operational config only.** In mppx, `currency` and `recipient` are NOT passed to `tempo.charge()`. They are passed in the `request` object to `Challenge.fromIntent()` and `verify()`. Only `getClient`, `decimals`, `feePayer`, `testnet`, etc. go in the constructor.
+3. **Verify + Receipt** (MPP section in orchestrate.ts): `deps.mppx.charge({ amount })(request)` returns `{ status: 200, withReceipt }` when the credential is valid. `withReceipt(response)` returns a new `Response` with the `Payment-Receipt` header attached.
 
-5. **Tempo RPC requires authentication.** The default `rpc.tempo.xyz` returns 401. Always provide `rpcUrl` or set `TEMPO_RPC_URL` env var with authenticated credentials.
+4. **Wallet extraction**: `Credential.fromRequest(request)` (from `mppx` core) extracts the credential, and `credential.source` contains the payer's DID.
 
-6. **viem is a peer dep of mppx.** The router uses viem directly for `createClient` and `http` in `buildGetClient()`. viem is always available when mppx is installed as a peer dep.
+### Key details
+
+- **`withReceipt()` creates a new Response** — it does not mutate the original. The returned value must be used (cast to `NextResponse`).
+- **`Credential.fromRequest()` is the only low-level mppx import** — used solely for wallet extraction after mppx has already verified the payment.
+- **`mppx` is an optional peer dep** — routes using `protocols: ['mpp']` require it. The router's `OrchestrateDeps.mppx` is `null` when not configured.
+- **Tempo RPC requires authentication.** The default `rpc.tempo.xyz` returns 401. Always provide `rpcUrl` or set `TEMPO_RPC_URL` env var with authenticated credentials.
 
 ## Registration-Time Validation
 
@@ -497,9 +501,6 @@ Barrel validation catches mismatches: keys in `prices` but not registered → er
 | Route not in discovery docs | Missing barrel import | Import the route file in your barrel |
 | Settlement not happening | Handler returned status >= 400 | Settlement is gated on success responses |
 | MPP 401 `unauthorized: authentication required` | Using default unauthenticated Tempo RPC | Set `TEMPO_RPC_URL` env var or `mpp.rpcUrl` config with authenticated URL |
-| MPP `Credential.fromRequest()` returns undefined | NextRequest header handling incompatibility | Router handles this via `toStandardRequest()` — if you see this, the router dist is stale |
-| MPP verify returns `status: 'success'` but route returns 402 | Code checking `.valid` instead of `.status` | Verify returns a receipt `{ status, reference }`, not `{ valid, payer }` |
-| MPP using wrong RPC URL after rebuild | Next.js webpack cache or stale pnpm link | Delete `.next/`, run `pnpm install` in the app to pick up new router dist |
 | `route 'X' in prices map but not registered` | Discovery endpoint hit before route module loaded | Add barrel import to discovery route files |
 | `mppx package is required` | mppx not installed | `pnpm add mppx` — it's an optional peer dep |
 

package/dist/index.cjs

@@ -123,7 +123,7 @@ var RouteRegistry = class {
 };
 
 // src/orchestrate.ts
-var import_server3 = require("next/server");
+var import_server2 = require("next/server");
 
 // src/plugin.ts
 function createDefaultContext(meta) {
@@ -366,6 +366,9 @@ function resolveMaxPrice(pricing) {
   return max;
 }
 
+// src/orchestrate.ts
+var import_mppx = require("mppx");
+
 // src/protocols/x402.ts
 async function buildX402Challenge(server, routeEntry, request, price, payeeAddress, network, extensions) {
   const { encodePaymentRequiredHeader } = await import("@x402/core/http");
@@ -431,107 +434,6 @@ async function settleX402Payment(server, payload, requirements) {
   return { encoded, result };
 }
 
-// src/protocols/mpp.ts
-var import_mppx = require("mppx");
-var import_server2 = require("mppx/server");
-var import_viem = require("viem");
-var import_chains = require("viem/chains");
-function buildGetClient(rpcUrl) {
-  const url = rpcUrl ?? process.env.TEMPO_RPC_URL;
-  if (!url) return {};
-  return {
-    getClient: () => (0, import_viem.createClient)({ chain: import_chains.tempo, transport: (0, import_viem.http)(url) })
-  };
-}
-function toStandardRequest(request) {
-  if (request.constructor.name === "Request") {
-    return request;
-  }
-  return new Request(request.url, {
-    method: request.method,
-    headers: request.headers
-  });
-}
-var DEFAULT_DECIMALS = 6;
-async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
-  const standardRequest = toStandardRequest(request);
-  const currency = mppConfig.currency;
-  const recipient = mppConfig.recipient ?? "";
-  const methodIntent = import_server2.tempo.charge();
-  const challenge = import_mppx.Challenge.fromIntent(methodIntent, {
-    secretKey: mppConfig.secretKey,
-    realm: new URL(standardRequest.url).origin,
-    request: {
-      amount: price,
-      currency,
-      recipient,
-      decimals: DEFAULT_DECIMALS
-    }
-  });
-  return import_mppx.Challenge.serialize(challenge);
-}
-async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
-  const standardRequest = toStandardRequest(request);
-  const currency = mppConfig.currency;
-  const recipient = mppConfig.recipient ?? "";
-  try {
-    const authHeader = standardRequest.headers.get("Authorization");
-    if (!authHeader) {
-      console.error("[MPP] No Authorization header found");
-      return null;
-    }
-    const credential = import_mppx.Credential.fromRequest(standardRequest);
-    if (!credential?.challenge) {
-      console.error("[MPP] Invalid credential structure");
-      return null;
-    }
-    const isValid = import_mppx.Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
-    if (!isValid) {
-      console.error("[MPP] Challenge HMAC verification failed");
-      return { valid: false, payer: null };
-    }
-    const methodIntent = import_server2.tempo.charge({
-      ...buildGetClient(mppConfig.rpcUrl)
-    });
-    const paymentRequest = {
-      amount: price,
-      currency,
-      recipient,
-      decimals: DEFAULT_DECIMALS
-    };
-    const receipt = await methodIntent.verify({
-      credential,
-      request: paymentRequest
-    });
-    if (!receipt || receipt.status !== "success") {
-      console.error("[MPP] Tempo verification failed:", receipt);
-      return { valid: false, payer: null };
-    }
-    const payer = receipt.reference ?? "";
-    return {
-      valid: true,
-      payer,
-      txHash: receipt.reference
-    };
-  } catch (error) {
-    console.error("[MPP] Credential verification error:", {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : void 0,
-      errorType: error?.constructor?.name
-    });
-    return null;
-  }
-}
-function buildMPPReceipt(reference) {
-  const receipt = import_mppx.Receipt.from({
-    method: "tempo",
-    status: "success",
-    reference,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  return import_mppx.Receipt.serialize(receipt);
-}
-
 // src/auth/siwx.ts
 var SIWX_ERROR_MESSAGES = {
   siwx_missing_header: "Missing SIGN-IN-WITH-X header",
@@ -633,7 +535,7 @@ function createRequestHandler(routeEntry, handler, deps) {
     firePluginResponse(deps, pluginCtx, meta, response);
   }
   function fail(status, message, meta, pluginCtx) {
-    const response = import_server3.NextResponse.json({ success: false, error: message }, { status });
+    const response = import_server2.NextResponse.json({ success: false, error: message }, { status });
     firePluginResponse(deps, pluginCtx, meta, response);
     return response;
   }
@@ -692,7 +594,8 @@ function createRequestHandler(routeEntry, handler, deps) {
     }
     const protocol = detectProtocol(request);
     let earlyBodyData;
-    const needsEarlyParse = !protocol && routeEntry.bodySchema && (typeof routeEntry.pricing === "function" || routeEntry.validateFn);
+    const pricingNeedsBody = routeEntry.pricing != null && typeof routeEntry.pricing !== "string";
+    const needsEarlyParse = !protocol && routeEntry.bodySchema && (pricingNeedsBody || routeEntry.validateFn);
     if (needsEarlyParse) {
       const requestForPricing = request.clone();
       const earlyBodyResult = await parseBody(requestForPricing, routeEntry);
@@ -775,7 +678,7 @@ function createRequestHandler(routeEntry, handler, deps) {
             route: routeEntry.key
           });
         }
-        const response = new import_server3.NextResponse(JSON.stringify(paymentRequired), {
+        const response = new import_server2.NextResponse(JSON.stringify(paymentRequired), {
           status: 402,
           headers: { "Content-Type": "application/json" }
         });
@@ -785,7 +688,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       }
       const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
       if (!siwx.valid) {
-        const response = import_server3.NextResponse.json(
+        const response = import_server2.NextResponse.json(
           { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
           { status: 402 }
         );
@@ -802,6 +705,21 @@ function createRequestHandler(routeEntry, handler, deps) {
       return handleAuth(wallet, void 0);
     }
     if (!protocol || protocol === "siwx") {
+      if (routeEntry.pricing) {
+        const initErrors = routeEntry.protocols.map((p) => {
+          if (p === "x402" && deps.x402InitError) return `x402: ${deps.x402InitError}`;
+          if (p === "mpp" && deps.mppInitError) return `mpp: ${deps.mppInitError}`;
+          return null;
+        }).filter(Boolean);
+        if (initErrors.length > 0) {
+          return fail(
+            500,
+            `Payment protocol initialization failed. ${initErrors.join("; ")}`,
+            meta,
+            pluginCtx
+          );
+        }
+      }
       return await build402(request, routeEntry, deps, meta, pluginCtx, earlyBodyData);
     }
     const body = await parseBody(request, routeEntry);
@@ -829,9 +747,22 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx
       );
     }
+    if (!routeEntry.protocols.includes(protocol)) {
+      const accepted = routeEntry.protocols.join(", ") || "none";
+      console.warn(
+        `[router] ${routeEntry.key}: received ${protocol} payment but route accepts [${accepted}]`
+      );
+      return fail(
+        400,
+        `This route does not accept ${protocol} payments. Accepted protocols: ${accepted}`,
+        meta,
+        pluginCtx
+      );
+    }
     if (protocol === "x402") {
       if (!deps.x402Server) {
         const reason = deps.x402InitError ? `x402 facilitator initialization failed: ${deps.x402InitError}` : "x402 server not initialized \u2014 ensure @x402/core, @x402/evm, and @coinbase/x402 are installed";
+        console.error(`[router] ${routeEntry.key}: ${reason}`);
         return fail(500, reason, meta, pluginCtx);
       }
       const verify = await verifyX402Payment(
@@ -904,10 +835,37 @@ function createRequestHandler(routeEntry, handler, deps) {
       return response;
     }
     if (protocol === "mpp") {
-      if (!deps.mppConfig) return await build402(request, routeEntry, deps, meta, pluginCtx);
-      const verify = await verifyMPPCredential(request, routeEntry, deps.mppConfig, price);
-      if (!verify?.valid) return await build402(request, routeEntry, deps, meta, pluginCtx);
-      const wallet = verify.payer.toLowerCase();
+      if (!deps.mppx) {
+        const reason = deps.mppInitError ? `MPP initialization failed: ${deps.mppInitError}` : "MPP not initialized \u2014 ensure mppx is installed and mpp config (secretKey, currency, recipient) is correct";
+        console.error(`[router] ${routeEntry.key}: ${reason}`);
+        return fail(500, reason, meta, pluginCtx);
+      }
+      let mppResult;
+      try {
+        mppResult = await deps.mppx.charge({ amount: price })(request);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[router] ${routeEntry.key}: MPP charge failed: ${message}`);
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "critical",
+          message: `MPP charge failed: ${message}`,
+          route: routeEntry.key
+        });
+        return fail(500, `MPP payment processing failed: ${message}`, meta, pluginCtx);
+      }
+      if (mppResult.status === 402) {
+        console.warn(
+          `[router] ${routeEntry.key}: MPP credential present but charge() returned 402 \u2014 credential may be invalid, or check TEMPO_RPC_URL configuration`
+        );
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "warn",
+          message: "MPP payment rejected despite credential present \u2014 possible config issue (TEMPO_RPC_URL)",
+          route: routeEntry.key
+        });
+        return await build402(request, routeEntry, deps, meta, pluginCtx);
+      }
+      const credential = import_mppx.Credential.fromRequest(request);
+      const wallet = (credential?.source ?? "").toLowerCase();
       pluginCtx.setVerifiedWallet(wallet);
       firePluginHook(deps.plugin, "onPaymentVerified", pluginCtx, {
         protocol: "mpp",
@@ -924,10 +882,9 @@ function createRequestHandler(routeEntry, handler, deps) {
         body.data
       );
       if (response.status < 400) {
-        try {
-          response.headers.set("Payment-Receipt", await buildMPPReceipt(crypto.randomUUID()));
-        } catch {
-        }
+        const receiptResponse = mppResult.withReceipt(response);
+        finalize(receiptResponse, rawResult, meta, pluginCtx);
+        return receiptResponse;
       }
       finalize(response, rawResult, meta, pluginCtx);
       return response;
@@ -942,7 +899,7 @@ async function parseBody(request, routeEntry) {
   if (result.success) return { ok: true, data: result.data };
   return {
     ok: false,
-    response: import_server3.NextResponse.json(
+    response: import_server2.NextResponse.json(
       { success: false, error: result.error, issues: result.issues },
       { status: 400 }
     )
@@ -1001,7 +958,7 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
       });
       return { price: routeEntry.maxPrice };
     } else {
-      const errorResponse = import_server3.NextResponse.json(
+      const errorResponse = import_server2.NextResponse.json(
         { success: false, error: "Price calculation failed" },
         { status: 500 }
       );
@@ -1011,14 +968,14 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
   }
 }
 async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
-  const response = new import_server3.NextResponse(null, {
+  const response = new import_server2.NextResponse(null, {
     status: 402,
     headers: {
       "Content-Type": "application/json"
     }
   });
   let challengePrice;
-  if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
+  if (bodyData !== void 0 && typeof routeEntry.pricing !== "string" && routeEntry.pricing != null) {
     const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);
     if ("error" in result) return result.error;
     challengePrice = result.price;
@@ -1069,12 +1026,13 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
       });
     }
   }
-  if (routeEntry.protocols.includes("mpp") && deps.mppConfig) {
+  if (routeEntry.protocols.includes("mpp") && deps.mppx) {
     try {
-      response.headers.set(
-        "WWW-Authenticate",
-        await buildMPPChallenge(routeEntry, request, deps.mppConfig, challengePrice)
-      );
+      const result = await deps.mppx.charge({ amount: challengePrice })(request);
+      if (result.status === 402) {
+        const wwwAuth = result.challenge.headers.get("WWW-Authenticate");
+        if (wwwAuth) response.headers.set("WWW-Authenticate", wwwAuth);
+      }
     } catch (err) {
       firePluginHook(deps.plugin, "onAlert", pluginCtx, {
         level: "critical",
@@ -1149,6 +1107,8 @@ var RouteBuilder = class {
   /** @internal */
   _maxPrice;
   /** @internal */
+  _minPrice;
+  /** @internal */
   _bodySchema;
   /** @internal */
   _querySchema;
@@ -1190,6 +1150,7 @@ var RouteBuilder = class {
     next._pricing = pricing;
     if (options?.protocols) next._protocols = options.protocols;
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
+    if (options?.minPrice) next._minPrice = options.minPrice;
     if (typeof pricing === "object" && "tiers" in pricing) {
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
@@ -1326,6 +1287,7 @@ var RouteBuilder = class {
       path: this._path,
       method: this._method,
       maxPrice: this._maxPrice,
+      minPrice: this._minPrice,
       apiKeyResolver: this._apiKeyResolver,
       providerName: this._providerName,
       providerConfig: this._providerConfig,
@@ -1337,7 +1299,7 @@ var RouteBuilder = class {
 };
 
 // src/discovery/well-known.ts
-var import_server4 = require("next/server");
+var import_server3 = require("next/server");
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
   let validated = false;
   return async (_request) => {
@@ -1375,7 +1337,7 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (instructions) {
       body.instructions = instructions;
     }
-    return import_server4.NextResponse.json(body, {
+    return import_server3.NextResponse.json(body, {
       headers: {
         "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET",
@@ -1386,12 +1348,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
 }
 
 // src/discovery/openapi.ts
-var import_server5 = require("next/server");
+var import_server4 = require("next/server");
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
   let cached = null;
   let validated = false;
   return async (_request) => {
-    if (cached) return import_server5.NextResponse.json(cached);
+    if (cached) return import_server4.NextResponse.json(cached);
     if (!validated && pricesKeys) {
       registry.validate(pricesKeys);
       validated = true;
@@ -1418,7 +1380,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       paths
     });
-    return import_server5.NextResponse.json(cached);
+    return import_server4.NextResponse.json(cached);
   };
 }
 function deriveTag(routeKey) {
@@ -1428,9 +1390,16 @@ function buildOperation(routeKey, entry, tag) {
   const protocols = entry.protocols.length > 0 ? entry.protocols : void 0;
   let price;
   if (typeof entry.pricing === "string") {
-    price = parseFloat(entry.pricing);
+    price = entry.pricing;
+  } else if (typeof entry.pricing === "object" && "tiers" in entry.pricing) {
+    const tierPrices = Object.values(entry.pricing.tiers).map((t) => parseFloat(t.price));
+    const min = Math.min(...tierPrices);
+    const max = Math.max(...tierPrices);
+    price = min === max ? String(min) : `${min}-${max}`;
+  } else if (entry.minPrice && entry.maxPrice) {
+    price = `${entry.minPrice}-${entry.maxPrice}`;
   } else if (entry.maxPrice) {
-    price = parseFloat(entry.maxPrice);
+    price = entry.maxPrice;
   }
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
@@ -1480,21 +1449,30 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
-  if (config.protocols) {
-    if (config.protocols.length === 0) {
-      throw new Error(
-        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
-      );
-    }
-    if (config.protocols.includes("mpp") && !config.mpp) {
-      throw new Error(
-        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
-      );
+  if (config.protocols && config.protocols.length === 0) {
+    throw new Error(
+      "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+    );
+  }
+  let x402ConfigError;
+  let mppConfigError;
+  if ((!config.protocols || config.protocols.includes("x402")) && !config.payeeAddress) {
+    x402ConfigError = "x402 requires payeeAddress in router config.";
+  }
+  if (config.protocols?.includes("mpp")) {
+    if (!config.mpp) {
+      mppConfigError = 'protocols includes "mpp" but mpp config is missing. Add mpp: { secretKey, currency, recipient } to your router config.';
+    } else if (!config.mpp.recipient && !config.payeeAddress) {
+      mppConfigError = "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config.";
+    } else if (!(config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL)) {
+      mppConfigError = "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object.";
     }
-    if (config.protocols.includes("x402") && !config.payeeAddress) {
-      throw new Error(
-        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
-      );
+  }
+  const allConfigErrors = [x402ConfigError, mppConfigError].filter(Boolean);
+  if (allConfigErrors.length > 0) {
+    for (const err of allConfigErrors) console.error(`[router] ${err}`);
+    if (process.env.NODE_ENV === "production") {
+      throw new Error(allConfigErrors.join("\n"));
     }
   }
   if (config.plugin?.init) {
@@ -1514,17 +1492,47 @@ function createRouter(config) {
     nonceStore,
     payeeAddress: config.payeeAddress,
     network,
-    mppConfig: config.mpp
+    mppx: null
   };
   deps.initPromise = (async () => {
-    try {
-      const { createX402Server: createX402Server2 } = await Promise.resolve().then(() => (init_server(), server_exports));
-      const result = await createX402Server2(config);
-      deps.x402Server = result.server;
-      await result.initPromise;
-    } catch (err) {
-      deps.x402Server = null;
-      deps.x402InitError = err instanceof Error ? err.message : String(err);
+    if (x402ConfigError) {
+      deps.x402InitError = x402ConfigError;
+    } else {
+      try {
+        const { createX402Server: createX402Server2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+        const result = await createX402Server2(config);
+        deps.x402Server = result.server;
+        await result.initPromise;
+      } catch (err) {
+        deps.x402Server = null;
+        deps.x402InitError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    if (mppConfigError) {
+      deps.mppInitError = mppConfigError;
+    } else if (config.mpp) {
+      try {
+        const { Mppx, tempo } = await import("mppx/server");
+        const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+        deps.mppx = Mppx.create({
+          methods: [
+            tempo.charge({
+              currency: config.mpp.currency,
+              recipient: config.mpp.recipient ?? config.payeeAddress,
+              getClient: async () => {
+                const { createClient, http } = await import("viem");
+                const { tempo: tempoChain } = await import("viem/chains");
+                return createClient({ chain: tempoChain, transport: http(rpcUrl) });
+              }
+            })
+          ],
+          secretKey: config.mpp.secretKey
+        });
+      } catch (err) {
+        deps.mppx = null;
+        deps.mppInitError = err instanceof Error ? err.message : String(err);
+        console.error(`[router] MPP initialization failed: ${deps.mppInitError}`);
+      }
     }
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;

package/dist/index.d.cts

@@ -170,6 +170,7 @@ type PricingConfig<TBody = unknown> = string | ((body: TBody) => string | Promis
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
+    minPrice?: string;
 }
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
@@ -218,6 +219,7 @@ interface RouteEntry {
     path?: string;
     method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
     maxPrice?: string;
+    minPrice?: string;
     apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
     providerName?: string;
     providerConfig?: ProviderConfig;
@@ -286,16 +288,22 @@ interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
     x402InitError?: string;
+    mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
     payeeAddress: string;
     network: string;
-    mppConfig?: {
-        secretKey: string;
-        currency: string;
-        recipient?: string;
-        rpcUrl?: string;
-    };
+    mppx?: {
+        charge: (options: {
+            amount: string;
+        }) => (input: Request) => Promise<{
+            status: 402;
+            challenge: Response;
+        } | {
+            status: 200;
+            withReceipt: (response: Response) => Response;
+        }>;
+    } | null;
 }
 
 type True = true;
@@ -308,6 +316,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _pricing: PricingConfig | undefined;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
+    /** @internal */ _minPrice: string | undefined;
     /** @internal */ _bodySchema: ZodType | undefined;
     /** @internal */ _querySchema: ZodType | undefined;
     /** @internal */ _outputSchema: ZodType | undefined;
@@ -378,13 +387,15 @@ interface MonitorEntry {
     warn?: number;
     critical?: number;
 }
-interface ServiceRouter {
-    route(key: string): RouteBuilder;
+interface ServiceRouter<TPriceKeys extends string = never> {
+    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
     wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
     openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
-declare function createRouter(config: RouterConfig): ServiceRouter;
+declare function createRouter<const P extends Record<string, string> = Record<string, never>>(config: RouterConfig & {
+    prices?: P;
+}): ServiceRouter<Extract<keyof P, string>>;
 
 export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisNonceStore, createRouter };

package/dist/index.d.ts

@@ -170,6 +170,7 @@ type PricingConfig<TBody = unknown> = string | ((body: TBody) => string | Promis
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
+    minPrice?: string;
 }
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
@@ -218,6 +219,7 @@ interface RouteEntry {
     path?: string;
     method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
     maxPrice?: string;
+    minPrice?: string;
     apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
     providerName?: string;
     providerConfig?: ProviderConfig;
@@ -286,16 +288,22 @@ interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
     x402InitError?: string;
+    mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
     payeeAddress: string;
     network: string;
-    mppConfig?: {
-        secretKey: string;
-        currency: string;
-        recipient?: string;
-        rpcUrl?: string;
-    };
+    mppx?: {
+        charge: (options: {
+            amount: string;
+        }) => (input: Request) => Promise<{
+            status: 402;
+            challenge: Response;
+        } | {
+            status: 200;
+            withReceipt: (response: Response) => Response;
+        }>;
+    } | null;
 }
 
 type True = true;
@@ -308,6 +316,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _pricing: PricingConfig | undefined;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
+    /** @internal */ _minPrice: string | undefined;
     /** @internal */ _bodySchema: ZodType | undefined;
     /** @internal */ _querySchema: ZodType | undefined;
     /** @internal */ _outputSchema: ZodType | undefined;
@@ -378,13 +387,15 @@ interface MonitorEntry {
     warn?: number;
     critical?: number;
 }
-interface ServiceRouter {
-    route(key: string): RouteBuilder;
+interface ServiceRouter<TPriceKeys extends string = never> {
+    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
     wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
     openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
-declare function createRouter(config: RouterConfig): ServiceRouter;
+declare function createRouter<const P extends Record<string, string> = Record<string, never>>(config: RouterConfig & {
+    prices?: P;
+}): ServiceRouter<Extract<keyof P, string>>;
 
 export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisNonceStore, createRouter };

package/dist/index.js

@@ -329,6 +329,9 @@ function resolveMaxPrice(pricing) {
   return max;
 }
 
+// src/orchestrate.ts
+import { Credential } from "mppx";
+
 // src/protocols/x402.ts
 async function buildX402Challenge(server, routeEntry, request, price, payeeAddress, network, extensions) {
   const { encodePaymentRequiredHeader } = await import("@x402/core/http");
@@ -394,107 +397,6 @@ async function settleX402Payment(server, payload, requirements) {
   return { encoded, result };
 }
 
-// src/protocols/mpp.ts
-import { Challenge, Credential, Receipt } from "mppx";
-import { tempo } from "mppx/server";
-import { createClient, http } from "viem";
-import { tempo as tempoChain } from "viem/chains";
-function buildGetClient(rpcUrl) {
-  const url = rpcUrl ?? process.env.TEMPO_RPC_URL;
-  if (!url) return {};
-  return {
-    getClient: () => createClient({ chain: tempoChain, transport: http(url) })
-  };
-}
-function toStandardRequest(request) {
-  if (request.constructor.name === "Request") {
-    return request;
-  }
-  return new Request(request.url, {
-    method: request.method,
-    headers: request.headers
-  });
-}
-var DEFAULT_DECIMALS = 6;
-async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
-  const standardRequest = toStandardRequest(request);
-  const currency = mppConfig.currency;
-  const recipient = mppConfig.recipient ?? "";
-  const methodIntent = tempo.charge();
-  const challenge = Challenge.fromIntent(methodIntent, {
-    secretKey: mppConfig.secretKey,
-    realm: new URL(standardRequest.url).origin,
-    request: {
-      amount: price,
-      currency,
-      recipient,
-      decimals: DEFAULT_DECIMALS
-    }
-  });
-  return Challenge.serialize(challenge);
-}
-async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
-  const standardRequest = toStandardRequest(request);
-  const currency = mppConfig.currency;
-  const recipient = mppConfig.recipient ?? "";
-  try {
-    const authHeader = standardRequest.headers.get("Authorization");
-    if (!authHeader) {
-      console.error("[MPP] No Authorization header found");
-      return null;
-    }
-    const credential = Credential.fromRequest(standardRequest);
-    if (!credential?.challenge) {
-      console.error("[MPP] Invalid credential structure");
-      return null;
-    }
-    const isValid = Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
-    if (!isValid) {
-      console.error("[MPP] Challenge HMAC verification failed");
-      return { valid: false, payer: null };
-    }
-    const methodIntent = tempo.charge({
-      ...buildGetClient(mppConfig.rpcUrl)
-    });
-    const paymentRequest = {
-      amount: price,
-      currency,
-      recipient,
-      decimals: DEFAULT_DECIMALS
-    };
-    const receipt = await methodIntent.verify({
-      credential,
-      request: paymentRequest
-    });
-    if (!receipt || receipt.status !== "success") {
-      console.error("[MPP] Tempo verification failed:", receipt);
-      return { valid: false, payer: null };
-    }
-    const payer = receipt.reference ?? "";
-    return {
-      valid: true,
-      payer,
-      txHash: receipt.reference
-    };
-  } catch (error) {
-    console.error("[MPP] Credential verification error:", {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : void 0,
-      errorType: error?.constructor?.name
-    });
-    return null;
-  }
-}
-function buildMPPReceipt(reference) {
-  const receipt = Receipt.from({
-    method: "tempo",
-    status: "success",
-    reference,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  return Receipt.serialize(receipt);
-}
-
 // src/auth/siwx.ts
 var SIWX_ERROR_MESSAGES = {
   siwx_missing_header: "Missing SIGN-IN-WITH-X header",
@@ -655,7 +557,8 @@ function createRequestHandler(routeEntry, handler, deps) {
     }
     const protocol = detectProtocol(request);
     let earlyBodyData;
-    const needsEarlyParse = !protocol && routeEntry.bodySchema && (typeof routeEntry.pricing === "function" || routeEntry.validateFn);
+    const pricingNeedsBody = routeEntry.pricing != null && typeof routeEntry.pricing !== "string";
+    const needsEarlyParse = !protocol && routeEntry.bodySchema && (pricingNeedsBody || routeEntry.validateFn);
     if (needsEarlyParse) {
       const requestForPricing = request.clone();
       const earlyBodyResult = await parseBody(requestForPricing, routeEntry);
@@ -765,6 +668,21 @@ function createRequestHandler(routeEntry, handler, deps) {
       return handleAuth(wallet, void 0);
     }
     if (!protocol || protocol === "siwx") {
+      if (routeEntry.pricing) {
+        const initErrors = routeEntry.protocols.map((p) => {
+          if (p === "x402" && deps.x402InitError) return `x402: ${deps.x402InitError}`;
+          if (p === "mpp" && deps.mppInitError) return `mpp: ${deps.mppInitError}`;
+          return null;
+        }).filter(Boolean);
+        if (initErrors.length > 0) {
+          return fail(
+            500,
+            `Payment protocol initialization failed. ${initErrors.join("; ")}`,
+            meta,
+            pluginCtx
+          );
+        }
+      }
       return await build402(request, routeEntry, deps, meta, pluginCtx, earlyBodyData);
     }
     const body = await parseBody(request, routeEntry);
@@ -792,9 +710,22 @@ function createRequestHandler(routeEntry, handler, deps) {
         pluginCtx
       );
     }
+    if (!routeEntry.protocols.includes(protocol)) {
+      const accepted = routeEntry.protocols.join(", ") || "none";
+      console.warn(
+        `[router] ${routeEntry.key}: received ${protocol} payment but route accepts [${accepted}]`
+      );
+      return fail(
+        400,
+        `This route does not accept ${protocol} payments. Accepted protocols: ${accepted}`,
+        meta,
+        pluginCtx
+      );
+    }
     if (protocol === "x402") {
       if (!deps.x402Server) {
         const reason = deps.x402InitError ? `x402 facilitator initialization failed: ${deps.x402InitError}` : "x402 server not initialized \u2014 ensure @x402/core, @x402/evm, and @coinbase/x402 are installed";
+        console.error(`[router] ${routeEntry.key}: ${reason}`);
         return fail(500, reason, meta, pluginCtx);
       }
       const verify = await verifyX402Payment(
@@ -867,10 +798,37 @@ function createRequestHandler(routeEntry, handler, deps) {
       return response;
     }
     if (protocol === "mpp") {
-      if (!deps.mppConfig) return await build402(request, routeEntry, deps, meta, pluginCtx);
-      const verify = await verifyMPPCredential(request, routeEntry, deps.mppConfig, price);
-      if (!verify?.valid) return await build402(request, routeEntry, deps, meta, pluginCtx);
-      const wallet = verify.payer.toLowerCase();
+      if (!deps.mppx) {
+        const reason = deps.mppInitError ? `MPP initialization failed: ${deps.mppInitError}` : "MPP not initialized \u2014 ensure mppx is installed and mpp config (secretKey, currency, recipient) is correct";
+        console.error(`[router] ${routeEntry.key}: ${reason}`);
+        return fail(500, reason, meta, pluginCtx);
+      }
+      let mppResult;
+      try {
+        mppResult = await deps.mppx.charge({ amount: price })(request);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[router] ${routeEntry.key}: MPP charge failed: ${message}`);
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "critical",
+          message: `MPP charge failed: ${message}`,
+          route: routeEntry.key
+        });
+        return fail(500, `MPP payment processing failed: ${message}`, meta, pluginCtx);
+      }
+      if (mppResult.status === 402) {
+        console.warn(
+          `[router] ${routeEntry.key}: MPP credential present but charge() returned 402 \u2014 credential may be invalid, or check TEMPO_RPC_URL configuration`
+        );
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "warn",
+          message: "MPP payment rejected despite credential present \u2014 possible config issue (TEMPO_RPC_URL)",
+          route: routeEntry.key
+        });
+        return await build402(request, routeEntry, deps, meta, pluginCtx);
+      }
+      const credential = Credential.fromRequest(request);
+      const wallet = (credential?.source ?? "").toLowerCase();
       pluginCtx.setVerifiedWallet(wallet);
       firePluginHook(deps.plugin, "onPaymentVerified", pluginCtx, {
         protocol: "mpp",
@@ -887,10 +845,9 @@ function createRequestHandler(routeEntry, handler, deps) {
         body.data
       );
       if (response.status < 400) {
-        try {
-          response.headers.set("Payment-Receipt", await buildMPPReceipt(crypto.randomUUID()));
-        } catch {
-        }
+        const receiptResponse = mppResult.withReceipt(response);
+        finalize(receiptResponse, rawResult, meta, pluginCtx);
+        return receiptResponse;
       }
       finalize(response, rawResult, meta, pluginCtx);
       return response;
@@ -981,7 +938,7 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
     }
   });
   let challengePrice;
-  if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
+  if (bodyData !== void 0 && typeof routeEntry.pricing !== "string" && routeEntry.pricing != null) {
     const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);
     if ("error" in result) return result.error;
     challengePrice = result.price;
@@ -1032,12 +989,13 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
       });
     }
   }
-  if (routeEntry.protocols.includes("mpp") && deps.mppConfig) {
+  if (routeEntry.protocols.includes("mpp") && deps.mppx) {
     try {
-      response.headers.set(
-        "WWW-Authenticate",
-        await buildMPPChallenge(routeEntry, request, deps.mppConfig, challengePrice)
-      );
+      const result = await deps.mppx.charge({ amount: challengePrice })(request);
+      if (result.status === 402) {
+        const wwwAuth = result.challenge.headers.get("WWW-Authenticate");
+        if (wwwAuth) response.headers.set("WWW-Authenticate", wwwAuth);
+      }
     } catch (err) {
       firePluginHook(deps.plugin, "onAlert", pluginCtx, {
         level: "critical",
@@ -1112,6 +1070,8 @@ var RouteBuilder = class {
   /** @internal */
   _maxPrice;
   /** @internal */
+  _minPrice;
+  /** @internal */
   _bodySchema;
   /** @internal */
   _querySchema;
@@ -1153,6 +1113,7 @@ var RouteBuilder = class {
     next._pricing = pricing;
     if (options?.protocols) next._protocols = options.protocols;
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
+    if (options?.minPrice) next._minPrice = options.minPrice;
     if (typeof pricing === "object" && "tiers" in pricing) {
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
@@ -1289,6 +1250,7 @@ var RouteBuilder = class {
       path: this._path,
       method: this._method,
       maxPrice: this._maxPrice,
+      minPrice: this._minPrice,
       apiKeyResolver: this._apiKeyResolver,
       providerName: this._providerName,
       providerConfig: this._providerConfig,
@@ -1391,9 +1353,16 @@ function buildOperation(routeKey, entry, tag) {
   const protocols = entry.protocols.length > 0 ? entry.protocols : void 0;
   let price;
   if (typeof entry.pricing === "string") {
-    price = parseFloat(entry.pricing);
+    price = entry.pricing;
+  } else if (typeof entry.pricing === "object" && "tiers" in entry.pricing) {
+    const tierPrices = Object.values(entry.pricing.tiers).map((t) => parseFloat(t.price));
+    const min = Math.min(...tierPrices);
+    const max = Math.max(...tierPrices);
+    price = min === max ? String(min) : `${min}-${max}`;
+  } else if (entry.minPrice && entry.maxPrice) {
+    price = `${entry.minPrice}-${entry.maxPrice}`;
   } else if (entry.maxPrice) {
-    price = parseFloat(entry.maxPrice);
+    price = entry.maxPrice;
   }
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
@@ -1443,21 +1412,30 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
-  if (config.protocols) {
-    if (config.protocols.length === 0) {
-      throw new Error(
-        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
-      );
-    }
-    if (config.protocols.includes("mpp") && !config.mpp) {
-      throw new Error(
-        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
-      );
+  if (config.protocols && config.protocols.length === 0) {
+    throw new Error(
+      "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+    );
+  }
+  let x402ConfigError;
+  let mppConfigError;
+  if ((!config.protocols || config.protocols.includes("x402")) && !config.payeeAddress) {
+    x402ConfigError = "x402 requires payeeAddress in router config.";
+  }
+  if (config.protocols?.includes("mpp")) {
+    if (!config.mpp) {
+      mppConfigError = 'protocols includes "mpp" but mpp config is missing. Add mpp: { secretKey, currency, recipient } to your router config.';
+    } else if (!config.mpp.recipient && !config.payeeAddress) {
+      mppConfigError = "MPP requires a recipient address. Set mpp.recipient or payeeAddress in your router config.";
+    } else if (!(config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL)) {
+      mppConfigError = "MPP requires an authenticated Tempo RPC URL. Set TEMPO_RPC_URL env var or pass rpcUrl in the mpp config object.";
     }
-    if (config.protocols.includes("x402") && !config.payeeAddress) {
-      throw new Error(
-        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
-      );
+  }
+  const allConfigErrors = [x402ConfigError, mppConfigError].filter(Boolean);
+  if (allConfigErrors.length > 0) {
+    for (const err of allConfigErrors) console.error(`[router] ${err}`);
+    if (process.env.NODE_ENV === "production") {
+      throw new Error(allConfigErrors.join("\n"));
     }
   }
   if (config.plugin?.init) {
@@ -1477,17 +1455,47 @@ function createRouter(config) {
     nonceStore,
     payeeAddress: config.payeeAddress,
     network,
-    mppConfig: config.mpp
+    mppx: null
   };
   deps.initPromise = (async () => {
-    try {
-      const { createX402Server: createX402Server2 } = await Promise.resolve().then(() => (init_server(), server_exports));
-      const result = await createX402Server2(config);
-      deps.x402Server = result.server;
-      await result.initPromise;
-    } catch (err) {
-      deps.x402Server = null;
-      deps.x402InitError = err instanceof Error ? err.message : String(err);
+    if (x402ConfigError) {
+      deps.x402InitError = x402ConfigError;
+    } else {
+      try {
+        const { createX402Server: createX402Server2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+        const result = await createX402Server2(config);
+        deps.x402Server = result.server;
+        await result.initPromise;
+      } catch (err) {
+        deps.x402Server = null;
+        deps.x402InitError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    if (mppConfigError) {
+      deps.mppInitError = mppConfigError;
+    } else if (config.mpp) {
+      try {
+        const { Mppx, tempo } = await import("mppx/server");
+        const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+        deps.mppx = Mppx.create({
+          methods: [
+            tempo.charge({
+              currency: config.mpp.currency,
+              recipient: config.mpp.recipient ?? config.payeeAddress,
+              getClient: async () => {
+                const { createClient, http } = await import("viem");
+                const { tempo: tempoChain } = await import("viem/chains");
+                return createClient({ chain: tempoChain, transport: http(rpcUrl) });
+              }
+            })
+          ],
+          secretKey: config.mpp.secretKey
+        });
+      } catch (err) {
+        deps.mppx = null;
+        deps.mppInitError = err instanceof Error ? err.message : String(err);
+        console.error(`[router] MPP initialization failed: ${deps.mppInitError}`);
+      }
     }
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -28,7 +28,7 @@
     "@x402/core": "^2.3.0",
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
-    "mppx": "^0.2.0",
+    "mppx": "^0.2.4",
     "next": ">=15.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
@@ -47,8 +47,8 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.2.0",
     "next": "^15.0.0",
+    "mppx": "^0.2.3",
     "prettier": "^3.8.1",
     "react": "^19.0.0",
     "tsup": "^8.0.0",