@absol-labs/agent 0.10.0 → 0.11.0

package/src/cli/spend-policy.ts

@@ -0,0 +1,139 @@
+import { formatUsdc } from "./amounts.js";
+import { CliError } from "./errors.js";
+import type { PrivySpendPolicy } from "./privy.js";
+import type { RequestedSpend } from "./mandate.js";
+import type { ServerMandateCaps } from "../mandates/env.js";
+
+/**
+ * Where a hire's spend ceiling comes from, and who enforces it.
+ *
+ * The CLI has two kinds of wallet, and they differ in WHO holds the key — which
+ * is the whole reason the self-signed spend mandate exists at all:
+ *
+ *  - **Key-holding wallet** (a raw private key, a CDP account). The person
+ *    typing the command holds the key, so nothing outside this process bounds
+ *    what that key can spend. `signCliMandate()` makes the agent state its own
+ *    ceiling, and `checkMandate()` enforces it here. That is the best available
+ *    guarantee when the client is the last line of defence.
+ *
+ *  - **Policy-enforced wallet** (Privy, either shape). The key lives at Privy
+ *    and is exercised by the broker, which caps every `openStream` against a
+ *    policy the client CANNOT reach or raise. Re-signing a local mandate on top
+ *    of that adds nothing: it is an agent attesting to its own limits when a
+ *    stronger limit is already enforced somewhere the agent cannot touch. Worse,
+ *    it cannot even be produced — the broker's typed-data policy allows an
+ *    `InvocationCapability` and nothing else — so insisting on it would block
+ *    the wallet whose ceiling is the stronger of the two.
+ *
+ * So for a policy-enforced wallet the CLI does not self-sign a mandate. It
+ * SUBSTITUTES the real ceiling rather than dropping the check: it reads the
+ * broker's public `/v1/config` and refuses an over-ceiling hire locally, in the
+ * same shape as the gas and USDC preflights — fail early with an actionable
+ * message instead of paying gas to learn a knowable fact.
+ *
+ * **Do not "restore" the mandate here for consistency.** Its premise is
+ * key-holding, and that premise is false for these wallets. Reinstating it
+ * would weaken the property that makes them non-custodial (the broker would
+ * have to be widened to sign `SpendMandate`) while making every fund-moving
+ * command fail against the broker as deployed.
+ */
+export interface SpendCeiling {
+  readonly policy: PrivySpendPolicy;
+}
+
+/**
+ * Refuse a hire the broker will refuse anyway, before any gas is spent.
+ *
+ * Mirrors the broker's own `openStream` check exactly — `deposit`,
+ * `ratePerSecond` and `duration` each against their ceiling — because a
+ * divergent copy would either block hires the broker would allow or promise
+ * hires it will not.
+ */
+export function assertWithinSpendPolicy(
+  policy: PrivySpendPolicy,
+  spend: RequestedSpend,
+): void {
+  const over: string[] = [];
+  if (spend.budgetUsdc > policy.maxTotalUsdc) {
+    over.push(
+      `--budget ${formatUsdc(spend.budgetUsdc)} exceeds the policy ceiling of ${formatUsdc(policy.maxTotalUsdc)}`,
+    );
+  }
+  if (spend.ratePerSecondUsdc > policy.maxRatePerSecondUsdc) {
+    over.push(
+      `--rate ${spend.ratePerSecondUsdc} atomic/second exceeds the policy ceiling of ${policy.maxRatePerSecondUsdc} atomic/second`,
+    );
+  }
+  if (spend.durationSeconds > policy.maxDurationSeconds) {
+    over.push(
+      `--duration ${spend.durationSeconds}s exceeds the policy ceiling of ${policy.maxDurationSeconds}s`,
+    );
+  }
+  if (over.length === 0) return;
+
+  throw new CliError(
+    `this hire is outside the spend policy your wallet is capped at: ${over.join("; ")}`,
+    {
+      exitCode: 3,
+      hint:
+        `the ceiling is enforced by the broker at ${policy.brokerUrl} (GET /v1/config), not by this CLI — you cannot raise it from this side, ` +
+        "which is exactly what makes the wallet non-custodial. Size the stream to fit, or use a key-holding wallet.",
+    },
+  );
+}
+
+/**
+ * Refuse a hire that exceeds an OPERATOR-SET standing ceiling.
+ *
+ * `METRIK_AGENT_MANDATE_*` is not the self-signed mandate: it is a ceiling the
+ * operator deliberately configured, and it can be TIGHTER than the broker
+ * policy. A policy-enforced wallet skips the self-signed mandate, so without
+ * this the env caps would silently stop applying to exactly the wallets an
+ * unattended run is most likely to use. Enforced locally here instead, with the
+ * same comparisons `checkMandate()` makes.
+ */
+export function assertWithinOperatorCaps(
+  caps: ServerMandateCaps,
+  spend: RequestedSpend,
+): void {
+  const over: string[] = [];
+  if (spend.budgetUsdc > caps.maxPerStreamUsdc) {
+    over.push(
+      `--budget ${formatUsdc(spend.budgetUsdc)} exceeds METRIK_AGENT_MANDATE max-per-stream ${formatUsdc(caps.maxPerStreamUsdc)}`,
+    );
+  }
+  if (spend.budgetUsdc > caps.maxTotalUsdc) {
+    over.push(
+      `--budget ${formatUsdc(spend.budgetUsdc)} exceeds METRIK_AGENT_MANDATE max-total ${formatUsdc(caps.maxTotalUsdc)}`,
+    );
+  }
+  if (spend.ratePerSecondUsdc > caps.maxRatePerSecondUsdc) {
+    over.push(
+      `--rate ${spend.ratePerSecondUsdc} atomic/second exceeds METRIK_AGENT_MANDATE max rate ${caps.maxRatePerSecondUsdc} atomic/second`,
+    );
+  }
+  if (spend.durationSeconds > caps.maxDurationSeconds) {
+    over.push(
+      `--duration ${spend.durationSeconds}s exceeds METRIK_AGENT_MANDATE max duration ${caps.maxDurationSeconds}s`,
+    );
+  }
+  if (
+    caps.allowedOperators.length > 0 &&
+    !caps.allowedOperators.some(
+      (operator) => operator.toLowerCase() === spend.operator.toLowerCase(),
+    )
+  ) {
+    over.push(
+      `operator ${spend.operator} is not in METRIK_AGENT_MANDATE_ALLOWED_OPERATORS`,
+    );
+  }
+  if (over.length === 0) return;
+
+  throw new CliError(
+    `this hire is outside the standing mandate caps in your environment: ${over.join("; ")}`,
+    {
+      exitCode: 3,
+      hint: "these caps come from METRIK_AGENT_MANDATE_* and are yours to change. They are enforced locally for a policy-enforced wallet, which signs no mandate of its own.",
+    },
+  );
+}

package/src/cli/wallet.ts

@@ -1,8 +1,17 @@
 import { privateKeyToAccount } from "viem/accounts";
-import type { Account, LocalAccount } from "viem";
+import type { Account, LocalAccount, Transport } from "viem";
 
+import type { AutonomousWalletCredentialStore } from "../wallet/autonomous-wallet.js";
 import { resolveAgentWallet } from "../wallet/provider.js";
 import { configError } from "./errors.js";
+import {
+  PRIVY_ENV_VARS,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+  resolvePrivyCliWallet,
+  type PrivyCliWalletSource,
+  type PrivySpendPolicy,
+} from "./privy.js";
 
 /**
  * The ONLY place the CLI resolves a signing wallet.
@@ -18,32 +27,33 @@ import { configError } from "./errors.js";
  *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
  *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
  *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
+ *     broker, either agent-owned (`METRIK_AGENT_PRIVY_WALLET_KEY`) or a
+ *     user-owned broker session. See `./privy.ts`.
  *
- * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
- * one environment configures every surface the same way. It is checked in a
- * FIXED order rather than "whichever is configured", because an environment
- * carrying both is ambiguous about which address funds the stream — and that
- * ambiguity is a fund-moving one. When both are present the private key wins
- * and `resolveCliWallet` says so on stderr rather than silently picking.
+ * The first two match `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures those surfaces the same way. The order is FIXED
+ * rather than "whichever is configured", because an environment carrying two is
+ * ambiguous about which address funds the stream — and that ambiguity is a
+ * fund-moving one. When more than one is present the earlier entry wins and
+ * `resolveCliWallet` says so on stderr rather than silently picking.
  *
- * ## Why CDP is wired and Privy is not
+ * ## What is different about Privy
  *
- * CDP is the only wallet path in this package with live CI evidence
- * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
- * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
- * viem local account, so it drops straight into the CLI's existing
- * `http(rpcUrl)` transport with no other change.
+ * A private key and a CDP account both sign LOCALLY: `privateKeyToAccount()`
+ * and `toAccount(cdpServerAccount)` are viem local accounts, so they drop
+ * straight into the CLI's `http(rpcUrl)` transport with no other change.
  *
- * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
- * account with no `signTransaction`: they sign and broadcast by sending
- * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
- * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
- * that into the CLI is not a matter of reading three more variables — it
- * changes the transport for every fund-moving command, and `metrik invoke`
- * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
- * `assertLocalSigner` below therefore REFUSES a non-local account with that
- * fact, instead of accepting one and failing later inside viem. See
- * `docs/cli.md` § Wallet.
+ * Privy does not. Its account is a JSON-RPC account with no `signTransaction`:
+ * it signs and broadcasts by sending `eth_sendTransaction` /
+ * `eth_signTypedData_v4` to a provider, so the wallet client's TRANSPORT must
+ * be that provider rather than a plain RPC. That is what {@link CliWallet.transport}
+ * carries, and the only reason this file knows Privy exists. The signer check
+ * below is therefore about CAPABILITY, not about locality: it refuses an
+ * account that genuinely cannot sign, and refuses a non-local account only on
+ * the paths that broadcast through `--rpc-url`.
+ *
+ * See `docs/cli.md` § Wallet.
  */
 export const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
 
@@ -55,6 +65,12 @@ export const CDP_ENV_VARS = [
   "METRIK_AGENT_CDP_OWNER_NAME",
 ] as const;
 
+export {
+  PRIVY_ENV_VARS,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+} from "./privy.js";
+
 /**
  * What the key is for, in the words of the command that needs it. `invoke`
  * signs an EIP-712 invocation capability and broadcasts NOTHING; telling its
@@ -69,48 +85,107 @@ const PURPOSE_TEXT: Record<KeyPurpose, string> = {
 };
 
 /** Which environment configured the signer, for output and for error text. */
-export type CliWalletSource = "private-key" | "cdp";
+export type CliWalletSource = "private-key" | "cdp" | PrivyCliWalletSource;
+
+/**
+ * An account every CLI signing path can actually use.
+ *
+ * `signTypedData` is required rather than optional because it is the one
+ * capability EVERY path needs: fund-moving commands self-sign an EIP-712
+ * `SpendMandate`, and `invoke` signs an EIP-712 `InvocationCapability`. An
+ * account without it type-checks as a viem `Account` and then fails at the
+ * first signature with a `TypeError`.
+ */
+export type CliSignerAccount = Account & Pick<LocalAccount, "signTypedData">;
 
 export interface CliWallet {
   readonly source: CliWalletSource;
+  readonly account: CliSignerAccount;
   /**
-   * A LOCAL signer. Every CLI path either broadcasts through `http(rpcUrl)`
-   * (which cannot sign) or signs EIP-712 off-chain, so a signer that delegates
-   * to a remote provider is refused at resolution rather than mid-command.
+   * The transport fund-moving commands must broadcast through, when the wallet
+   * REQUIRES one. `undefined` means "a plain `http(--rpc-url)` is correct" —
+   * true for a local signer, false for Privy, whose provider IS the transport.
    */
-  readonly account: LocalAccount;
+  readonly transport?: Transport;
   /** One line naming the signer's origin. Safe to print: no secret in it. */
   readonly description: string;
+  /**
+   * Set when this wallet's spend ceiling is enforced where the CLI cannot reach
+   * it — i.e. by a Privy broker policy, not by a locally self-signed mandate.
+   *
+   * Its presence is the signal that the CLI should NOT self-sign a
+   * `SpendMandate` for this wallet, and should read and enforce the real
+   * ceiling instead. See `./spend-policy.ts` for why that substitution is
+   * strictly stronger than the mandate it replaces, and why re-adding the
+   * mandate "for consistency" would be a regression.
+   */
+  readonly readSpendPolicy?: () => Promise<PrivySpendPolicy>;
 }
 
 const WALLET_HINT =
-  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), or configure a Coinbase CDP wallet with ` +
-  `${CDP_ENV_VARS.join(", ")}. Both are read from the environment only — never pass a credential as a command-line flag.`;
+  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), configure a Coinbase CDP wallet with ` +
+  `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
+  `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;
+
+export interface ResolveCliWalletOptions {
+  readonly purpose?: KeyPurpose;
+  /**
+   * `--rpc-url`. Only the Privy paths use it at resolution time: their provider
+   * serves the wallet client's READS as well as its writes, so without this a
+   * Privy command would read from a different endpoint than `--rpc-url` names.
+   */
+  readonly rpcUrl?: string;
+  readonly note?: (line: string) => void;
+  /**
+   * Test seam, same role as `ResolveAgentWalletOptions.createCdpClient`: the
+   * credential store an agent-owned Privy wallet is read from. Unset in every
+   * real run, where the store is selected from the environment.
+   */
+  readonly store?: AutonomousWalletCredentialStore;
+  /** Test seam: the `fetch` the Privy broker is reached through. */
+  readonly fetchImpl?: typeof fetch;
+}
 
 /**
  * Resolves the signing wallet, or throws an actionable configuration error.
  *
- * `note` receives one line when the environment is ambiguous (both wallet
- * sources configured). It is optional so `resolveCliWallet` stays usable from a
- * context with no printer; commands always pass `out.note`.
+ * `note` receives one line when the environment is ambiguous (more than one
+ * wallet source configured). It is optional so `resolveCliWallet` stays usable
+ * from a context with no printer; commands always pass `out.note`.
  */
 export async function resolveCliWallet(
   env: NodeJS.ProcessEnv,
-  options: {
-    readonly purpose?: KeyPurpose;
-    readonly note?: (line: string) => void;
-  } = {},
+  options: ResolveCliWalletOptions = {},
 ): Promise<CliWallet> {
   const wallet = await optionalCliWallet(env, options);
   if (wallet === null) {
     throw configError(
-      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: neither ${PRIVATE_KEY_ENV} nor the CDP variables are set`,
+      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`,
       WALLET_HINT,
     );
   }
   return wallet;
 }
 
+/** True for both Privy shapes, which reach their key through a broker. */
+export function isPrivyWalletSource(
+  source: CliWalletSource,
+): source is PrivyCliWalletSource {
+  return source === "privy-autonomous" || source === "privy-session";
+}
+
+/**
+ * Whether this wallet's ceiling is enforced somewhere the CLI cannot reach.
+ *
+ * The one question every fund-moving command asks before deciding whether to
+ * self-sign a `SpendMandate`. See `./spend-policy.ts`.
+ */
+export function isPolicyEnforced(wallet: CliWallet): wallet is CliWallet & {
+  readonly readSpendPolicy: () => Promise<PrivySpendPolicy>;
+} {
+  return wallet.readSpendPolicy !== undefined;
+}
+
 /**
  * The same resolution, but "nothing configured" is not an error. Used by
  * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
@@ -120,19 +195,24 @@ export async function resolveCliWallet(
  * A wallet that is PARTIALLY configured is still an error here: "you set three
  * of the four CDP variables" and "you configured no wallet" are different
  * facts, and rendering the first as the second sends the reader looking in the
- * wrong place.
+ * wrong place. The same rule applies to a partial Privy setup.
  */
 export async function optionalCliWallet(
   env: NodeJS.ProcessEnv,
-  options: { readonly note?: (line: string) => void } = {},
+  options: Omit<ResolveCliWalletOptions, "purpose"> = {},
 ): Promise<CliWallet | null> {
   const privateKeyAccount = optionalCliAccount(env);
   const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+  const privyConfigured = PRIVY_ENV_VARS.some((name) => isSet(env[name]));
 
   if (privateKeyAccount !== null) {
-    if (cdpConfigured) {
+    const shadowed = [
+      ...(cdpConfigured ? ["CDP"] : []),
+      ...(privyConfigured ? ["Privy"] : []),
+    ];
+    if (shadowed.length > 0) {
       options.note?.(
-        `warning: both ${PRIVATE_KEY_ENV} and CDP wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the CDP wallet.`,
+        `warning: both ${PRIVATE_KEY_ENV} and ${shadowed.join(" and ")} wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the ${shadowed[0]} wallet.`,
       );
     }
     return {
@@ -142,8 +222,32 @@ export async function optionalCliWallet(
     };
   }
 
-  if (!cdpConfigured) return null;
+  if (cdpConfigured) {
+    if (privyConfigured) {
+      options.note?.(
+        "warning: both CDP and Privy wallet variables are set; using the CDP wallet. Unset the CDP variables to sign with the Privy wallet.",
+      );
+    }
+    return await resolveCdpWallet(env);
+  }
+
+  if (!privyConfigured) return null;
 
+  const privy = await resolvePrivyCliWallet(env, options);
+  // Unreachable: `privyConfigured` is exactly the condition under which
+  // `resolvePrivyCliWallet` returns non-null or throws. Kept so a future change
+  // to either predicate fails loudly here rather than as a null deref.
+  if (privy === null) return null;
+  return {
+    source: privy.source,
+    account: assertCliSigner(privy.account, privy.source),
+    transport: privy.transport,
+    description: privy.description,
+    readSpendPolicy: privy.readSpendPolicy,
+  };
+}
+
+async function resolveCdpWallet(env: NodeJS.ProcessEnv): Promise<CliWallet> {
   const missing = CDP_ENV_VARS.filter((name) => !isSet(env[name]));
   if (missing.length > 0) {
     throw configError(
@@ -191,7 +295,7 @@ export async function optionalCliWallet(
 
   return {
     source: "cdp",
-    account: assertLocalSigner(account, "cdp"),
+    account: assertCliSigner(account, "cdp"),
     description: `${account.address} (CDP account "${ownerName}")`,
   };
 }
@@ -214,22 +318,49 @@ export function optionalCliAccount(
 }
 
 /**
- * Every CLI signing path needs a LOCAL signer: fund-moving commands broadcast
- * through `http(--rpc-url)`, which cannot sign, and `invoke` needs a
- * `LocalAccount` to sign the EIP-712 capability. A JSON-RPC account (Privy's
- * adapters) would type-check as an `Account` and then fail somewhere inside
- * viem with a message about a missing method, so it is rejected here with the
- * actual reason.
+ * Whether this wallet source broadcasts through the CLI's own
+ * `http(--rpc-url)` transport, and therefore needs an account that can produce
+ * a signed raw transaction by itself.
+ */
+function broadcastsLocally(source: CliWalletSource): boolean {
+  return source === "private-key" || source === "cdp";
+}
+
+/**
+ * Refuses an account that genuinely cannot sign — and nothing else.
+ *
+ * Two distinct capabilities are checked, because two distinct things fail:
+ *
+ *  - `signTypedData` is needed by EVERY command. Fund-moving commands self-sign
+ *    an EIP-712 `SpendMandate`; `invoke` signs an EIP-712
+ *    `InvocationCapability`. Without it the run dies at the first signature
+ *    with a `TypeError` from inside viem.
+ *  - A LOCAL account is needed only where the CLI broadcasts through
+ *    `http(--rpc-url)`, which cannot sign. A Privy account is deliberately NOT
+ *    local: its provider is the transport and performs `eth_sendTransaction`
+ *    itself, so demanding locality there would reject a wallet that works.
+ *
+ * The earlier version of this guard collapsed both into "must be local", which
+ * is why Privy was refused. Deleting the guard outright was not the fix: it
+ * exists so a broken wallet fails here, named, instead of deep inside viem.
  */
-function assertLocalSigner(
+export function assertCliSigner(
   account: Account,
   source: CliWalletSource,
-): LocalAccount {
-  if (account.type === "local") return account;
-  throw configError(
-    `the ${source} wallet returned a ${account.type} account, which cannot sign locally`,
-    "the CLI broadcasts through --rpc-url and signs EIP-712 capabilities in-process, so it needs a local signer.",
-  );
+): CliSignerAccount {
+  if (typeof account.signTypedData !== "function") {
+    throw configError(
+      `the ${source} wallet (${account.address}) cannot sign EIP-712 typed data`,
+      "every command signs typed data: fund-moving commands self-sign a spend mandate, and `invoke` signs an invocation capability.",
+    );
+  }
+  if (broadcastsLocally(source) && account.type !== "local") {
+    throw configError(
+      `the ${source} wallet returned a ${account.type} account, which cannot sign locally`,
+      "this wallet source broadcasts through --rpc-url, which cannot sign, so it needs a local signer.",
+    );
+  }
+  return account as CliSignerAccount;
 }
 
 function isSet(value: string | undefined): boolean {

package/src/gateway/caller-auth-gateway.ts

@@ -1,6 +1,13 @@
 import { MetrikClient } from "@absol-labs/sdk";
 import { isAddress, isHex, type Address, type Hex } from "viem";
 
+import {
+  evaluateX402Request,
+  X402_PAYMENT_HEADER,
+  type AcceptedX402Payment,
+  type GatewayX402Mode,
+} from "./x402-mode.js";
+import type { X402PaymentRequiredBody } from "../x402/payment-requirements.js";
 import {
   CAPABILITY_HEADER_NAME,
   decodeCapabilityHeader,
@@ -69,7 +76,21 @@ export type CallerAuthDenialReason =
   | "stream-not-active"
   | "stream-expired"
   | "stream-not-funded"
-  | "stream-state-stale";
+  | "stream-state-stale"
+  /**
+   * No Metrik capability, and x402 mode is enabled: the caller may pay per call
+   * instead. Carries an x402 `402` body in
+   * {@link CallerAuthDecision.x402PaymentRequired}. Emitted ONLY when
+   * {@link CallerAuthGatewayConfig.x402} is configured — without it, a missing
+   * capability is still `missing-capability-header` / `403`, unchanged.
+   */
+  | "x402-payment-required"
+  /**
+   * The request carried BOTH a Metrik capability and an `X-PAYMENT` header.
+   * Refused rather than guessed: serving it would charge the caller through one
+   * path while they believe they paid through the other.
+   */
+  | "ambiguous-payment-mode";
 
 /**
  * Default freshness bound for on-chain stream state, in seconds. Base blocks
@@ -116,11 +137,22 @@ export interface CallerAuthDecision {
   readonly authorized: boolean;
   readonly reason?: CallerAuthDenialReason;
   /** Set only when `authorized === false`. */
-  readonly httpStatus?: 402 | 403;
-  /** Set only when `authorized === true`. */
+  readonly httpStatus?: 400 | 402 | 403;
+  /** Set only when `authorized === true` via the Metrik stream path. */
   readonly stream?: GatewayStreamView;
   /** The decoded (but not necessarily valid) capability, when one was present. */
   readonly capability?: SignedInvocationCapability;
+  /**
+   * The x402 `402` body to return verbatim. Set only with
+   * `reason === "x402-payment-required"`.
+   */
+  readonly x402PaymentRequired?: X402PaymentRequiredBody;
+  /**
+   * A verified x402 payment. Set only when `authorized === true` via the x402
+   * path. The caller MUST settle it (see `./x402-mode.ts`) — verification alone
+   * moves no money.
+   */
+  readonly x402Payment?: AcceptedX402Payment;
 }
 
 /** The minimal on-chain stream fields the gateway needs to authorize a call. */
@@ -316,6 +348,13 @@ export interface CallerAuthGatewayConfig {
   readonly nonceCache?: NonceReplayCache;
   /** Injectable clock (unix seconds), for tests. */
   readonly now?: () => number;
+  /**
+   * Optional standard-x402 mode. When set, a request with NO Metrik capability
+   * gets a real x402 `402` challenge instead of a `403`, so a caller holding
+   * only `x402-fetch` can pay per call. Leaving it unset preserves today's
+   * behaviour byte for byte.
+   */
+  readonly x402?: GatewayX402Mode;
 }
 
 export interface CallerAuthRequestInput {
@@ -341,6 +380,7 @@ export class CallerAuthGateway {
   private readonly domain: InvocationCapabilityDomainInput;
   private readonly serviceRefs: ReadonlySet<string>;
   private readonly now: () => number;
+  private readonly x402: GatewayX402Mode | undefined;
 
   constructor(config: CallerAuthGatewayConfig) {
     if (!isAddress(config.escrowAddress)) {
@@ -397,19 +437,50 @@ export class CallerAuthGateway {
       verifyingContract: config.escrowAddress,
     };
     this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+    this.x402 = config.x402;
   }
 
   async authorize(
     request: CallerAuthRequestInput,
   ): Promise<CallerAuthDecision> {
     const headerValue = lookupHeader(request.headers, this.headerName);
-    if (headerValue === undefined || headerValue.length === 0) {
+    const hasCapabilityHeader =
+      headerValue !== undefined && headerValue.length > 0;
+
+    if (this.x402 !== undefined) {
+      const paymentHeader = lookupHeader(request.headers, X402_PAYMENT_HEADER);
+      const hasPaymentHeader =
+        paymentHeader !== undefined && paymentHeader.trim().length > 0;
+
+      // Exactly one payment mode per request. See `./x402-mode.ts`.
+      if (hasCapabilityHeader && hasPaymentHeader) {
+        return deny("ambiguous-payment-mode", 400);
+      }
+      if (!hasCapabilityHeader) {
+        const evaluated = await evaluateX402Request(
+          { method: request.method, path: request.path },
+          paymentHeader,
+          this.x402,
+        );
+        if (evaluated.outcome === "accepted") {
+          return { authorized: true, x402Payment: evaluated.payment };
+        }
+        return {
+          authorized: false,
+          reason: "x402-payment-required",
+          httpStatus: 402,
+          x402PaymentRequired: evaluated.body,
+        };
+      }
+    }
+
+    if (!hasCapabilityHeader) {
       return deny("missing-capability-header", 403);
     }
 
     let capability: SignedInvocationCapability;
     try {
-      capability = decodeCapabilityHeader(headerValue);
+      capability = decodeCapabilityHeader(headerValue as string);
     } catch (error) {
       if (error instanceof InvalidCapabilityHeaderError) {
         return deny("malformed-capability-header", 403);
@@ -569,7 +640,7 @@ function freshestView(views: readonly GatewayStreamView[]): GatewayStreamView {
 
 function deny(
   reason: CallerAuthDenialReason,
-  httpStatus: 402 | 403,
+  httpStatus: 400 | 402 | 403,
   capability?: SignedInvocationCapability,
 ): CallerAuthDecision {
   return {