@agentcash/router 1.10.6 → 1.11.0

package/AGENTS.md

@@ -39,6 +39,8 @@ src/
 
 `auth check -> body parse -> validate -> 402 challenge -> payment verify -> handler -> settle -> finalize`
 
+Paid `.paid()` routes may set `mpp: { settleBeforeHandler: true }` (or chain `.mpp({ settleBeforeHandler: true })` on auto-priced routes) to broadcast MPP transaction (pull) credentials at verify instead of after the handler. x402 on the same route is unaffected. MPP hash (push) credentials already settle at verify. Use `.settlement({ onSettledHandlerError })` when eager MPP settle can charge before an upstream failure.
+
 ## Naming
 
 Constructor-style functions use `build<Noun>` — one verb, one domain noun. Name them after the domain concept, never after an HTTP status code or transport detail (the function that builds a payment challenge is `buildChallengeResponse`, not `build402`). The challenge family shares the `Challenge` backbone: `buildChallengeResponse`, `buildChallengeExtensions`, `buildSiwxChallenge`, `buildSessionChallenge`, `buildX402Challenge`.

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
+  });
+}
+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;
 }
-function invokeUnauthed(ctx, wallet, account, body) {
-  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+
+// 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,
@@ -1709,7 +1784,8 @@ var mppStrategy = {
       return verifySessionMode(args, info);
     }
     if (info.sessionAction) return { ok: false, kind: "invalid" };
-    if (info.payloadType === "transaction" && args.deps.tempoClient) {
+    const deferTransactionSettlement = info.payloadType === "transaction" && args.deps.tempoClient && !args.routeEntry.mppInfo?.settleBeforeHandler;
+    if (deferTransactionSettlement) {
       return verifyTxMode(args, info);
     }
     return verifyHashMode(args, info);
@@ -2012,7 +2088,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 +2114,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 } : {},
@@ -2611,6 +2687,7 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  await attachAgentIdentityChallenge(response, ctx.request, ctx.deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -2745,7 +2822,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,
@@ -2753,12 +2830,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);
 }
@@ -2782,12 +2868,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 {
@@ -2846,12 +2941,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;
@@ -3384,6 +3481,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) {
@@ -3510,6 +3646,7 @@ async function buildSiwxChallenge(ctx) {
     } catch {
     }
   }
+  await attachAgentIdentityChallenge(response, request, deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3720,7 +3857,9 @@ var RouteBuilder = class _RouteBuilder {
     if (maxPrice) next.#s.maxPrice = maxPrice;
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
-    if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.mpp) {
+      next.#s.mppInfo = { ...next.#s.mppInfo, ...resolvedOptions.mpp };
+    }
     if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
     if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
@@ -4015,6 +4154,24 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.validateFn = fn;
     return next;
   }
+  /**
+   * Override MPP protocol metadata and per-route MPP settlement options.
+   * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+   * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+   *
+   * @example
+   * ```ts
+   * router.route('exa/answer')
+   *   .mpp({ settleBeforeHandler: true })
+   *   .body(schema)
+   *   .handler(handler);
+   * ```
+   */
+  mpp(info) {
+    const next = this.fork();
+    next.#s.mppInfo = { ...this.#s.mppInfo, ...info };
+    return next;
+  }
   /**
    * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
    * succeeds but before on-chain settlement and can cancel the charge;
@@ -4030,7 +4187,7 @@ var RouteBuilder = class _RouteBuilder {
    */
   settlement(lifecycle) {
     const next = this.fork();
-    next.#s.settlement = lifecycle;
+    next.#s.settlement = { ...this.#s.settlement, ...lifecycle };
     return next;
   }
   /**
@@ -4086,6 +4243,21 @@ var RouteBuilder = class _RouteBuilder {
     if (this.#s.settlement && !this.#s.pricing) {
       throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
     }
+    if (this.#s.mppInfo?.settleBeforeHandler) {
+      if (!this.#s.pricing) {
+        throw new Error(`route '${this.#s.key}': mpp.settleBeforeHandler requires a paid route`);
+      }
+      if (this.#s.billing !== "exact") {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is only supported on .paid() routes`
+        );
+      }
+      if (this.#s.settlement?.beforeSettle) {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
+        );
+      }
+    }
     if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {
@@ -4526,7 +4698,7 @@ function createNotFoundHandler(baseUrl) {
       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"
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X, X-Agent-Identity"
       }
     }
   );
@@ -5140,6 +5312,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);
@@ -5174,6 +5347,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    agentIdentityNonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
     mppRecipient: config.mpp?.recipient ?? config.payeeAddress,

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;
@@ -218,6 +221,7 @@ interface MppProtocolInfo {
     method?: string;
     intent?: string;
     currency?: string;
+    settleBeforeHandler?: boolean;
 }
 type CheckoutSessionResponse = Record<string, unknown>;
 interface CheckoutSessionContext<TBody = unknown> {
@@ -320,6 +324,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;
@@ -498,6 +504,7 @@ interface RouterDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    agentIdentityNonceStore: NonceStoreInterface;
     entitlementStore: EntitlementStore;
     payeeAddress: string;
     mppRecipient?: string;
@@ -576,8 +583,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
      * 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()`.
+     * `checkoutSession`) live alongside the pricing shape. Set `mpp.settleBeforeHandler`
+     * on slow upstream routes so MPP transaction (pull) credentials broadcast at verify.
+     * For auto-priced routes from `RouterConfig.prices`, chain `.mpp({ settleBeforeHandler: true })`.
      *
      * @example
      * ```ts
@@ -773,6 +781,20 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * ```
      */
     validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    /**
+     * Override MPP protocol metadata and per-route MPP settlement options.
+     * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+     * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+     *
+     * @example
+     * ```ts
+     * router.route('exa/answer')
+     *   .mpp({ settleBeforeHandler: true })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
+    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -947,4 +969,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 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 };
+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 MppProtocolInfo, 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;
@@ -218,6 +221,7 @@ interface MppProtocolInfo {
     method?: string;
     intent?: string;
     currency?: string;
+    settleBeforeHandler?: boolean;
 }
 type CheckoutSessionResponse = Record<string, unknown>;
 interface CheckoutSessionContext<TBody = unknown> {
@@ -320,6 +324,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;
@@ -498,6 +504,7 @@ interface RouterDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    agentIdentityNonceStore: NonceStoreInterface;
     entitlementStore: EntitlementStore;
     payeeAddress: string;
     mppRecipient?: string;
@@ -576,8 +583,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
      * 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()`.
+     * `checkoutSession`) live alongside the pricing shape. Set `mpp.settleBeforeHandler`
+     * on slow upstream routes so MPP transaction (pull) credentials broadcast at verify.
+     * For auto-priced routes from `RouterConfig.prices`, chain `.mpp({ settleBeforeHandler: true })`.
      *
      * @example
      * ```ts
@@ -773,6 +781,20 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * ```
      */
     validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    /**
+     * Override MPP protocol metadata and per-route MPP settlement options.
+     * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+     * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+     *
+     * @example
+     * ```ts
+     * router.route('exa/answer')
+     *   .mpp({ settleBeforeHandler: true })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
+    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -947,4 +969,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 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 };
+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 MppProtocolInfo, 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
+  });
+}
+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;
 }
-function invokeUnauthed(ctx, wallet, account, body) {
-  const base = buildHandlerCtx(ctx, wallet, account, body, null);
+
+// 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,
@@ -1667,7 +1746,8 @@ var mppStrategy = {
       return verifySessionMode(args, info);
     }
     if (info.sessionAction) return { ok: false, kind: "invalid" };
-    if (info.payloadType === "transaction" && args.deps.tempoClient) {
+    const deferTransactionSettlement = info.payloadType === "transaction" && args.deps.tempoClient && !args.routeEntry.mppInfo?.settleBeforeHandler;
+    if (deferTransactionSettlement) {
       return verifyTxMode(args, info);
     }
     return verifyHashMode(args, info);
@@ -2569,6 +2649,7 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  await attachAgentIdentityChallenge(response, ctx.request, ctx.deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -2703,7 +2784,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,
@@ -2711,12 +2792,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);
 }
@@ -2740,12 +2830,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 {
@@ -2804,12 +2903,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;
@@ -3342,6 +3443,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) {
@@ -3468,6 +3608,7 @@ async function buildSiwxChallenge(ctx) {
     } catch {
     }
   }
+  await attachAgentIdentityChallenge(response, request, deps.agentIdentityNonceStore);
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3678,7 +3819,9 @@ var RouteBuilder = class _RouteBuilder {
     if (maxPrice) next.#s.maxPrice = maxPrice;
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
-    if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.mpp) {
+      next.#s.mppInfo = { ...next.#s.mppInfo, ...resolvedOptions.mpp };
+    }
     if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
     if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
@@ -3973,6 +4116,24 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.validateFn = fn;
     return next;
   }
+  /**
+   * Override MPP protocol metadata and per-route MPP settlement options.
+   * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+   * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+   *
+   * @example
+   * ```ts
+   * router.route('exa/answer')
+   *   .mpp({ settleBeforeHandler: true })
+   *   .body(schema)
+   *   .handler(handler);
+   * ```
+   */
+  mpp(info) {
+    const next = this.fork();
+    next.#s.mppInfo = { ...this.#s.mppInfo, ...info };
+    return next;
+  }
   /**
    * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
    * succeeds but before on-chain settlement and can cancel the charge;
@@ -3988,7 +4149,7 @@ var RouteBuilder = class _RouteBuilder {
    */
   settlement(lifecycle) {
     const next = this.fork();
-    next.#s.settlement = lifecycle;
+    next.#s.settlement = { ...this.#s.settlement, ...lifecycle };
     return next;
   }
   /**
@@ -4044,6 +4205,21 @@ var RouteBuilder = class _RouteBuilder {
     if (this.#s.settlement && !this.#s.pricing) {
       throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
     }
+    if (this.#s.mppInfo?.settleBeforeHandler) {
+      if (!this.#s.pricing) {
+        throw new Error(`route '${this.#s.key}': mpp.settleBeforeHandler requires a paid route`);
+      }
+      if (this.#s.billing !== "exact") {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is only supported on .paid() routes`
+        );
+      }
+      if (this.#s.settlement?.beforeSettle) {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
+        );
+      }
+    }
     if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {
@@ -4484,7 +4660,7 @@ function createNotFoundHandler(baseUrl) {
       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"
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X, X-Agent-Identity"
       }
     }
   );
@@ -5098,6 +5274,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);
@@ -5132,6 +5309,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    agentIdentityNonceStore,
     entitlementStore,
     payeeAddress: config.payeeAddress ?? "",
     mppRecipient: config.mpp?.recipient ?? config.payeeAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.10.6",
+  "version": "1.11.0",
   "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"