@agentcash/router 0.3.1 → 0.4.1

package/.claude/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md — @agentcash/router
+
+Protocol-agnostic route framework for Next.js App Router APIs with x402 payment, MPP payment, SIWX identity auth, and API key auth. Used by stablestudio, enrichx402, x402email, agentfacilitator, agentupload.
+
+## Guiding Principles
+
+1. **Route definition is 3-6 lines.** Everything else is derived.
+2. **Single source of truth.** Route registry drives discovery, OpenAPI, pricing, Bazaar schemas.
+3. **Auth and pricing are orthogonal and composable.** `.paid()`, `.siwx()`, `.apiKey()`, `.unprotected()`.
+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`.
+
+## Architecture
+
+**Orchestrate pipeline:** auth check -> body parse -> price resolve -> payment verify -> handler invoke -> settle -> finalize
+
+- `src/orchestrate.ts` — Full request lifecycle orchestration
+- `src/builder.ts` — Fluent RouteBuilder API
+- `src/handler.ts` — Safe handler invocation with error mapping
+- `src/types.ts` — Core types (RouteEntry, HandlerContext, HttpError)
+- `src/registry.ts` — Route registry (Map-backed, silent overwrite on duplicate keys)
+- `src/pricing.ts` — Price resolution (static, tiered, dynamic)
+- `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/discovery/` — Auto-generated endpoints (well-known.ts, openapi.ts)
+
+## Critical Rules
+
+- **Error handling:** Respect `.status` on any thrown error, not just `HttpError`. The `Object.assign(new Error(), { status })` pattern is universal in Node.js.
+- **SIWX challenge:** Must return a proper x402v2 challenge with `PAYMENT-REQUIRED` header and JSON body containing `extensions['sign-in-with-x']` with `domain`, `uri`, `version`, `chainId`, `type`, `nonce`, `issuedAt`.
+- **Discovery:** `authMode !== 'unprotected'` determines well-known visibility, not the protocol list. SIWX routes return 402 challenges and must be discoverable.
+- **OpenAPI:** Merge paths for multi-method endpoints (GET + DELETE on same path). Never overwrite.
+- **Duplicate route keys:** Registry silently overwrites (last-write-wins) with a dev-only `console.warn`. This is intentional — Next.js module loading order is non-deterministic during `next build`, so discovery stubs and real handlers may register the same key in either order. Prior art: ElysiaJS uses the identical pattern. See stablestudio `.claude/13_route-registry-dedup.md` for full research.
+- **Dynamic pricing (v0.3.1+):** Early body parsing with `request.clone()` enables accurate dynamic pricing. `maxPrice` is optional and acts as a safety net (cap + fallback). Body is parsed before 402 challenge generation when pricing function exists. See `.claude/15_router-dynamic-pricing-solution.md` for full design and derisking.
+
+## Environment Variables
+
+The router uses the default facilitator from `@coinbase/x402`, which requires CDP API keys in `process.env`:
+
+- `CDP_API_KEY_ID` — Coinbase Developer Platform API key ID
+- `CDP_API_KEY_SECRET` — CDP API key secret
+
+**Critical for Next.js apps with env validation (T3 stack, `@t3-oss/env-nextjs`):** These variables must be explicitly declared in your env schema. Next.js does not automatically expose all env vars to `process.env` — undeclared vars are invisible at runtime.
+
+Without these keys, the default facilitator cannot authenticate with CDP:
+- x402 server `initialize()` fails with "Failed to fetch supported kinds from facilitator: TypeError: fetch failed" or "Facilitator getSupported failed (401): Unauthorized"
+- All payment routes return empty 402 responses (no `PAYMENT-REQUIRED` header, no body)
+
+**Example env schema (T3/`@t3-oss/env-nextjs`):**
+
+```typescript
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    CDP_API_KEY_ID: z.string(),
+    CDP_API_KEY_SECRET: z.string(),
+    // ... other vars
+  },
+  runtimeEnv: {
+    CDP_API_KEY_ID: process.env.CDP_API_KEY_ID,
+    CDP_API_KEY_SECRET: process.env.CDP_API_KEY_SECRET,
+    // ... other vars
+  },
+});
+```
+
+**Alternative:** Pass a custom facilitator config to `createRouter()` if you want to use a different facilitator URL or auth mechanism. But for most apps, the default CDP facilitator is correct.
+
+## Version Stability
+
+The public API is **not stable**. Downstream consumers should pin exact versions (`"@agentcash/router": "0.2.0"`, not `"^0.2.0"`). Breaking changes will happen as we build out multi-protocol support and discover patterns across services. Semver will be respected once we hit 1.0.
+
+## Build & Test
+
+```bash
+pnpm build      # tsup
+pnpm test       # vitest
+pnpm typecheck  # tsc --noEmit
+pnpm check      # format + lint + typecheck + build + test
+```
+
+## 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.
+
+**Convention:** Every doc has a `Status` header. When you resolve work described in a doc, update its Status to `Resolved in vX.Y.Z` and update INDEX.md.

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

@@ -0,0 +1,533 @@
+---
+name: router-guide
+description: Use when creating, modifying, or debugging routes with @agentcash/router. Covers route creation, auth modes, pricing, provider monitoring, discovery, plugins, and troubleshooting. Trigger phrases include "add a route", "create an endpoint", "set up discovery", "add provider monitoring", "configure the router".
+---
+
+# @agentcash/router Guide
+
+You are helping a developer build API routes using `@agentcash/router`. This package is a fluent route builder for Next.js App Router that handles x402 payments, MPP payments, SIWX authentication, API key auth, and provider monitoring.
+
+## Philosophy and Design Constraints
+
+These are intentional decisions. Do not change them without explicit user approval.
+
+### Why this exists
+
+Every paid API route in a Merit Systems service shared the same ~80-150 lines of boilerplate: x402 server init, payment verification, body parsing, settlement gating, error handling, observability hooks. Five services meant five copies that drifted. This router eliminates that by encoding the lifecycle into a fluent builder that compiles to a single Next.js handler function.
+
+### Core design principles
+
+1. **Fluent builder, not config object.** Progressive discoverability via IDE autocomplete. The chain reads like a sentence: `route('search').paid('0.01').body(schema).handler(fn)`. Config objects hide available options; fluent chains surface them.
+
+2. **Use `x402ResourceServer` primitives directly, not `withX402`.** The `withX402` wrapper from `@coinbase/x402` is a convenience that owns the full request lifecycle. We need to interleave body parsing, Zod validation, plugin hooks, and settlement gating at specific points in that lifecycle, so we call the lower-level primitives (`buildPaymentRequirementsFromOptions`, `verifyPayment`, `settlePayment`) directly.
+
+3. **Auth modes are mutually exclusive per route, except `apiKey` + `paid`.** A route is either paid, SIWX-authenticated, API-key-gated, or unprotected. The one exception: `.apiKey()` can compose with `.paid()` because some routes need both identity (API key) and payment (x402/MPP). This is enforced at the type level.
+
+4. **Body is only buffered when `.body()` is chained.** If a route doesn't declare a body schema, the request stream is untouched. This matters for routes that proxy multipart uploads or streams. For dynamic pricing, the body IS parsed before the 402 challenge (via `request.clone()`) so the pricing function can calculate an accurate price.
+
+5. **Settlement is gated on `response.status < 400`.** If the handler throws or returns an error response, no settlement occurs. The payer's funds are not captured. This is a fundamental safety guarantee.
+
+6. **The plugin interface is the observability boundary.** All Merit-specific telemetry (ClickHouse, Discord alerts, usage tracking) lives in a private `RouterPlugin` implementation. The router itself is fully open-source with zero Merit-specific code. The plugin hooks are fire-and-forget — they never delay the response.
+
+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 `mpay` primitives (`Challenge`, `Credential`, `tempo.charge`) — not the high-level `Mpay.create()` wrapper — because the router owns orchestration.
+
+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.
+
+10. **Fakes over mocks in tests.** The test suite uses `FakeX402Server` (a behavioral fake that accepts known payer/payee/amount tuples) instead of vi.mock stubs. This tests real verification logic, not mock wiring.
+
+### Version Stability
+
+The public API is **not stable**. Downstream consumers should pin exact versions (`"@agentcash/router": "0.2.0"`, not `"^0.2.0"`). Breaking changes will happen as we build out multi-protocol support and discover patterns across services. Semver will be respected once we hit 1.0.
+
+### Non-goals (deliberately rejected)
+
+- **No middleware chain.** Express-style middleware (`use()`) was considered and rejected. The builder's fixed lifecycle (auth → parse → validate → price → verify → handler → settle) covers all routes. Custom logic goes in the handler or plugin.
+- **No per-request config overrides.** The route is fully configured at definition time. Runtime behavior changes go through the handler function, not builder reconfiguration.
+- **No automatic retry on settlement failure.** Settlement failures are logged as critical alerts. Retry logic belongs in the plugin implementation, not the router core.
+
+## Architecture Overview
+
+```
+createRouter(config) → ServiceRouter
+  ├── .route(key) → RouteBuilder (fluent chain)
+  │     ├── Auth:  .paid() | .siwx() | .apiKey() | .unprotected()
+  │     ├── Schema: .body(zod) | .query(zod) | .output(zod)
+  │     ├── Meta:  .description() | .path() | .provider()
+  │     └── Terminal: .handler(fn) → Next.js handler
+  ├── .wellKnown() → /.well-known/x402 handler
+  ├── .openapi()   → /openapi.json handler
+  └── .monitors()  → MonitorEntry[] (for cron)
+```
+
+### Request lifecycle (orchestrate.ts)
+
+```
+Request in
+  → await x402 server init
+  → plugin.onRequest() → PluginContext
+  → if unprotected: skip to handler
+  → if apiKey route: verify API key → 401 if invalid
+  → detectProtocol(request) from headers
+  → if no payment header + dynamic pricing + body schema:
+      early body parse via request.clone() for accurate 402 price
+  → if SIWX: challenge or verify → handleAuth
+  → if no auth header: build 402 challenge
+      (x402: PAYMENT-REQUIRED header, MPP: WWW-Authenticate header)
+  → bufferBody + validateBody (only if .body() chained)
+  → resolvePrice (static / dynamic / tiered)
+  → protocol verify (x402 or MPP)
+  → plugin.onPaymentVerified()
+  → handler(ctx) → result
+  → if status < 400: settle payment (x402) or receipt (MPP)
+  → if provider configured: fireProviderQuota()
+  → plugin.onResponse()
+Response out
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | `createRouter()`, `ServiceRouter`, re-exports |
+| `src/builder.ts` | `RouteBuilder` fluent API with type-level state tracking |
+| `src/orchestrate.ts` | Core request lifecycle, `createRequestHandler()` |
+| `src/types.ts` | `HttpError`, `HandlerContext`, pricing/provider/auth types |
+| `src/plugin.ts` | `RouterPlugin` interface, `consolePlugin()`, `firePluginHook()` |
+| `src/pricing.ts` | `resolvePrice()`, `resolveMaxPrice()` |
+| `src/handler.ts` | `safeCallHandler()` error boundary |
+| `src/body.ts` | `bufferBody()`, `validateBody()` |
+| `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 mpay 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 |
+| `src/auth/nonce.ts` | `NonceStore` interface + `MemoryNonceStore` |
+| `src/discovery/well-known.ts` | `.well-known/x402` generation |
+| `src/discovery/openapi.ts` | OpenAPI 3.1 spec generation |
+
+## Environment Setup
+
+**CRITICAL:** The router uses the default facilitator from `@coinbase/x402`, which requires CDP API keys at runtime:
+
+```bash
+CDP_API_KEY_ID=your-key-id
+CDP_API_KEY_SECRET=your-key-secret
+```
+
+**For Next.js apps with env validation (T3 stack, `@t3-oss/env-nextjs`):** These must be declared in your env schema. Next.js does not expose undeclared env vars to `process.env`.
+
+Without these keys, x402 server initialization fails:
+- Error: `"Failed to fetch supported kinds from facilitator: TypeError: fetch failed"`
+- Or: `"Facilitator getSupported failed (401): Unauthorized"`
+- Symptom: All paid routes return empty 402 responses (no `PAYMENT-REQUIRED` header)
+
+**Example env schema (T3):**
+
+```typescript
+// src/env.js
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    CDP_API_KEY_ID: z.string(),
+    CDP_API_KEY_SECRET: z.string(),
+    // ... other vars
+  },
+  runtimeEnv: {
+    CDP_API_KEY_ID: process.env.CDP_API_KEY_ID,
+    CDP_API_KEY_SECRET: process.env.CDP_API_KEY_SECRET,
+    // ... other vars
+  },
+});
+```
+
+**Why this matters:** The default facilitator reads `process.env.CDP_API_KEY_ID` and `process.env.CDP_API_KEY_SECRET` when creating auth headers for the CDP facilitator API. If they're not in `process.env`, authentication fails silently — the facilitator sends requests without `Authorization` headers, and CDP returns 401.
+
+### MPP environment
+
+For MPP (Micropayment Protocol via Tempo blockchain), you need:
+
+```bash
+MPP_SECRET_KEY=your-hmac-secret       # HMAC key for challenge binding
+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:** `mpay` is an optional peer dep. When installed, it brings `viem` as a transitive dependency. Both are required for MPP support.
+
+## Creating Routes
+
+### Step 1: Router setup (once per service)
+
+```typescript
+// lib/routes.ts
+import { createRouter } from '@agentcash/router';
+
+export const router = createRouter({
+  payeeAddress: process.env.X402_PAYEE_ADDRESS!,
+  // Optional:
+  network: 'eip155:8453',            // default
+  protocols: ['x402', 'mpp'],        // protocols for auto-priced routes (default: ['x402'])
+  plugin: myPlugin,                   // observability
+  prices: { 'search': '0.02' },      // central pricing map
+  mpp: {                              // MPP support (requires mpay peer dep)
+    secretKey: process.env.MPP_SECRET_KEY!,
+    currency: '0x20c0000000000000000000000000000000000000', // PathUSD on Tempo
+    recipient: process.env.X402_PAYEE_ADDRESS!,
+    rpcUrl: process.env.TEMPO_RPC_URL,  // falls back to TEMPO_RPC_URL env var
+  },
+  siwx: { nonceStore },              // custom nonce store
+});
+```
+
+**Router-level `protocols`:** Sets default protocols for routes using the `prices` map (auto-priced routes). Routes using `.paid()` directly can override with `{ protocols: [...] }`.
+
+### Step 2: Define route files
+
+Each route file exports a Next.js handler (`GET`, `POST`, etc.):
+
+```typescript
+// app/api/search/route.ts
+import { router } from '@/lib/routes';
+import { searchSchema, searchResponseSchema } from '@/lib/schemas';
+
+export const POST = router.route('search')
+  .paid('0.01')
+  .body(searchSchema)
+  .output(searchResponseSchema)
+  .description('Search the web')
+  .handler(async ({ body }) => searchService(body));
+```
+
+### Step 3: Barrel import
+
+```typescript
+// lib/routes/barrel.ts
+import '@/app/api/search/route';
+import '@/app/api/lookup/route';
+// ... all route files
+```
+
+The barrel ensures all routes are registered before discovery endpoints generate their output.
+
+## Auth Modes
+
+### Paid (x402) — static price
+```typescript
+router.route('search').paid('0.01').body(schema).handler(fn);
+```
+
+### Paid (dynamic pricing)
+```typescript
+router.route('gen')
+  .paid((body) => calculateCost(body), { maxPrice: '5.00' })
+  .body(schema)
+  .handler(fn);
+```
+**How it works:** When a request arrives without a payment header, the router clones the request (`request.clone()`), parses the body early, and calls the pricing function to calculate an accurate price for the 402 challenge. This means clients see the real price, not a ceiling.
+
+`maxPrice` is **optional** and acts as a safety net:
+- **Cap:** If the pricing function returns a value above `maxPrice`, the price is capped and a warning is fired via the plugin.
+- **Fallback:** If the pricing function throws, `maxPrice` is used as a degraded-mode fallback. Without `maxPrice`, the route returns 500.
+- If omitted and the pricing function succeeds, the exact calculated price is used.
+
+### Paid (tiered) — requires body
+```typescript
+router.route('upload').paid({
+  field: 'tier',
+  tiers: {
+    '10mb': { price: '0.02', label: '10 MB' },
+    '100mb': { price: '0.20', label: '100 MB' },
+  },
+}).body(schema).handler(fn);
+```
+The tier value comes from `body[field]`. The 402 challenge uses the highest tier price.
+
+### Dual protocol (x402 + MPP)
+```typescript
+router.route('search')
+  .paid('0.01', { protocols: ['x402', 'mpp'] })
+  .body(schema).handler(fn);
+```
+
+### SIWX (wallet auth, no payment)
+```typescript
+router.route('inbox/status')
+  .siwx()
+  .query(querySchema)
+  .handler(async ({ query, wallet }) => getStatus(query, wallet));
+```
+
+### API key (composable with paid)
+```typescript
+router.route('admin/lookup')
+  .apiKey((key) => key === 'valid' ? { id: 'acct-1' } : null)
+  .paid('0.05')
+  .body(schema)
+  .handler(async ({ body, account }) => lookup(body, account));
+```
+API key is checked first (401 on failure), then payment flow runs.
+
+### Unprotected
+```typescript
+router.route('health').unprotected().handler(async () => ({ status: 'ok' }));
+```
+
+## Handler Context
+
+Every handler receives:
+
+```typescript
+interface HandlerContext<TBody, TQuery> {
+  body: TBody;              // Parsed + validated (undefined if no .body())
+  query: TQuery;            // Parsed + validated (undefined if no .query())
+  request: NextRequest;     // Raw request
+  requestId: string;        // Unique per-request UUID (for logging/tracing)
+  route: string;            // Route key (e.g. 'search', 'lookup/org')
+  wallet: string | null;    // Verified wallet (from payment or SIWX)
+  account: unknown;         // From .apiKey() resolver
+  alert: AlertFn;           // Fire observability alerts
+  setVerifiedWallet: (addr: string) => void;
+}
+```
+
+## Provider Monitoring
+
+Routes that wrap third-party APIs can declare monitoring behavior per-provider. This surfaces quota/balance information through the plugin system.
+
+### The six provider patterns
+
+| Pattern | How handled |
+|---------|-------------|
+| Balance in response headers | `extractQuota` reads `headers` |
+| Balance in response body | `extractQuota` reads `result` |
+| Separate health-check endpoint | `monitor` function (for cron) |
+| Overages at same rate | `overage: 'same-rate'` |
+| Overages at increased rate | `overage: 'increased-rate'` |
+| No overages, hard stop | `overage: 'hard-stop'` |
+
+### Usage
+
+```typescript
+export const POST = router.route('exa/search')
+  .paid('0.01')
+  .provider('exa', {
+    extractQuota: (result, headers) => ({
+      remaining: (result as any).rateLimit?.remaining ?? null,
+      limit: (result as any).rateLimit?.limit ?? null,
+    }),
+    monitor: async () => {
+      const res = await fetch('https://api.exa.ai/usage');
+      const data = await res.json();
+      return { remaining: data.credits, limit: data.limit };
+    },
+    overage: 'same-rate',
+    warn: 100,
+    critical: 10,
+  })
+  .body(searchSchema)
+  .handler(async ({ body }) => exaClient.search(body));
+```
+
+### ProviderConfig fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `extractQuota` | `(result, headers) => QuotaInfo \| null` | — | Inline extraction after each success |
+| `monitor` | `() => Promise<QuotaInfo \| null>` | — | Standalone check for cron |
+| `overage` | `'same-rate' \| 'increased-rate' \| 'hard-stop'` | `'same-rate'` | What happens at zero |
+| `warn` | `number` | — | Warn level threshold |
+| `critical` | `number` | — | Critical level threshold |
+
+### Threshold logic
+
+- `remaining === null` → `healthy` (no data)
+- `remaining <= critical` → `critical`
+- `remaining <= warn` → `warn`
+- Otherwise → `healthy`
+
+### Cron monitors
+
+```typescript
+for (const entry of router.monitors()) {
+  const quota = await entry.monitor();
+  // entry: { provider, route, monitor, overage, warn, critical }
+}
+```
+
+### Safety guarantees
+
+- `extractQuota` is fire-and-forget — exceptions never affect the response
+- Only runs when `response.status < 400`
+- Plugin hook (`onProviderQuota`) is non-blocking
+
+## Discovery Setup
+
+```typescript
+// app/.well-known/x402/route.ts
+import '@/lib/routes/barrel';  // barrel import FIRST to register all routes
+import { router } from '@/lib/routes';
+export const GET = router.wellKnown();
+
+// app/openapi.json/route.ts
+import '@/lib/routes/barrel';
+import { router } from '@/lib/routes';
+export const GET = router.openapi({ title: 'My API', version: '1.0.0' });
+```
+
+**Barrel import must come first.** Without it, Next.js lazy-loads route modules, so discovery endpoints hit before routes register → `route 'X' in prices map but not registered` error.
+
+**`.well-known/x402` output** includes `mppResources` alongside `resources` when MPP routes exist:
+```json
+{ "version": 1, "resources": ["..."], "mppResources": ["..."] }
+```
+
+**OpenAPI spec** includes `x-payment-info` with `price` and `protocols` per operation.
+
+## Plugin (Observability)
+
+```typescript
+const myPlugin: RouterPlugin = {
+  onRequest(meta) { /* return PluginContext */ },
+  onPaymentVerified(ctx, payment) { /* log payment */ },
+  onPaymentSettled(ctx, settlement) { /* log tx */ },
+  onResponse(ctx, response) { /* log response */ },
+  onError(ctx, error) { /* alert on errors */ },
+  onAlert(ctx, alert) { /* handle custom alerts */ },
+  onProviderQuota(ctx, event) { /* handle quota events */ },
+};
+```
+
+All hooks are optional. All are fire-and-forget. Use `consolePlugin()` for dev logging.
+
+## Builder Compile-Time Safety
+
+The type system (generic parameters `HasAuth`, `NeedsBody`, `HasBody`) prevents invalid chains:
+
+- `.handler()` requires auth to be set first
+- Dynamic/tiered pricing requires `.body()` before `.handler()`
+- `.siwx()` is mutually exclusive with `.paid()`
+- `.apiKey()` CAN compose with `.paid()`
+
+## MPP Internals (Critical Pitfalls)
+
+The router uses mpay's **low-level primitives**, not the high-level `Mpay.create()` API. This matters because mpay's internals have subtle conventions:
+
+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.
+
+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.
+
+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`.
+
+4. **`getClient` must be synchronous.** mpay's `Client.getResolver()` checks `if (getClient) return getClient` — it does NOT await. An async `getClient` will silently fall through to the default RPC URL.
+
+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.
+
+6. **viem is loaded eagerly in `ensureMpay()`.** Since `getClient` must be synchronous, viem's `createClient` and `http` are loaded once when mpay initializes, not per-call. viem is a transitive dep of mpay and is always available when mpay is installed.
+
+## Registration-Time Validation
+
+These throw immediately when the route is defined (not at request time):
+
+- Empty tier key in tiered pricing
+- `maxPrice` that isn't a positive decimal
+
+**Duplicate route keys** do NOT throw — the registry silently overwrites with a dev-only `console.warn`. This is intentional: Next.js `next build` loads modules non-deterministically, so discovery stubs and real handlers may register the same key in either order. Last writer wins. Prior art: ElysiaJS uses the identical pattern.
+
+## Central Pricing Map
+
+```typescript
+const router = createRouter({
+  payeeAddress: '...',
+  protocols: ['x402', 'mpp'],                    // default protocols for all auto-priced routes
+  prices: { 'search': '0.02', 'lookup': '0.05' },
+  mpp: { secretKey, currency, recipient, rpcUrl },
+});
+
+// .paid() is auto-applied with router-level protocols:
+export const POST = router.route('search').body(schema).handler(fn);
+```
+
+Routes using `prices` inherit the router-level `protocols` config. Routes using `.paid()` directly can override per-route with `{ protocols: [...] }`.
+
+Barrel validation catches mismatches: keys in `prices` but not registered → error.
+
+## Common Patterns
+
+### Return an error from handler
+```typescript
+.handler(async ({ body }) => {
+  if (!valid(body)) throw new HttpError('Invalid input', 400);
+  return result;
+});
+```
+
+### Return a raw Response (streaming)
+```typescript
+.handler(async ({ body }) => {
+  return new Response(streamData, {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+});
+```
+
+### Fire a custom alert
+```typescript
+.handler(async ({ body, alert }) => {
+  const result = await callProvider(body);
+  if (result.slow) alert('warn', 'Slow response', { latency: result.latency });
+  return result;
+});
+```
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `route 'X' registered twice` warning | Discovery stub + real handler both register same key | Expected during `next build` — last writer wins. Use `registry.has()` guards on stubs to suppress. |
+| `x402 server not initialized` | Missing peer deps | Install `@x402/core @x402/evm @x402/extensions @coinbase/x402` |
+| 402 on every request | No payment header | Client must send `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP) |
+| Body undefined in handler | No `.body()` chained | Add `.body(schema)` to the chain |
+| 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 |
+| `mpay package is required` | mpay not installed | `pnpm add mpay` — it's an optional peer dep |
+
+## Maintaining This Skill
+
+This skill file is the canonical reference for `@agentcash/router`. It ships with the repo at `.claude/skills/router-guide/SKILL.md` so that any agent working with the router has accurate, up-to-date guidance.
+
+**When you modify the router, update this skill.** Specifically:
+
+- **New interfaces or types** — Add them to the relevant section (Handler Context, Plugin, Provider Monitoring, etc.)
+- **New builder methods** — Document in the Auth Modes or Common Patterns sections
+- **New plugin hooks** — Add to the Plugin section
+- **Changed behavior** — Update the Request Lifecycle diagram and any affected sections
+- **New troubleshooting entries** — Add to the Troubleshooting table
+- **New design constraints or non-goals** — Add to the Philosophy section
+
+The goal is that any future agent can read this single file and implement correctly without needing to reverse-engineer the source. Keep it accurate, keep it concise.
+
+## Porting Services to the Router
+
+When porting an existing service to `@agentcash/router`, the service's route patterns may not cleanly map to the router's abstractions. **If you encounter a pattern that the router doesn't support, do not work around it silently.** Instead:
+
+1. **Inform the user** — explain what the service does, what the router expects, and where the mismatch is.
+2. **Suggest a router PR** — if the gap is a reasonable feature (not a one-off hack), propose adding it to the router. Describe the change, which files it touches, and why it's general-purpose.
+3. **Let the user decide** — they may prefer a workaround, a router change, or restructuring the service.
+
+Common conformance gaps to watch for:
+- Handler that needs raw request body (not JSON) — router buffers as JSON when `.body()` is chained. Consider if the route should skip `.body()` and parse from `ctx.request` directly.
+- Multiple pricing strategies on one route — router supports static, dynamic, or tiered, but only one per route.
+- Auth mode that doesn't fit the 4 modes — router enforces paid/siwx/apiKey/unprotected. Composite auth beyond apiKey+paid is not supported.
+- Custom response headers set by middleware — router owns the response lifecycle. Headers go in the handler return or via the plugin.

package/dist/index.cjs

@@ -120,7 +120,7 @@ var RouteRegistry = class {
 };
 
 // src/orchestrate.ts
-var import_server2 = require("next/server");
+var import_server3 = require("next/server");
 
 // src/plugin.ts
 function createDefaultContext(meta) {
@@ -354,70 +354,110 @@ async function settleX402Payment(server, payload, requirements) {
 }
 
 // src/protocols/mpp.ts
-var mpayLoaded = false;
-var Challenge;
-var Credential;
-var Receipt;
-var tempo;
-async function ensureMpay() {
-  if (mpayLoaded) return;
-  try {
-    const mpay = await import("mpay");
-    Challenge = mpay.Challenge;
-    Credential = mpay.Credential;
-    Receipt = mpay.Receipt;
-    const mpayServer = await import("mpay/server");
-    tempo = mpayServer.tempo;
-    mpayLoaded = true;
-  } catch {
-    throw new Error("mpay package is required for MPP protocol support. Install it: pnpm add mpay");
+var import_mpay = require("mpay");
+var import_server2 = require("mpay/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) {
-  await ensureMpay();
-  const methodIntent = tempo.charge({
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
+  const standardRequest = toStandardRequest(request);
+  const currency = mppConfig.currency;
+  const recipient = mppConfig.recipient ?? "";
+  const methodIntent = import_server2.tempo.charge({
+    currency,
+    recipient
   });
-  const challenge = Challenge.fromIntent(methodIntent, {
+  const challenge = import_mpay.Challenge.fromIntent(methodIntent, {
     secretKey: mppConfig.secretKey,
-    realm: new URL(request.url).origin,
-    request
+    realm: new URL(standardRequest.url).origin,
+    request: {
+      amount: price,
+      currency,
+      recipient,
+      decimals: DEFAULT_DECIMALS
+    }
   });
-  return Challenge.serialize(challenge);
+  return import_mpay.Challenge.serialize(challenge);
 }
 async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
-  await ensureMpay();
-  const credential = Credential.fromRequest(request);
-  if (!credential) return null;
-  const isValid = Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
-  if (!isValid) {
-    return { valid: false, payer: null };
-  }
-  const chargeConfig = {
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
-  };
-  const verifyResult = await tempo.charge(chargeConfig).verify(credential);
-  if (!verifyResult?.valid) {
-    return { valid: false, payer: null };
+  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_mpay.Credential.fromRequest(standardRequest);
+    if (!credential?.challenge) {
+      console.error("[MPP] Invalid credential structure");
+      return null;
+    }
+    const isValid = import_mpay.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({
+      currency,
+      recipient,
+      ...buildGetClient(mppConfig.rpcUrl)
+    });
+    const paymentRequest = {
+      amount: price,
+      currency,
+      recipient,
+      decimals: DEFAULT_DECIMALS
+    };
+    const resolvedRequest = methodIntent.request ? await methodIntent.request({ credential, request: paymentRequest }) : paymentRequest;
+    const receipt = await methodIntent.verify({
+      credential,
+      request: resolvedRequest
+    });
+    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;
   }
-  return {
-    valid: true,
-    payer: verifyResult.payer
-  };
 }
-async function buildMPPReceipt(reference) {
-  await ensureMpay();
-  const receipt = Receipt.from({
+function buildMPPReceipt(reference) {
+  const receipt = import_mpay.Receipt.from({
     method: "tempo",
     status: "success",
     reference,
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
-  return Receipt.serialize(receipt);
+  return import_mpay.Receipt.serialize(receipt);
 }
 
 // src/auth/siwx.ts
@@ -495,7 +535,7 @@ function createRequestHandler(routeEntry, handler, deps) {
     firePluginResponse(deps, pluginCtx, meta, response);
   }
   function fail(status, message, meta, pluginCtx) {
-    const response = import_server2.NextResponse.json({ success: false, error: message }, { status });
+    const response = import_server3.NextResponse.json({ success: false, error: message }, { status });
     firePluginResponse(deps, pluginCtx, meta, response);
     return response;
   }
@@ -595,7 +635,7 @@ function createRequestHandler(routeEntry, handler, deps) {
             route: routeEntry.key
           });
         }
-        const response = new import_server2.NextResponse(JSON.stringify(paymentRequired), {
+        const response = new import_server3.NextResponse(JSON.stringify(paymentRequired), {
           status: 402,
           headers: { "Content-Type": "application/json" }
         });
@@ -727,7 +767,7 @@ async function parseBody(request, routeEntry) {
   if (result.success) return { ok: true, data: result.data };
   return {
     ok: false,
-    response: import_server2.NextResponse.json(
+    response: import_server3.NextResponse.json(
       { success: false, error: result.error, issues: result.issues },
       { status: 400 }
     )
@@ -786,7 +826,7 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
       });
       return { price: routeEntry.maxPrice };
     } else {
-      const errorResponse = import_server2.NextResponse.json(
+      const errorResponse = import_server3.NextResponse.json(
         { success: false, error: "Price calculation failed" },
         { status: 500 }
       );
@@ -796,7 +836,12 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
   }
 }
 async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
-  const response = new import_server2.NextResponse(null, { status: 402 });
+  const response = new import_server3.NextResponse(null, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json"
+    }
+  });
   let challengePrice;
   if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
     const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);
@@ -1087,7 +1132,7 @@ var MemoryNonceStore = class {
 };
 
 // src/discovery/well-known.ts
-var import_server3 = require("next/server");
+var import_server4 = require("next/server");
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
   let validated = false;
   return async (_request) => {
@@ -1125,7 +1170,7 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (instructions) {
       body.instructions = instructions;
     }
-    return import_server3.NextResponse.json(body, {
+    return import_server4.NextResponse.json(body, {
       headers: {
         "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET",
@@ -1136,12 +1181,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
 }
 
 // src/discovery/openapi.ts
-var import_server4 = require("next/server");
+var import_server5 = require("next/server");
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
   let cached = null;
   let validated = false;
   return async (_request) => {
-    if (cached) return import_server4.NextResponse.json(cached);
+    if (cached) return import_server5.NextResponse.json(cached);
     if (!validated && pricesKeys) {
       registry.validate(pricesKeys);
       validated = true;
@@ -1168,7 +1213,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       paths
     });
-    return import_server4.NextResponse.json(cached);
+    return import_server5.NextResponse.json(cached);
   };
 }
 function deriveTag(routeKey) {

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
@@ -82,6 +83,7 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+
 interface X402Server {
     initialize(): Promise<void>;
     buildPaymentRequirementsFromOptions(options: Array<{
@@ -91,18 +93,18 @@ interface X402Server {
         payTo: string;
     }>, context: {
         request: Request;
-    }): Promise<unknown[]>;
-    createPaymentRequiredResponse(requirements: unknown[], resource: {
+    }): Promise<PaymentRequirements[]>;
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], resource: {
         url: string;
         method: string;
         description?: string;
-    }, error: string | null, extensions?: Record<string, unknown>): Promise<unknown>;
-    findMatchingRequirements(requirements: unknown[], payload: unknown): unknown;
-    verifyPayment(payload: unknown, requirements: unknown): Promise<{
+    }, error: string | null, extensions?: Record<string, unknown>): Promise<PaymentRequired>;
+    findMatchingRequirements(requirements: PaymentRequirements[], payload: unknown): PaymentRequirements;
+    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<{
         isValid: boolean;
         payer?: string;
     }>;
-    settlePayment(payload: unknown, requirements: unknown): Promise<unknown>;
+    settlePayment(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
@@ -183,6 +185,8 @@ interface RouterConfig {
         secretKey: string;
         currency: string;
         recipient?: string;
+        /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
+        rpcUrl?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).
@@ -239,6 +243,7 @@ interface OrchestrateDeps {
         secretKey: string;
         currency: string;
         recipient?: string;
+        rpcUrl?: string;
     };
 }
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
@@ -82,6 +83,7 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+
 interface X402Server {
     initialize(): Promise<void>;
     buildPaymentRequirementsFromOptions(options: Array<{
@@ -91,18 +93,18 @@ interface X402Server {
         payTo: string;
     }>, context: {
         request: Request;
-    }): Promise<unknown[]>;
-    createPaymentRequiredResponse(requirements: unknown[], resource: {
+    }): Promise<PaymentRequirements[]>;
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], resource: {
         url: string;
         method: string;
         description?: string;
-    }, error: string | null, extensions?: Record<string, unknown>): Promise<unknown>;
-    findMatchingRequirements(requirements: unknown[], payload: unknown): unknown;
-    verifyPayment(payload: unknown, requirements: unknown): Promise<{
+    }, error: string | null, extensions?: Record<string, unknown>): Promise<PaymentRequired>;
+    findMatchingRequirements(requirements: PaymentRequirements[], payload: unknown): PaymentRequirements;
+    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<{
         isValid: boolean;
         payer?: string;
     }>;
-    settlePayment(payload: unknown, requirements: unknown): Promise<unknown>;
+    settlePayment(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
@@ -183,6 +185,8 @@ interface RouterConfig {
         secretKey: string;
         currency: string;
         recipient?: string;
+        /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
+        rpcUrl?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).
@@ -239,6 +243,7 @@ interface OrchestrateDeps {
         secretKey: string;
         currency: string;
         recipient?: string;
+        rpcUrl?: string;
     };
 }
 

package/dist/index.js

@@ -320,63 +320,103 @@ async function settleX402Payment(server, payload, requirements) {
 }
 
 // src/protocols/mpp.ts
-var mpayLoaded = false;
-var Challenge;
-var Credential;
-var Receipt;
-var tempo;
-async function ensureMpay() {
-  if (mpayLoaded) return;
-  try {
-    const mpay = await import("mpay");
-    Challenge = mpay.Challenge;
-    Credential = mpay.Credential;
-    Receipt = mpay.Receipt;
-    const mpayServer = await import("mpay/server");
-    tempo = mpayServer.tempo;
-    mpayLoaded = true;
-  } catch {
-    throw new Error("mpay package is required for MPP protocol support. Install it: pnpm add mpay");
+import { Challenge, Credential, Receipt } from "mpay";
+import { tempo } from "mpay/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) {
-  await ensureMpay();
+  const standardRequest = toStandardRequest(request);
+  const currency = mppConfig.currency;
+  const recipient = mppConfig.recipient ?? "";
   const methodIntent = tempo.charge({
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
+    currency,
+    recipient
   });
   const challenge = Challenge.fromIntent(methodIntent, {
     secretKey: mppConfig.secretKey,
-    realm: new URL(request.url).origin,
-    request
+    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) {
-  await ensureMpay();
-  const credential = Credential.fromRequest(request);
-  if (!credential) return null;
-  const isValid = Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
-  if (!isValid) {
-    return { valid: false, payer: null };
-  }
-  const chargeConfig = {
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
-  };
-  const verifyResult = await tempo.charge(chargeConfig).verify(credential);
-  if (!verifyResult?.valid) {
-    return { valid: false, payer: null };
+  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({
+      currency,
+      recipient,
+      ...buildGetClient(mppConfig.rpcUrl)
+    });
+    const paymentRequest = {
+      amount: price,
+      currency,
+      recipient,
+      decimals: DEFAULT_DECIMALS
+    };
+    const resolvedRequest = methodIntent.request ? await methodIntent.request({ credential, request: paymentRequest }) : paymentRequest;
+    const receipt = await methodIntent.verify({
+      credential,
+      request: resolvedRequest
+    });
+    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;
   }
-  return {
-    valid: true,
-    payer: verifyResult.payer
-  };
 }
-async function buildMPPReceipt(reference) {
-  await ensureMpay();
+function buildMPPReceipt(reference) {
   const receipt = Receipt.from({
     method: "tempo",
     status: "success",
@@ -762,7 +802,12 @@ async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta)
   }
 }
 async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
-  const response = new NextResponse2(null, { status: 402 });
+  const response = new NextResponse2(null, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json"
+    }
+  });
   let challengePrice;
   if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
     const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -19,8 +19,21 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    ".claude/CLAUDE.md",
+    ".claude/skills"
   ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
+    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm build && pnpm test"
+  },
   "peerDependencies": {
     "@coinbase/x402": "^2.1.0",
     "@x402/core": "^2.3.0",
@@ -31,11 +44,6 @@
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
   },
-  "peerDependenciesMeta": {
-    "mpay": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@coinbase/x402": "^2.1.0",
     "@eslint/js": "^10.0.1",
@@ -51,24 +59,15 @@
     "tsup": "^8.0.0",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.55.0",
+    "viem": "^2.0.0",
     "vitest": "^3.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
   },
+  "packageManager": "pnpm@10.28.0",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/merit-systems/agentcash-router.git"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
-    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm build && pnpm test"
   }
-}
+}