@agentcash/router 1.10.5 → 1.10.7

package/README.md

@@ -150,6 +150,21 @@ The barrel forces every route module to load before the discovery handler walks
 
 The `openapi.json` should be hosted at `GET <origin>/openapi.json`. 
 
+### 4. Unmatched route fallback
+
+```typescript
+// app/api/[[...path]]/route.ts
+import { router } from '@/lib/router';
+
+export const GET = router.notFound();
+export const POST = router.notFound();
+export const DELETE = router.notFound();
+export const PUT = router.notFound();
+export const PATCH = router.notFound();
+```
+
+This catches stale agent calls to API paths that no longer exist and returns a JSON 404 telling the client to rediscover the origin.
+
 ## Auth modes
 
 | Method | Purpose |

package/dist/index.cjs

@@ -542,7 +542,8 @@ var HEADERS = {
   X402_PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
   X402_PAYMENT_RESPONSE: "PAYMENT-RESPONSE",
   MPP_PAYMENT_RECEIPT: "Payment-Receipt",
-  REQUEST_ID: "X-Request-ID"
+  REQUEST_ID: "X-Request-ID",
+  AGENT_IDENTITY: "X-Agent-Identity"
 };
 var AUTH_SCHEME = {
   BEARER: "Bearer ",
@@ -677,6 +678,7 @@ function firePaymentSettled(ctx, event) {
 }
 function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
   attachRequestId(response, ctx.meta.requestId);
+  const error = response.status >= 400 && response.status !== 402 ? buildErrorEvent(ctx, response, failure) : void 0;
   firePluginHook(ctx.deps.plugin, "onResponse", ctx.pluginCtx, {
     statusCode: response.status,
     statusText: response.statusText,
@@ -684,10 +686,10 @@ function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
     contentType: response.headers.get("content-type"),
     headers: Object.fromEntries(response.headers.entries()),
     requestBody,
-    responseBody
+    responseBody,
+    error
   });
-  if (response.status >= 400 && response.status !== 402) {
-    const error = buildErrorEvent(ctx, response, failure);
+  if (error) {
     if (response.status >= 500) logRouterFailure(error);
     firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, error);
   }
@@ -860,6 +862,9 @@ async function runValidate(ctx, body) {
 // src/pipeline/flows/static/static-invoke.ts
 var import_server4 = require("next/server");
 
+// src/auth/agent-identity.ts
+var import_did_auth_challenge = require("did-auth-challenge");
+
 // src/types.ts
 var HttpError = class extends Error {
   constructor(message, status) {
@@ -869,18 +874,87 @@ var HttpError = class extends Error {
   }
 };
 
-// src/pipeline/flows/static/static-invoke.ts
-function invokePaidStatic(ctx, wallet, account, body, payment) {
-  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment));
+// src/auth/agent-identity.ts
+var PROTOCOL_VERSION = 1;
+function base64urlEncode(value) {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function base64urlDecode(value) {
+  return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+}
+function challengeBindings(request) {
+  const url = new URL(request.url);
+  return { domain: url.hostname, route: url.pathname };
+}
+async function buildAgentIdentityChallengeHeader(request, nonceStore) {
+  const bindings = challengeBindings(request);
+  const challenge = await (0, import_did_auth_challenge.createChallenge)(bindings, { nonceStore });
+  return base64urlEncode({
+    v: PROTOCOL_VERSION,
+    challenge
+  });
 }
-function invokeUnauthed(ctx, wallet, account, body) {
-  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+async function attachAgentIdentityChallenge(response, request, nonceStore) {
+  response.headers.set(
+    HEADERS.AGENT_IDENTITY,
+    await buildAgentIdentityChallengeHeader(request, nonceStore)
+  );
+}
+async function resolveActor(request, nonceStore) {
+  const header = request.headers.get(HEADERS.AGENT_IDENTITY);
+  if (!header) return null;
+  let envelope;
+  try {
+    envelope = base64urlDecode(header);
+  } catch {
+    throw new HttpError("Malformed X-Agent-Identity header", 401);
+  }
+  if (envelope.v !== PROTOCOL_VERSION || !envelope.challenge || !envelope.did || !envelope.signature) {
+    throw new HttpError("Invalid X-Agent-Identity proof", 401);
+  }
+  const bindings = challengeBindings(request);
+  try {
+    await (0, import_did_auth_challenge.verifySignature)({
+      did: envelope.did,
+      authenticationKey: envelope.authenticationKey,
+      challenge: envelope.challenge,
+      signature: envelope.signature,
+      options: {
+        nonceStore,
+        expected: bindings
+      }
+    });
+  } catch (err) {
+    const message = (0, import_did_auth_challenge.isIdentityError)(err) ? err.code : "Invalid agent identity";
+    throw new HttpError(message, 401);
+  }
+  return envelope.did;
+}
+
+// src/pipeline/flows/static/static-invoke.ts
+async function invokePaidStatic(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorForHandler(ctx);
+  if (actorResult.kind === "error") return actorResult.result;
+  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment, actorResult.actor));
+}
+async function invokeUnauthed(ctx, wallet, account, body) {
+  const actorResult = await resolveActorForHandler(ctx);
+  if (actorResult.kind === "error") return actorResult.result;
+  const base = buildHandlerCtx(ctx, wallet, account, body, null, actorResult.actor);
   if (ctx.routeEntry.billing !== "upto") return runHandler(ctx, base);
   const uptoCtx = { ...base, charge: async () => {
   } };
   return runHandler(ctx, uptoCtx);
 }
-function buildHandlerCtx(ctx, wallet, account, body, payment) {
+async function resolveActorForHandler(ctx) {
+  try {
+    const actor = await resolveActor(ctx.request, ctx.deps.agentIdentityNonceStore);
+    return { kind: "ok", actor };
+  } catch (error) {
+    return { kind: "error", result: errorResult(error) };
+  }
+}
+function buildHandlerCtx(ctx, wallet, account, body, payment, actor) {
   return {
     body,
     query: ctx.query,
@@ -888,6 +962,7 @@ function buildHandlerCtx(ctx, wallet, account, body, payment) {
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
     wallet,
+    actor,
     payment,
     account,
     alert: ctx.report,
@@ -1207,7 +1282,7 @@ async function trySiwxFastPath(ctx, account) {
 function shouldParseBodyEarly(incomingStrategy, routeEntry, pricing) {
   if (incomingStrategy) return false;
   if (!routeEntry.bodySchema) return false;
-  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn;
+  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn || !!routeEntry.checkoutSession;
 }
 
 // src/pipeline/steps/resolve-early-body.ts
@@ -2012,7 +2087,7 @@ function tagBareDecimalAsDollars(amount) {
 }
 
 // src/protocols/x402/verify.ts
-var import_types2 = require("@x402/core/types");
+var import_types3 = require("@x402/core/types");
 async function verifyX402Payment(opts) {
   const { server, request, price, accepts, report } = opts;
   const payment = await readPaymentPayload(request);
@@ -2038,7 +2113,7 @@ async function verifyX402Payment(opts) {
   try {
     verify = await server.verifyPayment(payload, matching);
   } catch (err) {
-    if (err instanceof import_types2.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
+    if (err instanceof import_types3.VerifyError && err.statusCode >= 400 && err.statusCode < 500) {
       return invalidPaymentVerification({
         reason: err.invalidReason ?? "verify_error",
         ...err.invalidMessage ? { message: err.invalidMessage } : {},
@@ -2549,30 +2624,37 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
-  const responseBody = failure ? JSON.stringify({ error: failure.message ?? null, reason: failure.reason }) : null;
-  const response = new import_server5.NextResponse(responseBody, {
-    status: 402,
-    headers: {
-      "Content-Type": "application/json",
-      "Cache-Control": "no-store"
-    }
-  });
-  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+  let checkoutSession;
+  if (ctx.routeEntry.checkoutSession) {
     try {
-      const contribution = await strategy.buildChallenge({
+      checkoutSession = await ctx.routeEntry.checkoutSession({
         request: ctx.request,
-        routeEntry: ctx.routeEntry,
+        route: ctx.routeEntry.key,
         body,
-        price: challengePrice,
-        extensions,
-        deps: ctx.deps,
-        report: ctx.report
+        price: challengePrice
       });
-      if (contribution.headers) {
-        for (const [name, value] of Object.entries(contribution.headers)) {
-          response.headers.set(name, value);
-        }
-      }
+    } catch (err) {
+      const message = errorMessage(err, "Checkout session build failed");
+      const responseBody2 = { success: false, error: message };
+      const errorResponse = import_server5.NextResponse.json(responseBody2, { status: errorStatus(err, 500) });
+      firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
+      return errorResponse;
+    }
+  }
+  const contributions = [];
+  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+    try {
+      contributions.push(
+        await strategy.buildChallenge({
+          request: ctx.request,
+          routeEntry: ctx.routeEntry,
+          body,
+          price: challengePrice,
+          extensions,
+          deps: ctx.deps,
+          report: ctx.report
+        })
+      );
     } catch (err) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
@@ -2584,6 +2666,27 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  const responsePayload = {
+    ...Object.assign({}, ...contributions.map((contribution) => contribution.body ?? {})),
+    ...failure && { error: failure.message ?? null, reason: failure.reason },
+    ...checkoutSession && { checkout_session: checkoutSession }
+  };
+  const responseBody = Object.keys(responsePayload).length ? JSON.stringify(responsePayload) : null;
+  const response = new import_server5.NextResponse(responseBody, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    }
+  });
+  for (const contribution of contributions) {
+    if (contribution.headers) {
+      for (const [name, value] of Object.entries(contribution.headers)) {
+        response.headers.set(name, value);
+      }
+    }
+  }
+  await attachAgentIdentityChallenge(response, ctx.request, ctx.deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -2718,7 +2821,7 @@ function createChargeContext(args) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/shared.ts
 var import_server7 = require("next/server");
-function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
+function buildBaseHandlerCtx(ctx, wallet, account, body, payment, actor = null) {
   return {
     body,
     query: ctx.query,
@@ -2726,12 +2829,21 @@ function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
     wallet,
+    actor,
     payment,
     account,
     alert: ctx.report,
     setVerifiedWallet: (addr) => ctx.pluginCtx.setVerifiedWallet(addr)
   };
 }
+async function resolveActorOrError(ctx) {
+  try {
+    const actor = await resolveActor(ctx.request, ctx.deps.agentIdentityNonceStore);
+    return { actor };
+  } catch (error) {
+    return errorResult2(error);
+  }
+}
 function toResponse(rawResult) {
   return rawResult instanceof Response ? rawResult : import_server7.NextResponse.json(rawResult);
 }
@@ -2755,12 +2867,21 @@ function isThenable2(value) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/metered-invoke.ts
 async function invokeMetered(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorOrError(ctx);
+  if ("response" in actorResult) return actorResult;
   const chargeContext = ctx.routeEntry.streaming ? createChargeContext({
     tickCost: ctx.routeEntry.tickCost,
     maxPrice: ctx.routeEntry.maxPrice,
     route: ctx.routeEntry.key
   }) : null;
-  const baseHandlerCtx = buildBaseHandlerCtx(ctx, wallet, account, body, payment);
+  const baseHandlerCtx = buildBaseHandlerCtx(
+    ctx,
+    wallet,
+    account,
+    body,
+    payment,
+    actorResult.actor
+  );
   const handlerCtx = chargeContext !== null ? { ...baseHandlerCtx, charge: chargeContext.charge } : baseHandlerCtx;
   let returned;
   try {
@@ -2819,12 +2940,14 @@ function createUptoChargeContext(args) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/upto-invoke.ts
 async function invokeUpto(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorOrError(ctx);
+  if ("response" in actorResult) return actorResult;
   const uptoCtx = createUptoChargeContext({
     maxPrice: ctx.routeEntry.maxPrice,
     route: ctx.routeEntry.key
   });
   const handlerCtx = {
-    ...buildBaseHandlerCtx(ctx, wallet, account, body, payment),
+    ...buildBaseHandlerCtx(ctx, wallet, account, body, payment, actorResult.actor),
     charge: uptoCtx.charge
   };
   let returned;
@@ -3357,6 +3480,45 @@ async function createKvMppStore(kv, options) {
   });
 }
 
+// src/kv-store/agent-identity-nonce.ts
+var import_did_auth_challenge2 = require("did-auth-challenge");
+function createKvAgentIdentityNonceStore(kv, options) {
+  const prefix = options?.prefix ?? "actor:nonce:";
+  return {
+    async add(nonce, expiresAt, challengeJson) {
+      const ttl = Math.max(1, Math.ceil((expiresAt.getTime() - Date.now()) / 1e3));
+      const record = { challengeJson, expiresAt: expiresAt.getTime() };
+      await kv.setNxEx(`${prefix}${nonce}`, record, ttl);
+    },
+    async get(nonce) {
+      const raw = await kv.get(`${prefix}${nonce}`);
+      if (!raw) return null;
+      const record = raw;
+      if (Date.now() > record.expiresAt) {
+        await kv.del(`${prefix}${nonce}`);
+        return null;
+      }
+      return record;
+    },
+    async has(nonce) {
+      return await this.get(nonce) !== null;
+    },
+    async consume(nonce) {
+      return kv.update(`${prefix}${nonce}`, (current) => {
+        if (!current) return { op: "noop", result: null };
+        const record = current;
+        if (Date.now() > record.expiresAt) {
+          return { op: "delete", result: null };
+        }
+        return { op: "delete", result: record };
+      });
+    }
+  };
+}
+function createAgentIdentityNonceStore(kv) {
+  return kv ? createKvAgentIdentityNonceStore(kv) : new import_did_auth_challenge2.NonceStore();
+}
+
 // src/protocols/mpp/siwx-mode.ts
 var import_mppx3 = require("mppx");
 async function verifyMppSiwx(request, mppx) {
@@ -3483,6 +3645,7 @@ async function buildSiwxChallenge(ctx) {
     } catch {
     }
   }
+  await attachAgentIdentityChallenge(response, request, deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3602,7 +3765,8 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: void 0,
       settlement: void 0,
       mppInfo: void 0,
-      hasCheckout: false
+      hasCheckout: false,
+      checkoutSession: void 0
     };
   }
   fork() {
@@ -3693,7 +3857,8 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
-    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4128,6 +4293,7 @@ var RouteBuilder = class _RouteBuilder {
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
       hasCheckout: this.#s.hasCheckout ? true : void 0,
+      checkoutSession: this.#s.checkoutSession,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4475,6 +4641,33 @@ function createLlmsTxtHandler(discovery) {
   };
 }
 
+// src/discovery/not-found.ts
+var import_server12 = require("next/server");
+function createNotFoundHandler(baseUrl) {
+  const normalizedBase = baseUrl.replace(/\/+$/, "");
+  return async (request) => import_server12.NextResponse.json(
+    {
+      success: false,
+      code: "route_not_found",
+      error: "Route not found. Rediscover this origin and retry with the current discovery document.",
+      requestedUrl: request.url,
+      discovery: {
+        openapi: `${normalizedBase}/openapi.json`,
+        wellKnown: `${normalizedBase}/.well-known/x402`,
+        llmsTxt: `${normalizedBase}/llms.txt`
+      }
+    },
+    {
+      status: 404,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, DELETE, PUT, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X, X-Agent-Identity"
+      }
+    }
+  );
+}
+
 // src/index.ts
 init_accepts();
 init_constants();
@@ -5083,6 +5276,7 @@ function createRouter(config) {
   const registry = new RouteRegistry();
   const kvStore = resolveKvStore(config.kvStore);
   const nonceStore = kvStore ? createKvNonceStore(kvStore) : new MemoryNonceStore();
+  const agentIdentityNonceStore = createAgentIdentityNonceStore(kvStore);
   const entitlementStore = kvStore ? createKvEntitlementStore(kvStore) : new MemoryEntitlementStore();
   const network = config.network ?? BASE_MAINNET_NETWORK;
   const x402Accepts = getConfiguredX402Accepts(config);
@@ -5117,6 +5311,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    agentIdentityNonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
     mppRecipient: config.mpp?.recipient ?? config.payeeAddress,
@@ -5178,6 +5373,9 @@ function createRouter(config) {
     llmsTxt() {
       return createLlmsTxtHandler(config.discovery);
     },
+    notFound() {
+      return createNotFoundHandler(resolvedBaseUrl);
+    },
     monitors() {
       const result = [];
       for (const [, entry] of registry.entries()) {

package/dist/index.d.cts

@@ -4,6 +4,7 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, VerifyResponse, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 import { Transport } from 'mppx/server';
+import { NonceStoreInterface } from 'did-auth-challenge';
 
 interface KvStore {
     get(key: string): Promise<unknown>;
@@ -79,6 +80,8 @@ interface ResponseMeta {
     requestBody?: unknown;
     /** Handler return value or structured router-generated error body. */
     responseBody?: unknown;
+    /** Rich error details for non-402 failure responses. */
+    error?: ErrorEvent;
 }
 interface ErrorEvent {
     status: number;
@@ -219,6 +222,15 @@ interface MppProtocolInfo {
     intent?: string;
     currency?: string;
 }
+type CheckoutSessionResponse = Record<string, unknown>;
+interface CheckoutSessionContext<TBody = unknown> {
+    request: NextRequest;
+    route: string;
+    body: TBody | undefined;
+    /** Decimal-dollar price quoted for this 402 challenge. */
+    price: string;
+}
+type CheckoutSessionFn<TBody = unknown> = (ctx: CheckoutSessionContext<TBody>) => CheckoutSessionResponse | null | undefined | Promise<CheckoutSessionResponse | null | undefined>;
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
@@ -229,6 +241,14 @@ interface PaidOptions {
     mpp?: MppProtocolInfo;
     /** Signal in discovery that clients should use an explicit checkout flow before payment. */
     checkout?: boolean;
+    /**
+     * Build dynamic checkout review metadata for the router-owned 402 response body.
+     *
+     * The returned object is emitted as `{ "checkout_session": ... }` on the unpaid
+     * payment challenge response. Payment terms remain authoritative in the x402/MPP
+     * challenge headers.
+     */
+    checkoutSession?: CheckoutSessionFn;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -303,6 +323,8 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     requestId: string;
     route: string;
     wallet: string | null;
+    /** Optional DID from `X-Agent-Identity` proof. Null when the client omits identity. */
+    actor: string | null;
     payment: HandlerPaymentContext | null;
     account: unknown;
     alert: AlertFn;
@@ -374,6 +396,7 @@ interface RouteEntry {
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
     hasCheckout?: boolean;
+    checkoutSession?: CheckoutSessionFn;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -480,6 +503,7 @@ interface RouterDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    agentIdentityNonceStore: NonceStoreInterface;
     entitlementStore: EntitlementStore;
     payeeAddress: string;
     mppRecipient?: string;
@@ -557,8 +581,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
-     * alongside the pricing shape. For handler-computed billing use `.upTo()`;
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
+     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *
      * @example
@@ -900,6 +924,7 @@ interface ServiceRouter<TPriceKeys extends string = never> {
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
+    notFound(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -928,4 +953,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, VerifyResponse, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 import { Transport } from 'mppx/server';
+import { NonceStoreInterface } from 'did-auth-challenge';
 
 interface KvStore {
     get(key: string): Promise<unknown>;
@@ -79,6 +80,8 @@ interface ResponseMeta {
     requestBody?: unknown;
     /** Handler return value or structured router-generated error body. */
     responseBody?: unknown;
+    /** Rich error details for non-402 failure responses. */
+    error?: ErrorEvent;
 }
 interface ErrorEvent {
     status: number;
@@ -219,6 +222,15 @@ interface MppProtocolInfo {
     intent?: string;
     currency?: string;
 }
+type CheckoutSessionResponse = Record<string, unknown>;
+interface CheckoutSessionContext<TBody = unknown> {
+    request: NextRequest;
+    route: string;
+    body: TBody | undefined;
+    /** Decimal-dollar price quoted for this 402 challenge. */
+    price: string;
+}
+type CheckoutSessionFn<TBody = unknown> = (ctx: CheckoutSessionContext<TBody>) => CheckoutSessionResponse | null | undefined | Promise<CheckoutSessionResponse | null | undefined>;
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
@@ -229,6 +241,14 @@ interface PaidOptions {
     mpp?: MppProtocolInfo;
     /** Signal in discovery that clients should use an explicit checkout flow before payment. */
     checkout?: boolean;
+    /**
+     * Build dynamic checkout review metadata for the router-owned 402 response body.
+     *
+     * The returned object is emitted as `{ "checkout_session": ... }` on the unpaid
+     * payment challenge response. Payment terms remain authoritative in the x402/MPP
+     * challenge headers.
+     */
+    checkoutSession?: CheckoutSessionFn;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -303,6 +323,8 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     requestId: string;
     route: string;
     wallet: string | null;
+    /** Optional DID from `X-Agent-Identity` proof. Null when the client omits identity. */
+    actor: string | null;
     payment: HandlerPaymentContext | null;
     account: unknown;
     alert: AlertFn;
@@ -374,6 +396,7 @@ interface RouteEntry {
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
     hasCheckout?: boolean;
+    checkoutSession?: CheckoutSessionFn;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -480,6 +503,7 @@ interface RouterDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    agentIdentityNonceStore: NonceStoreInterface;
     entitlementStore: EntitlementStore;
     payeeAddress: string;
     mppRecipient?: string;
@@ -557,8 +581,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
-     * alongside the pricing shape. For handler-computed billing use `.upTo()`;
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
+     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *
      * @example
@@ -900,6 +924,7 @@ interface ServiceRouter<TPriceKeys extends string = never> {
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
+    notFound(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -928,4 +953,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.js

@@ -500,7 +500,8 @@ var HEADERS = {
   X402_PAYMENT_REQUIRED: "PAYMENT-REQUIRED",
   X402_PAYMENT_RESPONSE: "PAYMENT-RESPONSE",
   MPP_PAYMENT_RECEIPT: "Payment-Receipt",
-  REQUEST_ID: "X-Request-ID"
+  REQUEST_ID: "X-Request-ID",
+  AGENT_IDENTITY: "X-Agent-Identity"
 };
 var AUTH_SCHEME = {
   BEARER: "Bearer ",
@@ -635,6 +636,7 @@ function firePaymentSettled(ctx, event) {
 }
 function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
   attachRequestId(response, ctx.meta.requestId);
+  const error = response.status >= 400 && response.status !== 402 ? buildErrorEvent(ctx, response, failure) : void 0;
   firePluginHook(ctx.deps.plugin, "onResponse", ctx.pluginCtx, {
     statusCode: response.status,
     statusText: response.statusText,
@@ -642,10 +644,10 @@ function firePluginResponse(ctx, response, requestBody, responseBody, failure) {
     contentType: response.headers.get("content-type"),
     headers: Object.fromEntries(response.headers.entries()),
     requestBody,
-    responseBody
+    responseBody,
+    error
   });
-  if (response.status >= 400 && response.status !== 402) {
-    const error = buildErrorEvent(ctx, response, failure);
+  if (error) {
     if (response.status >= 500) logRouterFailure(error);
     firePluginHook(ctx.deps.plugin, "onError", ctx.pluginCtx, error);
   }
@@ -818,6 +820,13 @@ async function runValidate(ctx, body) {
 // src/pipeline/flows/static/static-invoke.ts
 import { NextResponse as NextResponse4 } from "next/server";
 
+// src/auth/agent-identity.ts
+import {
+  createChallenge,
+  isIdentityError,
+  verifySignature
+} from "did-auth-challenge";
+
 // src/types.ts
 var HttpError = class extends Error {
   constructor(message, status) {
@@ -827,18 +836,87 @@ var HttpError = class extends Error {
   }
 };
 
-// src/pipeline/flows/static/static-invoke.ts
-function invokePaidStatic(ctx, wallet, account, body, payment) {
-  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment));
+// src/auth/agent-identity.ts
+var PROTOCOL_VERSION = 1;
+function base64urlEncode(value) {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function base64urlDecode(value) {
+  return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+}
+function challengeBindings(request) {
+  const url = new URL(request.url);
+  return { domain: url.hostname, route: url.pathname };
+}
+async function buildAgentIdentityChallengeHeader(request, nonceStore) {
+  const bindings = challengeBindings(request);
+  const challenge = await createChallenge(bindings, { nonceStore });
+  return base64urlEncode({
+    v: PROTOCOL_VERSION,
+    challenge
+  });
 }
-function invokeUnauthed(ctx, wallet, account, body) {
-  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+async function attachAgentIdentityChallenge(response, request, nonceStore) {
+  response.headers.set(
+    HEADERS.AGENT_IDENTITY,
+    await buildAgentIdentityChallengeHeader(request, nonceStore)
+  );
+}
+async function resolveActor(request, nonceStore) {
+  const header = request.headers.get(HEADERS.AGENT_IDENTITY);
+  if (!header) return null;
+  let envelope;
+  try {
+    envelope = base64urlDecode(header);
+  } catch {
+    throw new HttpError("Malformed X-Agent-Identity header", 401);
+  }
+  if (envelope.v !== PROTOCOL_VERSION || !envelope.challenge || !envelope.did || !envelope.signature) {
+    throw new HttpError("Invalid X-Agent-Identity proof", 401);
+  }
+  const bindings = challengeBindings(request);
+  try {
+    await verifySignature({
+      did: envelope.did,
+      authenticationKey: envelope.authenticationKey,
+      challenge: envelope.challenge,
+      signature: envelope.signature,
+      options: {
+        nonceStore,
+        expected: bindings
+      }
+    });
+  } catch (err) {
+    const message = isIdentityError(err) ? err.code : "Invalid agent identity";
+    throw new HttpError(message, 401);
+  }
+  return envelope.did;
+}
+
+// src/pipeline/flows/static/static-invoke.ts
+async function invokePaidStatic(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorForHandler(ctx);
+  if (actorResult.kind === "error") return actorResult.result;
+  return runHandler(ctx, buildHandlerCtx(ctx, wallet, account, body, payment, actorResult.actor));
+}
+async function invokeUnauthed(ctx, wallet, account, body) {
+  const actorResult = await resolveActorForHandler(ctx);
+  if (actorResult.kind === "error") return actorResult.result;
+  const base = buildHandlerCtx(ctx, wallet, account, body, null, actorResult.actor);
   if (ctx.routeEntry.billing !== "upto") return runHandler(ctx, base);
   const uptoCtx = { ...base, charge: async () => {
   } };
   return runHandler(ctx, uptoCtx);
 }
-function buildHandlerCtx(ctx, wallet, account, body, payment) {
+async function resolveActorForHandler(ctx) {
+  try {
+    const actor = await resolveActor(ctx.request, ctx.deps.agentIdentityNonceStore);
+    return { kind: "ok", actor };
+  } catch (error) {
+    return { kind: "error", result: errorResult(error) };
+  }
+}
+function buildHandlerCtx(ctx, wallet, account, body, payment, actor) {
   return {
     body,
     query: ctx.query,
@@ -846,6 +924,7 @@ function buildHandlerCtx(ctx, wallet, account, body, payment) {
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
     wallet,
+    actor,
     payment,
     account,
     alert: ctx.report,
@@ -1165,7 +1244,7 @@ async function trySiwxFastPath(ctx, account) {
 function shouldParseBodyEarly(incomingStrategy, routeEntry, pricing) {
   if (incomingStrategy) return false;
   if (!routeEntry.bodySchema) return false;
-  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn;
+  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn || !!routeEntry.checkoutSession;
 }
 
 // src/pipeline/steps/resolve-early-body.ts
@@ -2507,30 +2586,37 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
-  const responseBody = failure ? JSON.stringify({ error: failure.message ?? null, reason: failure.reason }) : null;
-  const response = new NextResponse5(responseBody, {
-    status: 402,
-    headers: {
-      "Content-Type": "application/json",
-      "Cache-Control": "no-store"
-    }
-  });
-  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+  let checkoutSession;
+  if (ctx.routeEntry.checkoutSession) {
     try {
-      const contribution = await strategy.buildChallenge({
+      checkoutSession = await ctx.routeEntry.checkoutSession({
         request: ctx.request,
-        routeEntry: ctx.routeEntry,
+        route: ctx.routeEntry.key,
         body,
-        price: challengePrice,
-        extensions,
-        deps: ctx.deps,
-        report: ctx.report
+        price: challengePrice
       });
-      if (contribution.headers) {
-        for (const [name, value] of Object.entries(contribution.headers)) {
-          response.headers.set(name, value);
-        }
-      }
+    } catch (err) {
+      const message = errorMessage(err, "Checkout session build failed");
+      const responseBody2 = { success: false, error: message };
+      const errorResponse = NextResponse5.json(responseBody2, { status: errorStatus(err, 500) });
+      firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
+      return errorResponse;
+    }
+  }
+  const contributions = [];
+  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+    try {
+      contributions.push(
+        await strategy.buildChallenge({
+          request: ctx.request,
+          routeEntry: ctx.routeEntry,
+          body,
+          price: challengePrice,
+          extensions,
+          deps: ctx.deps,
+          report: ctx.report
+        })
+      );
     } catch (err) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
@@ -2542,6 +2628,27 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  const responsePayload = {
+    ...Object.assign({}, ...contributions.map((contribution) => contribution.body ?? {})),
+    ...failure && { error: failure.message ?? null, reason: failure.reason },
+    ...checkoutSession && { checkout_session: checkoutSession }
+  };
+  const responseBody = Object.keys(responsePayload).length ? JSON.stringify(responsePayload) : null;
+  const response = new NextResponse5(responseBody, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    }
+  });
+  for (const contribution of contributions) {
+    if (contribution.headers) {
+      for (const [name, value] of Object.entries(contribution.headers)) {
+        response.headers.set(name, value);
+      }
+    }
+  }
+  await attachAgentIdentityChallenge(response, ctx.request, ctx.deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -2676,7 +2783,7 @@ function createChargeContext(args) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/shared.ts
 import { NextResponse as NextResponse7 } from "next/server";
-function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
+function buildBaseHandlerCtx(ctx, wallet, account, body, payment, actor = null) {
   return {
     body,
     query: ctx.query,
@@ -2684,12 +2791,21 @@ function buildBaseHandlerCtx(ctx, wallet, account, body, payment) {
     requestId: ctx.meta.requestId,
     route: ctx.routeEntry.key,
     wallet,
+    actor,
     payment,
     account,
     alert: ctx.report,
     setVerifiedWallet: (addr) => ctx.pluginCtx.setVerifiedWallet(addr)
   };
 }
+async function resolveActorOrError(ctx) {
+  try {
+    const actor = await resolveActor(ctx.request, ctx.deps.agentIdentityNonceStore);
+    return { actor };
+  } catch (error) {
+    return errorResult2(error);
+  }
+}
 function toResponse(rawResult) {
   return rawResult instanceof Response ? rawResult : NextResponse7.json(rawResult);
 }
@@ -2713,12 +2829,21 @@ function isThenable2(value) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/metered-invoke.ts
 async function invokeMetered(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorOrError(ctx);
+  if ("response" in actorResult) return actorResult;
   const chargeContext = ctx.routeEntry.streaming ? createChargeContext({
     tickCost: ctx.routeEntry.tickCost,
     maxPrice: ctx.routeEntry.maxPrice,
     route: ctx.routeEntry.key
   }) : null;
-  const baseHandlerCtx = buildBaseHandlerCtx(ctx, wallet, account, body, payment);
+  const baseHandlerCtx = buildBaseHandlerCtx(
+    ctx,
+    wallet,
+    account,
+    body,
+    payment,
+    actorResult.actor
+  );
   const handlerCtx = chargeContext !== null ? { ...baseHandlerCtx, charge: chargeContext.charge } : baseHandlerCtx;
   let returned;
   try {
@@ -2777,12 +2902,14 @@ function createUptoChargeContext(args) {
 
 // src/pipeline/flows/dynamic/dynamic-invoke/upto-invoke.ts
 async function invokeUpto(ctx, wallet, account, body, payment) {
+  const actorResult = await resolveActorOrError(ctx);
+  if ("response" in actorResult) return actorResult;
   const uptoCtx = createUptoChargeContext({
     maxPrice: ctx.routeEntry.maxPrice,
     route: ctx.routeEntry.key
   });
   const handlerCtx = {
-    ...buildBaseHandlerCtx(ctx, wallet, account, body, payment),
+    ...buildBaseHandlerCtx(ctx, wallet, account, body, payment, actorResult.actor),
     charge: uptoCtx.charge
   };
   let returned;
@@ -3315,6 +3442,45 @@ async function createKvMppStore(kv, options) {
   });
 }
 
+// src/kv-store/agent-identity-nonce.ts
+import { NonceStore } from "did-auth-challenge";
+function createKvAgentIdentityNonceStore(kv, options) {
+  const prefix = options?.prefix ?? "actor:nonce:";
+  return {
+    async add(nonce, expiresAt, challengeJson) {
+      const ttl = Math.max(1, Math.ceil((expiresAt.getTime() - Date.now()) / 1e3));
+      const record = { challengeJson, expiresAt: expiresAt.getTime() };
+      await kv.setNxEx(`${prefix}${nonce}`, record, ttl);
+    },
+    async get(nonce) {
+      const raw = await kv.get(`${prefix}${nonce}`);
+      if (!raw) return null;
+      const record = raw;
+      if (Date.now() > record.expiresAt) {
+        await kv.del(`${prefix}${nonce}`);
+        return null;
+      }
+      return record;
+    },
+    async has(nonce) {
+      return await this.get(nonce) !== null;
+    },
+    async consume(nonce) {
+      return kv.update(`${prefix}${nonce}`, (current) => {
+        if (!current) return { op: "noop", result: null };
+        const record = current;
+        if (Date.now() > record.expiresAt) {
+          return { op: "delete", result: null };
+        }
+        return { op: "delete", result: record };
+      });
+    }
+  };
+}
+function createAgentIdentityNonceStore(kv) {
+  return kv ? createKvAgentIdentityNonceStore(kv) : new NonceStore();
+}
+
 // src/protocols/mpp/siwx-mode.ts
 import { Credential as Credential2 } from "mppx";
 async function verifyMppSiwx(request, mppx) {
@@ -3441,6 +3607,7 @@ async function buildSiwxChallenge(ctx) {
     } catch {
     }
   }
+  await attachAgentIdentityChallenge(response, request, deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3560,7 +3727,8 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: void 0,
       settlement: void 0,
       mppInfo: void 0,
-      hasCheckout: false
+      hasCheckout: false,
+      checkoutSession: void 0
     };
   }
   fork() {
@@ -3651,7 +3819,8 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
-    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4086,6 +4255,7 @@ var RouteBuilder = class _RouteBuilder {
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
       hasCheckout: this.#s.hasCheckout ? true : void 0,
+      checkoutSession: this.#s.checkoutSession,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4433,6 +4603,33 @@ function createLlmsTxtHandler(discovery) {
   };
 }
 
+// src/discovery/not-found.ts
+import { NextResponse as NextResponse12 } from "next/server";
+function createNotFoundHandler(baseUrl) {
+  const normalizedBase = baseUrl.replace(/\/+$/, "");
+  return async (request) => NextResponse12.json(
+    {
+      success: false,
+      code: "route_not_found",
+      error: "Route not found. Rediscover this origin and retry with the current discovery document.",
+      requestedUrl: request.url,
+      discovery: {
+        openapi: `${normalizedBase}/openapi.json`,
+        wellKnown: `${normalizedBase}/.well-known/x402`,
+        llmsTxt: `${normalizedBase}/llms.txt`
+      }
+    },
+    {
+      status: 404,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, DELETE, PUT, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X, X-Agent-Identity"
+      }
+    }
+  );
+}
+
 // src/index.ts
 init_accepts();
 init_constants();
@@ -5041,6 +5238,7 @@ function createRouter(config) {
   const registry = new RouteRegistry();
   const kvStore = resolveKvStore(config.kvStore);
   const nonceStore = kvStore ? createKvNonceStore(kvStore) : new MemoryNonceStore();
+  const agentIdentityNonceStore = createAgentIdentityNonceStore(kvStore);
   const entitlementStore = kvStore ? createKvEntitlementStore(kvStore) : new MemoryEntitlementStore();
   const network = config.network ?? BASE_MAINNET_NETWORK;
   const x402Accepts = getConfiguredX402Accepts(config);
@@ -5075,6 +5273,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    agentIdentityNonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
     mppRecipient: config.mpp?.recipient ?? config.payeeAddress,
@@ -5136,6 +5335,9 @@ function createRouter(config) {
     llmsTxt() {
       return createLlmsTxtHandler(config.discovery);
     },
+    notFound() {
+      return createNotFoundHandler(resolvedBaseUrl);
+    },
     monitors() {
       const result = [];
       for (const [, entry] of registry.entries()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.10.5",
+  "version": "1.10.7",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -32,6 +32,7 @@
     "@x402/evm": "^2.13.0",
     "@x402/extensions": "^2.13.0",
     "@x402/svm": "^2.13.0",
+    "did-auth-challenge": "^0.0.1",
     "mppx": "^0.6.16",
     "viem": "^2.47.6",
     "zod-openapi": "^5.0.0"