@absol-labs/agent 0.9.1 → 0.11.0

package/src/x402/facilitator.ts

@@ -1,3 +1,16 @@
+/**
+ * Metrik-native HTTP `402` challenge flow.
+ *
+ * This is NOT an implementation of the x402 protocol. It uses its own scheme
+ * string (`streamproof-verified-stream`), its own wire format, and its own
+ * request header (`x-metrik-payment`). It does not interoperate with
+ * `x402-fetch`, `x402-axios`, `x402-express`, or any other x402 client or
+ * facilitator. See `docs/x402.md` for the full explanation of why Metrik's
+ * metered-stream settlement does not fit any shipped x402 scheme.
+ *
+ * The `X402*` / `x402*` exports at the bottom of this file are deprecated
+ * aliases of the canonical names, kept so existing consumers keep working.
+ */
 import type { StreamProofClientConfig } from "@absol-labs/sdk";
 import { z } from "zod";
 
@@ -16,7 +29,19 @@ import {
   type VerifiedConsumedHttpsResponseProof,
 } from "../zktls/reclaim.js";
 
-export const X402_SCHEME = "streamproof-verified-stream" as const;
+/**
+ * Immutable wire constant for the Metrik-native 402 scheme. The value is
+ * historical (`streamproof-*` predates the Metrik rename) and MUST NOT change:
+ * the live gateway and deployed callers depend on it.
+ */
+export const METRIK_STREAM_SCHEME = "streamproof-verified-stream" as const;
+
+/**
+ * Request header carrying the Metrik verified-stream payload. Deliberately NOT
+ * `x-payment`: that header belongs to the x402 protocol, which this flow does
+ * not implement.
+ */
+export const METRIK_PAYMENT_HEADER = "x-metrik-payment" as const;
 
 const addressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
 const bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
@@ -35,36 +60,36 @@ export interface VerifiedStreamRequirements extends z.infer<
   typeof verifiedStreamRequirementsSchema
 > {}
 
-export const x402StreamChallengeSchema = z.object({
-  scheme: z.literal(X402_SCHEME),
+export const streamChallengeSchema = z.object({
+  scheme: z.literal(METRIK_STREAM_SCHEME),
   requirements: verifiedStreamRequirementsSchema,
 });
 
-export interface X402StreamChallenge extends z.infer<
-  typeof x402StreamChallengeSchema
+export interface StreamChallenge extends z.infer<
+  typeof streamChallengeSchema
 > {}
 
-export const x402OpenPayloadSchema = z.object({
-  challenge: x402StreamChallengeSchema,
+export const streamOpenPayloadSchema = z.object({
+  challenge: streamChallengeSchema,
   signedMandate: signedSpendMandateSchema,
 });
 
-export interface X402OpenPayload extends z.infer<
-  typeof x402OpenPayloadSchema
+export interface StreamOpenPayload extends z.infer<
+  typeof streamOpenPayloadSchema
 > {}
 
-export interface X402Facilitator {
+export interface StreamFacilitator {
   /** Build the 402 challenge a server returns to prompt a verified stream. */
-  challenge(req: VerifiedStreamRequirements): X402StreamChallenge;
+  challenge(req: VerifiedStreamRequirements): StreamChallenge;
   /** Verify + open the stream from an agent's signed payment payload. */
   open(payloadHeader: string): Promise<{ streamId: `0x${string}` }>;
   /** Prove the HTTPS response consumed after opening a verified stream. */
   proveConsumedHttpsResponse(
-    input: X402ConsumedHttpsResponseProofInput,
+    input: ConsumedHttpsResponseProofInput,
   ): Promise<VerifiedConsumedHttpsResponseProof>;
 }
 
-export interface X402ConsumedHttpsResponseProofInput {
+export interface ConsumedHttpsResponseProofInput {
   readonly signedMandate: SignedSpendMandate;
   readonly streamId?: `0x${string}`;
   readonly operator?: `0x${string}`;
@@ -109,9 +134,11 @@ function warnFacilitatorOnce(key: string, message: string): void {
   console.error(message);
 }
 
-export class X402PayloadError extends Error {
+export class StreamPayloadError extends Error {
   constructor(message: string) {
     super(message);
+    // Unchanged on purpose: `error.name` is an observable value that existing
+    // consumers may match on. The class was renamed; its `name` was not.
     this.name = "X402PayloadError";
   }
 }
@@ -137,14 +164,15 @@ export class DeliveryProofUnavailableError extends Error {
  * facilitator denies the open in this case (fail-closed, buyer-favoring) rather
  * than proceeding on an unverified assumption of "0 spent / none revoked".
  */
-export class X402SpendControlUnavailableError extends Error {
+export class SpendControlUnavailableError extends Error {
   constructor(message: string) {
     super(message);
+    // Unchanged on purpose: see StreamPayloadError above.
     this.name = "X402SpendControlUnavailableError";
   }
 }
 
-export class VerifiedStreamX402Facilitator implements X402Facilitator {
+export class VerifiedStreamFacilitator implements StreamFacilitator {
   private readonly agentClient: VerifiedStreamAgentOpener;
   private readonly deliveryProofs: ConsumerDeliveryProofService | undefined;
   private readonly sdkConfig: StreamProofClientConfig;
@@ -181,26 +209,26 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     // both resolvers are wired; warn once so the reason is visible at deploy time.
     if (options.resolveSpentSoFarUsdc === undefined) {
       warnFacilitatorOnce(
-        "x402-spent",
-        "[metrik] x402 facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
+        "metrik-stream-spent",
+        "[metrik] Metrik verified-stream facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
     if (options.resolveRevokedMandateIds === undefined) {
       warnFacilitatorOnce(
-        "x402-revocation",
-        "[metrik] x402 facilitator: no resolveRevokedMandateIds wired — revocation state cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
+        "metrik-stream-revocation",
+        "[metrik] Metrik verified-stream facilitator: no resolveRevokedMandateIds wired — revocation state cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
   }
 
-  challenge(req: VerifiedStreamRequirements): X402StreamChallenge {
+  challenge(req: VerifiedStreamRequirements): StreamChallenge {
     const requirements = verifiedStreamRequirementsSchema.parse(req);
     assertSettlementTarget(requirements, this.sdkConfig);
-    return { scheme: X402_SCHEME, requirements };
+    return { scheme: METRIK_STREAM_SCHEME, requirements };
   }
 
   async open(payloadHeader: string): Promise<{ streamId: `0x${string}` }> {
-    const payload = parseX402PayloadHeader(payloadHeader);
+    const payload = parseStreamPayloadHeader(payloadHeader);
     assertSettlementTarget(payload.challenge.requirements, this.sdkConfig);
 
     // FAIL-CLOSED fund safety (B6). Both the cumulative-cap accounting and the
@@ -209,12 +237,12 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     // returns a non-bigint/negative spend is treated as "state cannot be
     // verified" and DENIES the open — never a silent fail-open to 0/none.
     if (this.resolveSpentSoFarUsdc === undefined) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot open verified stream: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified (fail-closed)",
       );
     }
     if (this.resolveRevokedMandateIds === undefined) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot open verified stream: no resolveRevokedMandateIds wired — mandate revocation state cannot be verified (fail-closed)",
       );
     }
@@ -223,14 +251,14 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     try {
       spentSoFarUsdc = await this.resolveSpentSoFarUsdc(payload.signedMandate);
     } catch (error) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         `cannot verify mandate cumulative cap (maxTotalUsdc): ${
           error instanceof Error ? error.message : String(error)
         } (fail-closed)`,
       );
     }
     if (typeof spentSoFarUsdc !== "bigint" || spentSoFarUsdc < 0n) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot verify mandate cumulative cap (maxTotalUsdc): resolver returned an invalid spent-so-far value (fail-closed)",
       );
     }
@@ -241,7 +269,7 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
         payload.signedMandate,
       );
     } catch (error) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         `cannot verify mandate revocation state: ${
           error instanceof Error ? error.message : String(error)
         } (fail-closed)`,
@@ -254,7 +282,7 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
         Symbol.iterator
       ] !== "function"
     ) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot verify mandate revocation state: resolver returned a non-iterable value (fail-closed)",
       );
     }
@@ -275,11 +303,11 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
   }
 
   async proveConsumedHttpsResponse(
-    input: X402ConsumedHttpsResponseProofInput,
+    input: ConsumedHttpsResponseProofInput,
   ): Promise<VerifiedConsumedHttpsResponseProof> {
     if (this.deliveryProofs === undefined) {
       throw new DeliveryProofUnavailableError(
-        "zkTLS delivery proofs are not configured on this x402 facilitator",
+        "zkTLS delivery proofs are not configured on this Metrik verified-stream facilitator",
       );
     }
 
@@ -317,42 +345,52 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
   }
 }
 
-export function encodeX402PayloadHeader(payload: X402OpenPayload): string {
-  const parsed = x402OpenPayloadSchema.parse(payload);
-  const token = Buffer.from(stringifyX402Payload(parsed)).toString("base64url");
-  return `${X402_SCHEME} ${token}`;
+export function encodeStreamPayloadHeader(payload: StreamOpenPayload): string {
+  const parsed = streamOpenPayloadSchema.parse(payload);
+  const token = Buffer.from(stringifyStreamPayload(parsed)).toString(
+    "base64url",
+  );
+  return `${METRIK_STREAM_SCHEME} ${token}`;
 }
 
-export function parseX402ChallengeJson(value: unknown): X402StreamChallenge {
-  const parsed = x402StreamChallengeSchema.safeParse(reviveBigInts(value));
+export function parseStreamChallengeJson(value: unknown): StreamChallenge {
+  const parsed = streamChallengeSchema.safeParse(reviveBigInts(value));
   if (!parsed.success) {
-    throw new X402PayloadError(
+    throw new StreamPayloadError(
       parsed.error.issues.map((issue) => issue.message).join("; "),
     );
   }
   return parsed.data;
 }
 
-export function parseX402PayloadHeader(payloadHeader: string): X402OpenPayload {
+export function parseStreamPayloadHeader(
+  payloadHeader: string,
+): StreamOpenPayload {
   const [scheme, token] = payloadHeader.split(" ", 2);
-  if (scheme !== X402_SCHEME || token === undefined || token.trim() === "") {
-    throw new X402PayloadError("invalid x402 verified-stream payload header");
+  if (
+    scheme !== METRIK_STREAM_SCHEME ||
+    token === undefined ||
+    token.trim() === ""
+  ) {
+    throw new StreamPayloadError(
+      "invalid Metrik verified-stream payload header",
+    );
   }
 
   let decoded: unknown;
   try {
     decoded = JSON.parse(Buffer.from(token, "base64url").toString("utf8"));
   } catch (error) {
-    throw new X402PayloadError(
-      `invalid x402 verified-stream payload encoding: ${
+    throw new StreamPayloadError(
+      `invalid Metrik verified-stream payload encoding: ${
         error instanceof Error ? error.message : String(error)
       }`,
     );
   }
 
-  const parsed = x402OpenPayloadSchema.safeParse(reviveBigInts(decoded));
+  const parsed = streamOpenPayloadSchema.safeParse(reviveBigInts(decoded));
   if (!parsed.success) {
-    throw new X402PayloadError(
+    throw new StreamPayloadError(
       parsed.error.issues.map((issue) => issue.message).join("; "),
     );
   }
@@ -381,7 +419,7 @@ function assertSettlementTarget(
   }
 }
 
-function stringifyX402Payload(payload: X402OpenPayload): string {
+function stringifyStreamPayload(payload: StreamOpenPayload): string {
   return JSON.stringify(payload, (_key, value) =>
     typeof value === "bigint" ? `${value.toString()}n` : value,
   );
@@ -404,3 +442,44 @@ function reviveBigInts(value: unknown): unknown {
 
   return value;
 }
+
+/* -------------------------------------------------------------------------- */
+/* Deprecated `x402`-flavoured aliases.                                        */
+/*                                                                             */
+/* These names are misleading — this flow is Metrik-native and not x402 (see   */
+/* `docs/x402.md`). They are retained as aliases bound to the SAME values and  */
+/* class objects as the canonical exports above, so existing consumers and     */
+/* `instanceof` checks keep working. Prefer the canonical names.               */
+/* -------------------------------------------------------------------------- */
+
+export {
+  /** @deprecated Use {@link METRIK_STREAM_SCHEME}. This flow is not x402. */
+  METRIK_STREAM_SCHEME as X402_SCHEME,
+  /** @deprecated Use {@link VerifiedStreamFacilitator}. This flow is not x402. */
+  VerifiedStreamFacilitator as VerifiedStreamX402Facilitator,
+  /** @deprecated Use {@link StreamPayloadError}. Same class object. */
+  StreamPayloadError as X402PayloadError,
+  /** @deprecated Use {@link SpendControlUnavailableError}. Same class object. */
+  SpendControlUnavailableError as X402SpendControlUnavailableError,
+  /** @deprecated Use {@link streamChallengeSchema}. */
+  streamChallengeSchema as x402StreamChallengeSchema,
+  /** @deprecated Use {@link streamOpenPayloadSchema}. */
+  streamOpenPayloadSchema as x402OpenPayloadSchema,
+  /** @deprecated Use {@link encodeStreamPayloadHeader}. */
+  encodeStreamPayloadHeader as encodeX402PayloadHeader,
+  /** @deprecated Use {@link parseStreamPayloadHeader}. */
+  parseStreamPayloadHeader as parseX402PayloadHeader,
+  /** @deprecated Use {@link parseStreamChallengeJson}. */
+  parseStreamChallengeJson as parseX402ChallengeJson,
+};
+
+export type {
+  /** @deprecated Use {@link StreamFacilitator}. This flow is not x402. */
+  StreamFacilitator as X402Facilitator,
+  /** @deprecated Use {@link StreamChallenge}. */
+  StreamChallenge as X402StreamChallenge,
+  /** @deprecated Use {@link StreamOpenPayload}. */
+  StreamOpenPayload as X402OpenPayload,
+  /** @deprecated Use {@link ConsumedHttpsResponseProofInput}. */
+  ConsumedHttpsResponseProofInput as X402ConsumedHttpsResponseProofInput,
+};

package/src/x402/payment-requirements.ts

@@ -0,0 +1,231 @@
+import type { Address, Hex } from "viem";
+import { getAddress, isAddress, isHex } from "viem";
+// TYPE-ONLY import: erased at compile time, so the core package never gains a
+// runtime dependency on `x402`. The shape is still pinned to the real library —
+// `test/x402-facilitator-conformance.test.ts` parses what this module builds
+// with the REAL `PaymentRequirementsSchema`, so a drift in either direction
+// fails CI rather than shipping.
+import type { PaymentRequirements } from "x402/types";
+
+/**
+ * Standard x402 `exact` payment requirements, built from an OPERATOR-SIGNED
+ * Metrik listing.
+ *
+ * This is the "additional way in" described in `docs/x402.md`: the Metrik
+ * verified-stream flow (`./facilitator.ts`) is unchanged and is still the only
+ * path with recoverable escrow. What this module adds is the ability for a
+ * seller's gateway to ALSO quote an ordinary, fully conformant x402 `exact`
+ * price for a single call, so an agent holding nothing but `x402-fetch` can pay
+ * without knowing Metrik exists.
+ *
+ * ## What is signed and what is not
+ *
+ * `payTo` is derived from the operator's EIP-712-signed service descriptor and
+ * from nothing else. It is never read from configuration and never read from a
+ * caller-supplied field, because `payTo` is the one field whose corruption
+ * silently redirects money.
+ *
+ * The PRICE is not signed. The descriptor schema (`@absol-labs/shared`) carries
+ * `minRatePerSecond` / `maxRatePerSecond` for metered streams and has no
+ * per-call price field, so a per-call x402 amount can only come from the seller
+ * running the gateway. That is legitimate — it is the seller's own price on the
+ * seller's own gateway — but a buyer CANNOT cross-check it against the registry
+ * the way they can cross-check `payTo`. Said plainly here so nobody assumes a
+ * guarantee that does not exist.
+ */
+
+/** The only x402 protocol version implemented by the published `x402` package. */
+export const X402_VERSION = 1 as const;
+
+/** The only x402 payment scheme implemented by the published `x402` package. */
+export const X402_EXACT_SCHEME = "exact" as const;
+
+/** x402 v1 uses bare network names, not CAIP-2. Metrik settles on Base only. */
+export const X402_NETWORK_BY_CHAIN_ID: Readonly<
+  Record<number, "base" | "base-sepolia">
+> = Object.freeze({
+  8453: "base",
+  84532: "base-sepolia",
+});
+
+export interface X402AssetConfig {
+  readonly address: Address;
+  /** EIP-712 domain `name` of the asset, needed to sign EIP-3009 offline. */
+  readonly eip712Name: string;
+  /** EIP-712 domain `version` of the asset. */
+  readonly eip712Version: string;
+  readonly decimals: number;
+}
+
+/**
+ * USDC per Base chain. The EIP-712 domain values are what a client needs to
+ * sign `TransferWithAuthorization` WITHOUT an extra RPC round trip: the x402
+ * client falls back to reading `version()` on chain only when
+ * `PaymentRequirements.extra` omits it, so quoting them here removes a network
+ * dependency from the payer's hot path.
+ *
+ * Base Sepolia values read from the live contract on 2026-09-18
+ * (`name() == "USDC"`, `version() == "2"`).
+ */
+export const X402_USDC_BY_CHAIN_ID: Readonly<Record<number, X402AssetConfig>> =
+  Object.freeze({
+    8453: Object.freeze({
+      address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as Address,
+      eip712Name: "USD Coin",
+      eip712Version: "2",
+      decimals: 6,
+    }),
+    84532: Object.freeze({
+      address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as Address,
+      eip712Name: "USDC",
+      eip712Version: "2",
+      decimals: 6,
+    }),
+  });
+
+export class X402RequirementsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "X402RequirementsError";
+  }
+}
+
+/**
+ * The minimum a payee must prove. Both fields MUST be projected from the
+ * operator-signed descriptor (see `../discovery/registry.ts`, which recovers the
+ * EIP-712 signer and re-derives `serviceRef` from the signed content), never
+ * from an unsigned registry column and never from a request.
+ */
+export interface SignedListingPayee {
+  readonly serviceRef: Hex;
+  readonly operator: Address;
+}
+
+export interface BuildMetrikPaymentRequirementsInput {
+  readonly listing: SignedListingPayee;
+  /** Absolute URL of the paid resource, as the buyer will request it. */
+  readonly resource: string;
+  /** Price for ONE call, in the asset's base units (micro-USDC at 6 decimals). */
+  readonly priceBaseUnits: bigint;
+  readonly chainId: number;
+  readonly description?: string;
+  readonly mimeType?: string;
+  /** How long the signed authorization stays valid. Default 60s. */
+  readonly maxTimeoutSeconds?: number;
+  readonly outputSchema?: Record<string, unknown>;
+  /** Override the settlement asset (defaults to USDC for `chainId`). */
+  readonly asset?: X402AssetConfig;
+}
+
+/** Default authorization validity window quoted to payers, in seconds. */
+export const DEFAULT_X402_MAX_TIMEOUT_SECONDS = 60;
+
+/**
+ * Builds standard-`exact` `PaymentRequirements` for one call of a Metrik-listed
+ * resource. Throws rather than emitting anything a conformant client would
+ * reject or a payer could be harmed by.
+ */
+export function buildMetrikPaymentRequirements(
+  input: BuildMetrikPaymentRequirementsInput,
+): PaymentRequirements {
+  const network = X402_NETWORK_BY_CHAIN_ID[input.chainId];
+  if (network === undefined) {
+    throw new X402RequirementsError(
+      `x402 v1 has no network name for chain ${input.chainId} (Metrik settles on Base: 8453, 84532)`,
+    );
+  }
+  const asset = input.asset ?? X402_USDC_BY_CHAIN_ID[input.chainId];
+  if (asset === undefined) {
+    throw new X402RequirementsError(
+      `no default settlement asset known for chain ${input.chainId}`,
+    );
+  }
+  if (!isAddress(input.listing.operator)) {
+    throw new X402RequirementsError(
+      "listing.operator must be an EVM address (it becomes payTo)",
+    );
+  }
+  if (
+    !isHex(input.listing.serviceRef, { strict: true }) ||
+    input.listing.serviceRef.length !== 66
+  ) {
+    throw new X402RequirementsError(
+      "listing.serviceRef must be a 32-byte hex value",
+    );
+  }
+  if (input.priceBaseUnits <= 0n) {
+    throw new X402RequirementsError(
+      "priceBaseUnits must be positive — a zero-priced x402 quote is not a payment",
+    );
+  }
+  let resource: URL;
+  try {
+    resource = new URL(input.resource);
+  } catch {
+    throw new X402RequirementsError(`resource must be an absolute URL`);
+  }
+  const maxTimeoutSeconds =
+    input.maxTimeoutSeconds ?? DEFAULT_X402_MAX_TIMEOUT_SECONDS;
+  if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds <= 0) {
+    throw new X402RequirementsError(
+      "maxTimeoutSeconds must be a positive integer",
+    );
+  }
+
+  return {
+    scheme: X402_EXACT_SCHEME,
+    network,
+    maxAmountRequired: input.priceBaseUnits.toString(),
+    resource: resource.toString(),
+    description:
+      input.description ??
+      "One call to a Metrik-listed service. Metrik's facilitator refuses to settle this payment while its oracle reports the service as failing.",
+    mimeType: input.mimeType ?? "application/json",
+    payTo: getAddress(input.listing.operator),
+    maxTimeoutSeconds,
+    asset: getAddress(asset.address),
+    extra: {
+      // Required by the x402 `exact` EVM binding so the payer can sign the
+      // EIP-3009 authorization offline.
+      name: asset.eip712Name,
+      version: asset.eip712Version,
+      // ADVISORY ONLY. The facilitator NEVER reads this to decide anything: it
+      // arrives inside a caller-supplied request body, so trusting it would let
+      // a caller pick which service's delivery record gets checked. The
+      // facilitator re-derives the service from `resource` against its own
+      // registry view. Published purely so a client can look the listing up.
+      metrikServiceRef: input.listing.serviceRef,
+    },
+    ...(input.outputSchema === undefined
+      ? {}
+      : { outputSchema: input.outputSchema }),
+  };
+}
+
+/**
+ * The HTTP `402` response body a resource server returns.
+ *
+ * NOTE on `error`: the shipped `x402ResponseSchema` types `error` as the closed
+ * `ErrorReasons` enum, which no real x402 server obeys — `x402-express` and
+ * friends put human-readable text there, and `x402-fetch` never reads the field
+ * at all. Metrik follows the real-world behaviour (free text) rather than the
+ * schema; `test/x402-facilitator-conformance.test.ts` pins that divergence so it
+ * is a recorded decision and not an accident.
+ */
+export interface X402PaymentRequiredBody {
+  readonly x402Version: typeof X402_VERSION;
+  readonly error: string;
+  readonly accepts: readonly PaymentRequirements[];
+}
+
+export function buildX402PaymentRequiredBody(
+  accepts: readonly PaymentRequirements[],
+  error = "X-PAYMENT header is required",
+): X402PaymentRequiredBody {
+  if (accepts.length === 0) {
+    throw new X402RequirementsError(
+      "a 402 must advertise at least one PaymentRequirements",
+    );
+  }
+  return { x402Version: X402_VERSION, error, accepts };
+}

package/src/x402/relayer.ts

@@ -0,0 +1,122 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  publicActions,
+  type Chain,
+  type Hex,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base, baseSepolia } from "viem/chains";
+import { settle as x402Settle, verify as x402Verify } from "x402/facilitator";
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+  SettleResponse,
+  VerifyResponse,
+} from "x402/types";
+
+import type {
+  PaymentSettler,
+  PaymentVerifier,
+} from "./verified-delivery-facilitator.js";
+
+/**
+ * Chain wiring for the payment half of Metrik's x402 facilitator.
+ *
+ * Nothing here is Metrik-specific: verification and settlement are delegated
+ * VERBATIM to the real `x402/facilitator` implementation of the `exact` scheme.
+ * Metrik does not reimplement EIP-3009, and a change in the library's rules is
+ * inherited rather than drifted away from. The Metrik-specific part — the
+ * delivery gate — lives entirely in `./verified-delivery-facilitator.ts` and is
+ * layered ON TOP of whatever this returns.
+ */
+
+export const X402_CHAINS: Readonly<Record<number, Chain>> = Object.freeze({
+  8453: base,
+  84532: baseSepolia,
+});
+
+export interface X402ChainOptions {
+  /** Default `84532` (Base Sepolia). */
+  readonly chainId?: number;
+  /** RPC endpoint. Required: the library's default public RPCs are not operable infrastructure. */
+  readonly rpcUrl: string;
+}
+
+function chainFor(chainId: number): Chain {
+  const chain = X402_CHAINS[chainId];
+  if (chain === undefined) {
+    throw new Error(`unsupported x402 settlement chain: ${chainId}`);
+  }
+  return chain;
+}
+
+/**
+ * Read-only verifier. Needs an RPC because the `exact` scheme checks the payer's
+ * on-chain balance; it holds no key and can broadcast nothing.
+ */
+export function createX402PaymentVerifier(
+  options: X402ChainOptions,
+): PaymentVerifier {
+  const chain = chainFor(options.chainId ?? 84532);
+  const client = createPublicClient({
+    chain,
+    transport: http(options.rpcUrl),
+  });
+  return {
+    verify(
+      payload: PaymentPayload,
+      requirements: PaymentRequirements,
+    ): Promise<VerifyResponse> {
+      return x402Verify(
+        client as Parameters<typeof x402Verify>[0],
+        payload,
+        requirements,
+      );
+    },
+  };
+}
+
+export interface X402RelayerOptions extends X402ChainOptions {
+  /**
+   * The relayer's private key. This wallet BROADCASTS and pays gas; it never
+   * custodies payment funds (EIP-3009 moves value directly from payer to payee).
+   * Supplied by the operator through the environment, exactly like every other
+   * wallet in this package. Never committed, never defaulted.
+   */
+  readonly privateKey: Hex;
+}
+
+/**
+ * The settlement half. Constructing this is the ONLY place a key enters the
+ * facilitator, and there is no code path that broadcasts without one.
+ */
+export function createX402PaymentSettler(
+  options: X402RelayerOptions,
+): PaymentSettler {
+  const chain = chainFor(options.chainId ?? 84532);
+  const account = privateKeyToAccount(options.privateKey);
+  const signer = createWalletClient({
+    account,
+    chain,
+    transport: http(options.rpcUrl),
+  }).extend(publicActions);
+  return {
+    settle(
+      payload: PaymentPayload,
+      requirements: PaymentRequirements,
+    ): Promise<SettleResponse> {
+      return x402Settle(
+        signer as Parameters<typeof x402Settle>[0],
+        payload,
+        requirements,
+      );
+    },
+  };
+}
+
+/** The relayer address, so an operator can check what they must fund with gas. */
+export function relayerAddress(privateKey: Hex): `0x${string}` {
+  return privateKeyToAccount(privateKey).address;
+}