@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/src/mcp/server.ts

@@ -1,12 +1,11 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 
-import { BASE_SEPOLIA_ESCROW_V2 } from "@absol-labs/sdk";
+import type { MetrikNetwork } from "@absol-labs/sdk";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { privateKeyToAccount } from "viem/accounts";
 import { http, isAddress, isHex, type Chain } from "viem";
-import { baseSepolia } from "viem/chains";
 import { z } from "zod";
 
 import {
@@ -14,6 +13,7 @@ import {
   type DiscoverServicesOptions,
   type ServiceListing,
 } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
   parseServerMandateCapsEnv,
@@ -60,6 +60,19 @@ import {
   type ServiceInvocationResult,
   type ServiceInvoker,
 } from "./service-invoker.js";
+import {
+  defaultNetwork,
+  readOnlyMetrikClient,
+  registeredDeployment,
+  resolveAgentNetwork,
+} from "../network.js";
+import {
+  REFUND_STATUS_TOOL_DESCRIPTION,
+  REFUND_TOOL_DESCRIPTION,
+  X402_PAY_TOOL_DESCRIPTION,
+  registerX402Tools,
+  type McpX402Options,
+} from "./x402-tools.js";
 
 /**
  * MCP server for the agent lane.
@@ -223,19 +236,26 @@ const metrikAgentEnvSchema = z.object({
   METRIK_AGENT_REGISTRY_URL: z.string().url().optional(),
   METRIK_AGENT_REGISTRY_APIKEY: z.string().optional(),
   METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR: z.string().optional(),
+  METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW: z.string().optional(),
+  METRIK_NETWORK: z.string().optional(),
+  METRIK_AGENT_X402: z.string().optional(),
+  METRIK_AGENT_X402_ALLOWED_HOSTS: z.string().optional(),
 });
 
 /**
- * The retired V1 metered escrow.
+ * Opt in to an escrow that is NOT the network's registered `StreamEscrowV2`.
  *
- * Refused by NAME rather than left to fail at read time, because it does not
- * fail at read time: V1 and V2 `getStream` return different tuples that diverge
- * from index 5 onward, so a V2 decoder pointed at V1 does not revert — it
- * decodes other fields into correctly-named ones and reports a confident wrong
- * answer about someone's money. This repository's own shipped docs pointed
- * `METRIK_AGENT_ESCROW` here as recently as 0.10.0.
+ * Off by default, because a wrong escrow does not fail at read time: the
+ * retired V1 escrow's `getStream` returns a tuple that diverges from V2's from
+ * index 5 onward, so a V2 decoder pointed at it does not revert — it decodes
+ * other fields into correctly-named ones and reports a confident wrong answer
+ * about someone's money. This repository's own shipped docs pointed
+ * `METRIK_AGENT_ESCROW` at V1 as recently as 0.10.0. Requiring the escrow to be
+ * the one the SDK network registry records for the chain refuses V1 (and any
+ * other stray address) without naming it in code. Operator-set input only.
  */
-const RETIRED_V1_ESCROW = "0x21948a5e6ae8d9a3d1050791ab6138657fb54286";
+export const ALLOW_UNREGISTERED_ESCROW_ENV =
+  "METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW";
 
 /**
  * Opt out of the operator/serviceRef cross-check on hire. Operator-set input
@@ -255,7 +275,7 @@ const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
  * generation has to be a stated fact that can be wrong out loud, rather than an
  * assumption buried in one constructor argument.
  */
-export type EscrowGeneration = "v2";
+export type EscrowGeneration = "v2" | "v3";
 
 export interface McpToolSpec {
   name: string;
@@ -317,6 +337,21 @@ export const METRIK_MCP_TOOLS: readonly McpToolSpec[] = [
       "Generate a buyer-side zkTLS proof of an HTTPS response from a stream's verified service origin. PUBLIC listings only: the proof is fetched by a third-party Reclaim attestor, which cannot present this stream's caller-auth capability, so a GATED listing answers the attestor with a 403 and the tool fails closed rather than proving a rejection. This is an L2 delivery signal (consumer zkTLS) and must be cross-checked with oracle/L1 evidence; it is not a substitute for it.",
     movesFunds: false,
   },
+  {
+    name: "x402_pay",
+    description: X402_PAY_TOOL_DESCRIPTION,
+    movesFunds: true,
+  },
+  {
+    name: "refund_status",
+    description: REFUND_STATUS_TOOL_DESCRIPTION,
+    movesFunds: false,
+  },
+  {
+    name: "refund",
+    description: REFUND_TOOL_DESCRIPTION,
+    movesFunds: true,
+  },
 ] as const;
 
 /** @deprecated Renamed to METRIK_MCP_TOOLS; retained for back-compat. */
@@ -332,12 +367,40 @@ export interface StoredStreamRecord {
   readonly maxDurationSeconds: number;
   readonly openedAtSeconds: number;
   readonly mandateId: `0x${string}`;
+  /** x402 streams only: the seller's refund relay URL for this stream. */
+  readonly refundUrl?: string;
+  /** x402 streams only: the X402StreamOpener that bought the stream. */
+  readonly opener?: `0x${string}`;
+  /**
+   * An x402 payment approved and signed whose stream is not (yet) known. It
+   * counts against the cumulative cap exactly like a stream; `streamId` is a
+   * reservation key, not an escrow stream id.
+   */
+  readonly x402Reservation?: boolean;
+  /**
+   * NOT a stream: a settled x402 upfront-only charge (an upfront opener with
+   * `upfrontAmount == price` opens no stream). It counts against the
+   * cumulative cap like any spend and has nothing to refund; `streamId` is a
+   * charge key, not an escrow stream id.
+   */
+  readonly x402Charge?: "upfront-only";
+  /**
+   * x402 upfront openers: the NON-REFUNDABLE part of `budgetUsdc` (paid to the
+   * seller at settlement). Informational: `budgetUsdc` always counts it.
+   */
+  readonly nonRefundableUsdc?: bigint;
 }
 
 export interface StreamRegistry {
   put(record: StoredStreamRecord): Promise<void>;
   get(streamId: `0x${string}`): Promise<StoredStreamRecord | null>;
   list(): Promise<readonly StoredStreamRecord[]>;
+  /**
+   * Remove a record. Used ONLY to release an x402 spend reservation that
+   * provably never moved money, or one superseded by its real stream. A
+   * registry without it keeps reservations (they over-count: buyer-favouring).
+   */
+  delete?(streamId: `0x${string}`): Promise<void>;
 }
 
 export class InMemoryStreamRegistry implements StreamRegistry {
@@ -354,6 +417,10 @@ export class InMemoryStreamRegistry implements StreamRegistry {
   async list(): Promise<readonly StoredStreamRecord[]> {
     return Array.from(this.records.values());
   }
+
+  async delete(streamId: `0x${string}`): Promise<void> {
+    this.records.delete(streamId);
+  }
 }
 
 export class FileStreamRegistry implements StreamRegistry {
@@ -374,6 +441,11 @@ export class FileStreamRegistry implements StreamRegistry {
     return Array.from((await this.readAll()).values());
   }
 
+  async delete(streamId: `0x${string}`): Promise<void> {
+    const records = await this.readAll();
+    if (records.delete(streamId)) await this.writeAll(records);
+  }
+
   private async readAll(): Promise<Map<`0x${string}`, StoredStreamRecord>> {
     const contents = await fs.readFile(this.filePath, "utf8").catch((error) => {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
@@ -393,6 +465,11 @@ export class FileStreamRegistry implements StreamRegistry {
           maxDurationSeconds: z.number().int().positive(),
           openedAtSeconds: z.number().int().nonnegative(),
           mandateId: bytes32Schema,
+          refundUrl: z.string().url().optional(),
+          opener: addressSchema.optional(),
+          x402Reservation: z.boolean().optional(),
+          x402Charge: z.literal("upfront-only").optional(),
+          nonRefundableUsdc: decimalStringSchema.optional(),
         }),
       )
       .parse(JSON.parse(contents));
@@ -410,6 +487,19 @@ export class FileStreamRegistry implements StreamRegistry {
           maxDurationSeconds: record.maxDurationSeconds,
           openedAtSeconds: record.openedAtSeconds,
           mandateId: record.mandateId as `0x${string}`,
+          ...(record.refundUrl === undefined
+            ? {}
+            : { refundUrl: record.refundUrl }),
+          ...(record.opener === undefined
+            ? {}
+            : { opener: record.opener as `0x${string}` }),
+          ...(record.x402Reservation === true ? { x402Reservation: true } : {}),
+          ...(record.x402Charge === undefined
+            ? {}
+            : { x402Charge: record.x402Charge }),
+          ...(record.nonRefundableUsdc === undefined
+            ? {}
+            : { nonRefundableUsdc: BigInt(record.nonRefundableUsdc) }),
         },
       ]),
     );
@@ -426,6 +516,9 @@ export class FileStreamRegistry implements StreamRegistry {
           ...record,
           budgetUsdc: record.budgetUsdc.toString(),
           ratePerSecondUsdc: record.ratePerSecondUsdc.toString(),
+          ...(record.nonRefundableUsdc === undefined
+            ? {}
+            : { nonRefundableUsdc: record.nonRefundableUsdc.toString() }),
         })),
         null,
         2,
@@ -494,6 +587,12 @@ export interface VerifiedStreamMcpServerOptions {
    * the registry URL/apikey come from env inside `discoverServices`.
    */
   readonly discoverServices?: DiscoverServicesFn;
+  /**
+   * The buyer side of x402. When set, `x402_pay`, `refund_status` and `refund`
+   * are registered (mandate-gated like `hire_verified_service`); unset, the
+   * tool surface is exactly as before.
+   */
+  readonly x402?: McpX402Options;
   readonly serverInfo?: {
     readonly name: string;
     readonly version: string;
@@ -512,6 +611,12 @@ export interface ParsedMetrikAgentEnv {
   readonly escrow: `0x${string}`;
   /** Which escrow generation {@link escrow} is, as CONFIGURED (never probed). */
   readonly escrowGeneration: EscrowGeneration;
+  /**
+   * True when `escrow` is NOT a registered deployment and the operator opted
+   * in (`METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW=true` + an explicit
+   * `METRIK_AGENT_ESCROW_GENERATION`); the SDK then skips its code-hash pin.
+   */
+  readonly unregisteredEscrow: boolean;
   /** Registry the invocation origin is verified against. Undefined = the public default. */
   readonly registryUrl?: string;
   readonly registryApiKey?: string;
@@ -519,6 +624,12 @@ export interface ParsedMetrikAgentEnv {
   readonly allowUnverifiedOperatorPairing: boolean;
   readonly usdc: `0x${string}`;
   readonly chain: Chain;
+  /** The registered network this server settles on (SDK network registry). */
+  readonly network: MetrikNetwork;
+  /** `METRIK_AGENT_X402`: register the x402 tools. OPT-IN: only `1`/`true`/`yes`/`on`. */
+  readonly x402Enabled: boolean;
+  /** `METRIK_AGENT_X402_ALLOWED_HOSTS`, comma-separated; empty = any public host. */
+  readonly x402AllowedHosts: readonly string[];
   readonly stateFile?: string;
   readonly wallet: AgentWalletInput;
 }
@@ -755,6 +866,30 @@ export function createVerifiedStreamMcpServer(
           }
         }
 
+        // Is the rate inside the band the operator SIGNED? The escrow accepts
+        // any non-zero rate, but the seller's capability gateway answers every
+        // request on an out-of-band stream with 403
+        // `stream-rate-out-of-bounds`, so such a hire escrows the buyer's USDC
+        // into a stream that can never be served. Checked against the verified
+        // listing the pairing check just resolved — no second registry read,
+        // and no tool argument can widen the band. A descriptor that does not
+        // verify is a refusal, never "no band". Only an unverified pairing
+        // (which already needed the operator-set override above) has no listing
+        // to check, and its success result says so.
+        if (pairing.verdict === "verified") {
+          const band = await checkListedRateBand(
+            async () => [pairing.listing],
+            args.serviceRef,
+            request.ratePerSecondUsdc,
+            "ratePerSecondUsdc",
+          );
+          if (!band.ok) {
+            return errorResult(
+              `${band.message} Pick a ratePerSecondUsdc inside the band (discover_services reports it as ratePerSecondBand).`,
+            );
+          }
+        }
+
         // Serialize per owner: the spent-so-far read, cap check, open, and
         // registry write must be atomic, or concurrent hires could both pass
         // the cumulative-cap check on stale spend and overshoot maxTotalUsdc.
@@ -811,7 +946,7 @@ export function createVerifiedStreamMcpServer(
               : request.ratePerSecondUsdc * BigInt(request.maxDurationSeconds);
 
           return successResult(
-            `opened verified stream ${result.streamId} on chain ${result.handle.chainId}.${pairing.verdict === "verified" ? "" : ` WARNING: the operator/serviceRef pairing was NOT verified (${pairing.verdict}) and this server is configured to escrow anyway via ${ALLOW_UNVERIFIED_OPERATOR_ENV}. The operator is the wallet that gets paid and nothing proved it owns this service.`} The meter is running from now at ${request.ratePerSecondUsdc} USDC base units per VERIFIED second, whether or not you call the service. Call it with invoke_service; stop the meter with reclaim_unspent.`,
+            `opened verified stream ${result.streamId} on chain ${result.handle.chainId}.${pairing.verdict === "verified" ? "" : ` WARNING: the operator/serviceRef pairing was NOT verified (${pairing.verdict}) and this server is configured to escrow anyway via ${ALLOW_UNVERIFIED_OPERATOR_ENV}. The operator is the wallet that gets paid and nothing proved it owns this service, and the operator-signed rate band could not be checked either: if this rate is outside it, the service's gateway refuses every request while the deposit stays escrowed.`} The meter is running from now at ${request.ratePerSecondUsdc} USDC base units per VERIFIED second, whether or not you call the service. Call it with invoke_service; stop the meter with reclaim_unspent.`,
             {
               streamId: result.streamId,
               txHash: result.txHash,
@@ -1014,13 +1149,30 @@ export function createVerifiedStreamMcpServer(
         const records = await registry.list();
         const entries = await Promise.all(
           records.map(async (record) => {
-            const status = await options.agentClient
-              .getStreamStatus(record.streamId)
-              .then((value) => serializeStreamStatus(value, record.streamId))
-              .catch((error) => ({
-                streamId: record.streamId,
-                statusError: asErrorMessage(error),
-              }));
+            // A reservation key is not an escrow stream: report it as what it
+            // is instead of reading a stream that does not exist.
+            const status =
+              record.x402Charge === "upfront-only"
+                ? {
+                    streamId: record.streamId,
+                    x402Charge:
+                      "a settled x402 upfront-only charge: the whole price was a non-refundable per-call charge, no stream exists and there is nothing to refund; its amount counts against the spend mandate",
+                  }
+                : record.x402Reservation === true
+                  ? {
+                      streamId: record.streamId,
+                      x402Reservation:
+                        "an x402 payment was signed but its stream could not be confirmed; its amount stays counted against the spend mandate",
+                    }
+                  : await options.agentClient
+                      .getStreamStatus(record.streamId)
+                      .then((value) =>
+                        serializeStreamStatus(value, record.streamId),
+                      )
+                      .catch((error) => ({
+                        streamId: record.streamId,
+                        statusError: asErrorMessage(error),
+                      }));
             return {
               streamId: record.streamId,
               buyer: record.buyer,
@@ -1031,6 +1183,9 @@ export function createVerifiedStreamMcpServer(
               maxDurationSeconds: record.maxDurationSeconds,
               openedAtSeconds: record.openedAtSeconds,
               mandateId: record.mandateId,
+              ...(record.nonRefundableUsdc === undefined
+                ? {}
+                : { nonRefundableUsdc: record.nonRefundableUsdc.toString() }),
               status,
             };
           }),
@@ -1046,6 +1201,34 @@ export function createVerifiedStreamMcpServer(
     },
   );
 
+  if (options.x402 !== undefined) {
+    registerX402Tools(mcpServer, {
+      x402: options.x402,
+      resolveMandate,
+      getSpentSoFarUsdc: (owner) => resolver.getSpentSoFarUsdc(owner),
+      getRevokedMandateIds: (owner) => resolver.getRevokedMandateIds(owner),
+      // The SAME per-owner chain as hire_verified_service: a hire and an x402
+      // payment from one owner can never both pass the cumulative cap on
+      // stale spend.
+      serialize: serializeHire,
+      recordStream: async (record) => {
+        await registry.put(record);
+      },
+      ...(registry.delete === undefined
+        ? {}
+        : {
+            removeStream: async (streamId: `0x${string}`) => {
+              await registry.delete?.(streamId);
+            },
+          }),
+      findStream: async (streamId) => await registry.get(streamId),
+      now,
+      ok: successResult,
+      fail: errorResult,
+      unexpected: safeToolError,
+    });
+  }
+
   if (options.deliveryProofService !== undefined) {
     const deliveryProofService = options.deliveryProofService;
     mcpServer.registerTool(
@@ -1187,41 +1370,76 @@ export function parseMetrikAgentEnv(
     // so that array was the ONLY thing an operator ever saw — a correct failure
     // rendered as noise. Name the variables instead.
     throw new Error(
-      `metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP/Privy variables). METRIK_AGENT_CHAIN_ID defaults to Base Sepolia (${baseSepolia.id}).`,
+      `metrik-mcp is not configured: ${describeEnvIssues(result.error)}. Set METRIK_AGENT_RPC_URL (an http(s) URL), METRIK_AGENT_ESCROW and METRIK_AGENT_USDC (EVM addresses), plus a wallet (METRIK_AGENT_PRIVATE_KEY, or the CDP variables — a Privy wallet is a CLI-only source and is not resolved here). METRIK_NETWORK (or METRIK_AGENT_CHAIN_ID) defaults to the registry's default network (${defaultNetwork().name}).`,
     );
   }
   const parsed = result.data;
-  const chainId = Number(parsed.METRIK_AGENT_CHAIN_ID ?? baseSepolia.id);
-  if (!Number.isInteger(chainId) || chainId <= 0) {
-    throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
+  let chainId: number | undefined;
+  if (parsed.METRIK_AGENT_CHAIN_ID !== undefined) {
+    chainId = Number(parsed.METRIK_AGENT_CHAIN_ID);
+    if (!Number.isInteger(chainId) || chainId <= 0) {
+      throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
+    }
   }
-  if (chainId !== baseSepolia.id) {
+  // "Is this a network the registry knows and the build allows": a registered
+  // TESTNET. This server signs with a key from the environment and moves funds.
+  let network: MetrikNetwork;
+  try {
+    network = resolveAgentNetwork(
+      parsed.METRIK_NETWORK !== undefined &&
+        parsed.METRIK_NETWORK.trim().length > 0
+        ? parsed.METRIK_NETWORK
+        : chainId,
+      { testnetOnly: true },
+    );
+  } catch (error) {
     throw new Error(
-      `unsupported METRIK_AGENT_CHAIN_ID ${chainId}; phase 2 is Base Sepolia only`,
+      `unsupported METRIK_NETWORK / METRIK_AGENT_CHAIN_ID: ${error instanceof Error ? error.message : String(error)}`,
     );
   }
-
-  // Generation is CONFIGURED. `v2` is the only generation the checkpoint escrow
-  // semantics this server implements apply to, so anything else is refused up
-  // front instead of silently mis-decoded (see RETIRED_V1_ESCROW).
-  const generation = (
-    parsed.METRIK_AGENT_ESCROW_GENERATION ?? "v2"
-  ).toLowerCase();
-  if (generation !== "v2") {
+  if (chainId !== undefined && chainId !== network.chain.id) {
     throw new Error(
-      `unsupported METRIK_AGENT_ESCROW_GENERATION "${parsed.METRIK_AGENT_ESCROW_GENERATION}": this server reads checkpoint-settled StreamEscrowV2 only. Leave it unset (or set it to "v2") and point METRIK_AGENT_ESCROW at the V2 escrow.`,
+      `METRIK_AGENT_CHAIN_ID ${chainId} does not match METRIK_NETWORK ${network.id} (chain ${network.chain.id})`,
     );
   }
-  if (parsed.METRIK_AGENT_ESCROW.toLowerCase() === RETIRED_V1_ESCROW) {
+
+  // Generation: a registered deployment's comes from the registry (a
+  // contradicting env value is refused); an unregistered escrow needs it
+  // DECLARED. Only the checkpoint-settled generations (v2, v3) are served.
+  const declared = parsed.METRIK_AGENT_ESCROW_GENERATION?.trim().toLowerCase();
+  if (declared !== undefined && declared !== "v2" && declared !== "v3") {
     throw new Error(
-      `METRIK_AGENT_ESCROW is the RETIRED V1 metered escrow (${parsed.METRIK_AGENT_ESCROW}). It is no longer settled by the oracle, and its stream tuple is incompatible with the checkpoint decoder this server uses — reads would not revert, they would return confident nonsense. Point it at the live StreamEscrowV2 (${BASE_SEPOLIA_ESCROW_V2}).`,
+      `unsupported METRIK_AGENT_ESCROW_GENERATION "${parsed.METRIK_AGENT_ESCROW_GENERATION}": this server reads the checkpoint-settled StreamEscrowV2/V3 only. Leave it unset for a registered escrow.`,
     );
   }
+  const deployment = registeredDeployment(network, parsed.METRIK_AGENT_ESCROW);
+  let generation: EscrowGeneration;
+  if (deployment !== undefined) {
+    generation = deployment.escrow.generation;
+    if (declared !== undefined && declared !== generation) {
+      throw new Error(
+        `METRIK_AGENT_ESCROW_GENERATION "${declared}" contradicts the registry: ${parsed.METRIK_AGENT_ESCROW} is ${network.name}'s ${generation} escrow`,
+      );
+    }
+  } else {
+    if (parsed.METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW !== "true") {
+      throw new Error(
+        `METRIK_AGENT_ESCROW (${parsed.METRIK_AGENT_ESCROW}) is not a registered escrow of ${network.name} (current ${network.escrow.address}${network.legacy.length === 0 ? "" : `; legacy ${network.legacy.map((d) => d.escrow.address).join(", ")}`}). A wrong escrow does not fail at read time — the retired V1 escrow's stream tuple decodes into confident nonsense with the checkpoint decoder this server uses. Point it at a registered escrow, or set ${ALLOW_UNREGISTERED_ESCROW_ENV}=true and METRIK_AGENT_ESCROW_GENERATION for a deliberate private deployment.`,
+      );
+    }
+    if (declared === undefined) {
+      throw new Error(
+        `${ALLOW_UNREGISTERED_ESCROW_ENV}=true also needs METRIK_AGENT_ESCROW_GENERATION ("v2" | "v3"): an unregistered escrow's generation cannot be read from the registry`,
+      );
+    }
+    generation = declared;
+  }
 
   return {
     rpcUrl: parsed.METRIK_AGENT_RPC_URL,
     escrow: parsed.METRIK_AGENT_ESCROW as `0x${string}`,
-    escrowGeneration: "v2",
+    escrowGeneration: generation,
+    unregisteredEscrow: deployment === undefined,
     // Opt-IN only: any value but the exact string "true" leaves the check on.
     allowUnverifiedOperatorPairing:
       parsed.METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR === "true",
@@ -1233,9 +1451,19 @@ export function parseMetrikAgentEnv(
       : { registryApiKey: parsed.METRIK_AGENT_REGISTRY_APIKEY }),
     usdc: parsed.METRIK_AGENT_USDC as `0x${string}`,
     chain: {
-      ...baseSepolia,
-      name: parsed.METRIK_AGENT_CHAIN_NAME ?? baseSepolia.name,
+      ...network.chain,
+      name: parsed.METRIK_AGENT_CHAIN_NAME ?? network.chain.name,
     },
+    network,
+    // Opt-IN: a fund-moving tool family whose URL the MODEL picks is never
+    // switched on by default or by an unrecognised value.
+    x402Enabled: ["1", "true", "yes", "on"].includes(
+      (parsed.METRIK_AGENT_X402 ?? "").trim().toLowerCase(),
+    ),
+    x402AllowedHosts: (parsed.METRIK_AGENT_X402_ALLOWED_HOSTS ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0),
     ...(parsed.METRIK_AGENT_MCP_STATE_FILE === undefined
       ? {}
       : {
@@ -1281,7 +1509,15 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
       // SDK treats the client as V1 and routes claimable()/reclaimable() to the
       // legacy ABI, which reverts against StreamEscrowV2: the checkpoint escrow
       // replaced those one-argument views with proof-carrying ones.
-      ...(parsed.escrowGeneration === "v2" ? { escrowV2: parsed.escrow } : {}),
+      escrowV2: parsed.escrow,
+      // An unregistered escrow was opted into by the operator: the SDK skips
+      // its code-hash pin only with both flags (see parseMetrikAgentEnv).
+      ...(parsed.unregisteredEscrow
+        ? {
+            allowUnregisteredEscrow: true,
+            escrowGeneration: parsed.escrowGeneration,
+          }
+        : {}),
       usdc: parsed.usdc,
       settlementTarget: {
         chainId: parsed.chain.id,
@@ -1319,6 +1555,10 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
     streamReader: createSdkInvokeStreamReader({
       escrowAddress: parsed.escrow,
       rpcUrl: parsed.rpcUrl,
+      chainId: parsed.chain.id,
+      ...(parsed.unregisteredEscrow
+        ? { unregisteredEscrowGeneration: parsed.escrowGeneration }
+        : {}),
     }),
     buyer: requireCapabilitySigner(wallet.account),
     domain: { chainId, verifyingContract: parsed.escrow },
@@ -1346,6 +1586,39 @@ export async function createVerifiedStreamMcpServerOptionsFromEnv(
         : new FileStreamRegistry(parsed.stateFile),
     allowUnverifiedOperatorPairing: parsed.allowUnverifiedOperatorPairing,
     serviceInvoker,
+    ...(parsed.x402Enabled
+      ? {
+          x402: {
+            signer: requireCapabilitySigner(
+              wallet.account,
+            ) as unknown as McpX402Options["signer"],
+            network: parsed.network,
+            // The SDK's on-chain quote checks (factory.predict) read through
+            // this server's own RPC.
+            sdkOptions: { transport: http(parsed.rpcUrl) },
+            ...(parsed.x402AllowedHosts.length === 0
+              ? {}
+              : { allowedHosts: parsed.x402AllowedHosts }),
+            refundClient: async (target) => {
+              const { refundClient } = await import("@absol-labs/sdk/x402");
+              return refundClient(target.refundUrl, {
+                streamId: target.streamId,
+                ...(target.opener === undefined
+                  ? {}
+                  : { opener: target.opener }),
+                ...(target.fetch === undefined ? {} : { fetch: target.fetch }),
+                // Every relay "success" is checked against the receipt.
+                verifyWith: readOnlyMetrikClient({
+                  escrowAddress: parsed.escrow,
+                  rpcUrl: parsed.rpcUrl,
+                  chainId: parsed.chain.id,
+                }),
+                expectedChainId: parsed.chain.id,
+              });
+            },
+          } satisfies McpX402Options,
+        }
+      : {}),
     ...(deliveryProofService === null ? {} : { deliveryProofService }),
   };
 }
@@ -1395,6 +1668,42 @@ function serializeServiceListing(
     ...(listing.targetMetadata === undefined
       ? {}
       : { targetMetadata: listing.targetMetadata }),
+    ...signedRateBandField(listing),
+  };
+}
+
+/**
+ * The operator-signed rate band, in USDC atomic units per second, so an agent
+ * can pick a `ratePerSecondUsdc` that hire_verified_service will accept. Read
+ * from the record discovery already verified; omitted when none was signed.
+ * hire_verified_service re-verifies it before enforcing it.
+ */
+function signedRateBandField(listing: ServiceListing): {
+  readonly ratePerSecondBand?: Record<string, string | null>;
+} {
+  const commercial = (
+    listing.signed as
+      | {
+          readonly descriptor?: {
+            readonly commercial?: {
+              readonly minRatePerSecond?: string;
+              readonly maxRatePerSecond?: string;
+            };
+          };
+        }
+      | undefined
+  )?.descriptor?.commercial;
+  if (
+    commercial?.minRatePerSecond === undefined &&
+    commercial?.maxRatePerSecond === undefined
+  ) {
+    return {};
+  }
+  return {
+    ratePerSecondBand: {
+      minRatePerSecondUsdc: commercial.minRatePerSecond ?? null,
+      maxRatePerSecondUsdc: commercial.maxRatePerSecond ?? null,
+    },
   };
 }
 
@@ -1481,7 +1790,7 @@ function hasForbiddenPathCharacter(value: string): boolean {
 
 /** Lower-cases header names so duplicate/odd-cased keys collapse to one. */
 type OperatorPairing =
-  | { readonly verdict: "verified" }
+  | { readonly verdict: "verified"; readonly listing: ServiceListing }
   | { readonly verdict: "mismatch"; readonly listedOperator: `0x${string}` }
   | { readonly verdict: "unlisted" }
   | {
@@ -1531,7 +1840,7 @@ async function checkOperatorPairing(
   if (listing.operator.toLowerCase() !== operator.toLowerCase()) {
     return { verdict: "mismatch", listedOperator: listing.operator };
   }
-  return { verdict: "verified" };
+  return { verdict: "verified", listing };
 }
 
 /**