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

package/src/cli/commands/pay.ts

@@ -0,0 +1,584 @@
+import type { X402PayerSigner, X402QuoteSummary } from "@absol-labs/sdk/x402";
+
+import {
+  DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+  parseServerMandateCapsEnv,
+  signServerMandate,
+  type ServerMandateCaps,
+} from "../../mandates/env.js";
+import {
+  booleanFlag,
+  integerFlag,
+  jsonBodyFlag,
+  stringFlag,
+  stringFlags,
+} from "../args.js";
+import {
+  formatDuration,
+  formatUsdc,
+  parseAmountUnits,
+  parseDurationSeconds,
+  parseUsdcAmount,
+} from "../amounts.js";
+import { assertTestnetRpc } from "../config.js";
+import { rpcTransport, type CliX402 } from "../deps.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { usdcFundingHint } from "../../network.js";
+import {
+  CDP_ENV_VARS,
+  PRIVATE_KEY_ENV,
+  isPrivyWalletSource,
+  resolveCliWallet,
+} from "../wallet.js";
+import { hasHeader, parseHeaders } from "./invoke.js";
+import type { X402PostSignatureError } from "../../x402-buyer/pay.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/** Default stream window a request-sized mandate allows (one day). */
+const DEFAULT_MAX_DURATION_SECONDS = 86_400;
+/** Longest response body printed in human mode before it is truncated. */
+const MAX_PRINTED_BODY_CHARS = 64 * 1024;
+
+export const payCommand: CommandSpec = {
+  name: "pay",
+  summary:
+    "Pay an x402 endpoint into a recoverable escrow stream, under a spend mandate",
+  usage:
+    'metrik pay <url> [--json \'{"text":"hi"}\' | --data <body>] [--method POST] [--header "K: V"] --max-amount <usdc> [--max-rate <usdc/s>] [--max-upfront <usdc>] [--max-duration <seconds>] [--min-duration <seconds>] [--operator <address>] [--units atomic]',
+  flags: [
+    "data",
+    "json-body",
+    "method",
+    "header",
+    "max-amount",
+    "max-rate",
+    "max-upfront",
+    "max-duration",
+    "min-duration",
+    "operator",
+    "units",
+    "allow-legacy-factory",
+  ],
+  // It moves the payer's USDC (an EIP-3009 authorization the facilitator
+  // settles into the escrow). The PAYER broadcasts nothing and needs no gas,
+  // but it is a fund-moving command and is gated like one.
+  signs: true,
+  // ...so the generic "Broadcasts a transaction" help would be false, and so
+  // would listing Privy: the command refuses a Privy wallet (its broker does
+  // not sign EIP-3009). Say what actually happens.
+  walletHelp: {
+    tag: "[signs a USDC payment]",
+    text:
+      "Broadcasts nothing and needs no gas: the payer signs an EIP-3009 USDC authorization (TransferWithAuthorization) " +
+      "that the seller's facilitator settles into an escrow stream. Requires a wallet holding USDC in the environment: " +
+      `${PRIVATE_KEY_ENV} or ${CDP_ENV_VARS.join(" + ")}. A Privy wallet cannot pay x402: its broker does not sign EIP-3009.`,
+  },
+  flagHelp: {
+    "max-upfront":
+      "--max-upfront <usdc> (cap on the NON-REFUNDABLE per-call part of an upfront-opener quote; default 0.10 USDC, 0 refuses any)",
+    data: "--data <body>",
+    "json-body": "--json <body> (alias: --json-body <body>)",
+  },
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const x402 = requireX402(deps.x402);
+    const [urlArg] = args.positionals;
+    if (urlArg === undefined) {
+      throw usageError("metrik pay requires the <url> of an x402 endpoint");
+    }
+    const url = parseResourceUrl(urlArg);
+    const units = parseAmountUnits(stringFlag(args, "units"));
+    const maxAmountRaw = stringFlag(args, "max-amount");
+    const maxAmount =
+      maxAmountRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxAmountRaw, units, "max-amount");
+    const maxRateRaw = stringFlag(args, "max-rate");
+    const maxRate =
+      maxRateRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxRateRaw, units, "max-rate");
+    const maxUpfrontRaw = stringFlag(args, "max-upfront");
+    const maxUpfront =
+      maxUpfrontRaw === undefined
+        ? undefined
+        : parseUsdcAmount(maxUpfrontRaw, units, "max-upfront");
+    const maxDurationRaw = stringFlag(args, "max-duration");
+    const maxDuration =
+      maxDurationRaw === undefined
+        ? undefined
+        : parseDurationSeconds(maxDurationRaw);
+    const minDuration = integerFlag(args, "min-duration");
+    const operator = stringFlag(args, "operator");
+    if (operator !== undefined && !/^0x[0-9a-fA-F]{40}$/.test(operator)) {
+      throw usageError(`--operator must be an EVM address (got "${operator}")`);
+    }
+    if (maxAmount !== undefined && maxAmount <= 0n) {
+      throw usageError("--max-amount must be greater than zero");
+    }
+    if (maxRate !== undefined && maxRate <= 0n) {
+      throw usageError("--max-rate must be greater than zero");
+    }
+
+    const init = buildRequest(context);
+
+    // The mandate: an operator-set standing ceiling (METRIK_AGENT_MANDATE_*),
+    // or one sized to exactly this payment. Either way it is SIGNED and
+    // `checkMandate()` gates the quote before anything is signed for the
+    // seller. There is no unbounded path: without standing caps, --max-amount
+    // is required.
+    const envCaps = parseServerMandateCapsEnv(env);
+    if (envCaps === null && maxAmount === undefined) {
+      throw usageError(
+        "metrik pay needs a spend ceiling: pass --max-amount <usdc> (or configure a standing mandate with METRIK_AGENT_MANDATE_*)",
+        "no spend without a mandate: the seller picks the price, so the buyer must cap it. Nothing was sent.",
+      );
+    }
+    const caps = intersectCaps(envCaps, {
+      maxAmount,
+      maxRate,
+      maxDuration,
+      operator: operator as `0x${string}` | undefined,
+    });
+
+    const wallet = await resolveCliWallet(env, {
+      purpose: "x402-payment",
+      note: out.note,
+      rpcUrl: config.rpcUrl,
+    });
+    if (isPrivyWalletSource(wallet.source)) {
+      throw configError(
+        "metrik pay cannot sign with a Privy wallet",
+        "an x402 payment is an EIP-3009 TransferWithAuthorization signature, and the Privy broker's typed-data policy allows only an InvocationCapability. Pay with METRIK_AGENT_PRIVATE_KEY or a CDP wallet.",
+      );
+    }
+    const { account } = wallet;
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    // The payer needs USDC only — no gas: the facilitator's relayer submits
+    // the authorization. A zero balance is a knowable fact before signing.
+    const balance = await read.usdcBalance(account.address).catch(() => null);
+    if (balance === 0n) {
+      throw new CliError(
+        `wallet ${account.address} holds 0 USDC on ${config.network.name}, so it cannot pay`,
+        {
+          exitCode: 3,
+          hint: `${usdcFundingHint(config.network)}, then re-run. (An x402 payer needs USDC only; no gas.)`,
+        },
+      );
+    }
+
+    const signedMandate = await signServerMandate(account, caps, {
+      chainId: config.chainId,
+    });
+
+    out.note(
+      `paying ${url} (ceiling ${formatUsdc(maxAmount === undefined ? caps.maxPerStreamUsdc : maxAmount < caps.maxPerStreamUsdc ? maxAmount : caps.maxPerStreamUsdc)}, mandate from ${envCaps === null ? "this command" : "METRIK_AGENT_MANDATE_*"}) …`,
+    );
+    const result = await payOrExplain(x402, {
+      url,
+      init,
+      signer: account as unknown as X402PayerSigner,
+      network: config.network,
+      signedMandate,
+      spentSoFarUsdc: 0n,
+      nowSeconds: deps.nowSeconds(),
+      ...(maxAmount === undefined ? {} : { maxAmount }),
+      ...(maxRate === undefined ? {} : { maxRatePerSecond: maxRate }),
+      ...(minDuration === undefined ? {} : { minDurationSeconds: minDuration }),
+      ...(maxUpfront === undefined ? {} : { maxUpfrontAmount: maxUpfront }),
+      // The split, stated BEFORE anything is signed (the mandate approved the
+      // quote; the SDK signs right after this).
+      onApproved: ({ quote }) => {
+        out.note(describeQuoteSplit(quote));
+      },
+      sdkOptions: {
+        transport: rpcTransport(config),
+        // A LEGACY deployment's factory is refused by the SDK unless the
+        // buyer opts in: streams there can still be closed and reclaimed, but
+        // nothing new should open on a generation being retired by default.
+        ...(booleanFlag(args, "allow-legacy-factory")
+          ? { allowLegacyFactory: true }
+          : {}),
+      },
+    });
+
+    const bodyText = await result.response.text();
+    const opener = result.metrikStreamOpener;
+    const quote = result.quote;
+    const settlementTx = settlementTransaction(result.paymentResponse);
+    out.result({
+      paid: result.paid,
+      // The facilitator's settlement transaction, from the PAYMENT-RESPONSE
+      // header the seller relayed: the facilitator's relayer broadcast it, not
+      // the payer. Reported as-is; null when the header carries none.
+      settlementTransaction: settlementTx,
+      settlementTransactionSource:
+        settlementTx === null ? null : "PAYMENT-RESPONSE",
+      httpStatus: result.response.status,
+      contentType: result.response.headers.get("content-type"),
+      body: bodyText,
+      streamId: opener?.streamId ?? null,
+      opener: opener?.opener ?? null,
+      refundUrl: opener?.refundUrl ?? null,
+      escrow: opener?.escrow ?? null,
+      deposit: opener?.deposit ?? null,
+      openerKind: quote?.openerKind ?? null,
+      price: quote?.amount ?? null,
+      // The NON-REFUNDABLE part (paid to the seller at settlement) and the
+      // metered, refundable part (the most any refund can return).
+      upfrontAmount: quote?.upfrontAmount ?? null,
+      refundableAmount: quote?.refundableAmount ?? null,
+      upfrontFee: opener?.upfrontFee ?? null,
+      upfrontOnly: opener?.upfrontOnly ?? quote?.upfrontOnly ?? null,
+      // True for an upfront-only payment: nothing was escrowed, nothing to refund.
+      final: opener?.upfrontOnly === true,
+      ratePerSecond: opener?.ratePerSecond ?? null,
+      expiresAt: opener?.expiresAt ?? null,
+      operator: quote?.operator ?? null,
+      serviceRef: quote?.serviceRef ?? null,
+      minEarnSeconds: quote?.minEarnSeconds ?? null,
+      mandateSource: envCaps === null ? "request" : "env",
+      refundIsAutomatic: false,
+    });
+
+    if (!result.paid) {
+      out.print(
+        `The endpoint answered ${result.response.status} without asking for payment; nothing was signed or paid.`,
+      );
+      out.print(truncate(bodyText));
+      return;
+    }
+    out.print(`Paid. HTTP ${result.response.status}`);
+    out.print(truncate(bodyText));
+    out.print("");
+    if (opener !== null && opener.streamId === null) {
+      // Upfront-only: no stream exists, so there is no refund or reclaim to offer.
+      out.table([
+        ["opener", opener.opener],
+        ["payer", account.address],
+        ...splitRows(quote, opener.upfrontFee),
+        ...(settlementTx === null
+          ? []
+          : ([
+              [
+                "settlement tx",
+                `${settlementTx} (reported by the seller's facilitator in PAYMENT-RESPONSE; its relayer broadcast it)`,
+              ],
+            ] as const)),
+      ]);
+      out.print("");
+      out.print(
+        "This payment is FINAL: it was an upfront-only (minimum-charge) payment, the whole price was paid to the seller at settlement as a non-refundable per-call charge, and no escrow stream was opened. There is nothing to refund or reclaim.",
+      );
+      return;
+    }
+    if (opener !== null && opener.streamId !== null) {
+      out.table([
+        ["streamId", opener.streamId],
+        ["opener", opener.opener],
+        ["payer", account.address],
+        ...splitRows(quote, opener.upfrontFee),
+        ...(opener.deposit === null
+          ? []
+          : ([["deposit", formatUsdc(opener.deposit)]] as const)),
+        ...(opener.ratePerSecond === null
+          ? []
+          : ([
+              ["rate", `${formatUsdc(opener.ratePerSecond)} / verified second`],
+            ] as const)),
+        ...(quote?.minEarnSeconds === null ||
+        quote?.minEarnSeconds === undefined
+          ? []
+          : ([
+              [
+                "fully earned after",
+                `${formatDuration(Number(quote.minEarnSeconds))} of verified delivery`,
+              ],
+            ] as const)),
+        ...(opener.expiresAt === null
+          ? []
+          : ([
+              ["expires", new Date(opener.expiresAt * 1000).toISOString()],
+            ] as const)),
+        ["refund url", opener.refundUrl ?? "(the seller advertised no relay)"],
+        ...(settlementTx === null
+          ? []
+          : ([
+              [
+                "settlement tx",
+                `${settlementTx} (reported by the seller's facilitator in PAYMENT-RESPONSE; its relayer broadcast it)`,
+              ],
+            ] as const)),
+      ]);
+      out.print("");
+      // A stream on another (e.g. legacy) registered escrow is reached by
+      // naming that escrow; the CLI defaults to the network's current one.
+      const escrowFlag =
+        opener.escrow !== null &&
+        opener.escrow.toLowerCase() !== config.escrow.toLowerCase()
+          ? ` --escrow ${opener.escrow}`
+          : "";
+      out.print(
+        quote?.openerKind === "upfront" &&
+          quote.upfrontAmount !== null &&
+          quote.upfrontAmount > 0n
+          ? `Refunds are NOT automatic. The ${formatUsdc(quote.upfrontAmount)} upfront charge is final; of the ${formatUsdc(quote.refundableAmount ?? 0n)} escrowed, the seller earns only verified seconds, and whatever is unearned stays in the escrow until someone reclaims it for you:`
+          : "Refunds are NOT automatic. The seller earns only for verified seconds; whatever is unearned stays in the escrow until someone reclaims it for you:",
+      );
+      out.print(
+        opener.refundUrl === null
+          ? `  metrik reclaim ${opener.streamId}${escrowFlag}      (anyone may send it; the refund always goes to the payer)`
+          : `  metrik refund ${opener.streamId} --refund-url ${opener.refundUrl}${escrowFlag} --close --reclaim`,
+      );
+    }
+  },
+};
+
+/**
+ * One line stating what a quote commits the payer to, printed before signing:
+ * for an upfront-opener quote, the NON-REFUNDABLE per-call part and the
+ * metered, refundable part; for a stream quote, that all of it is metered.
+ */
+export function describeQuoteSplit(quote: X402QuoteSummary): string {
+  if (quote.openerKind === "upfront" && quote.upfrontAmount !== null) {
+    if (quote.upfrontOnly === true) {
+      return `quote: ${formatUsdc(quote.amount)}, ALL of it a NON-REFUNDABLE per-call charge (upfront-only: no stream is opened, nothing is metered, nothing can be refunded). Signing it.`;
+    }
+    return `quote: ${formatUsdc(quote.amount)} = ${formatUsdc(quote.upfrontAmount)} NON-REFUNDABLE per-call charge (paid to the seller at settlement) + ${formatUsdc(quote.refundableAmount ?? 0n)} metered and refundable (escrowed; the seller earns it only for verified seconds). Signing it.`;
+  }
+  return `quote: ${formatUsdc(quote.amount)}, all of it escrowed, metered and refundable (the seller earns it only for verified seconds). Signing it.`;
+}
+
+/** Table rows stating a paid quote's split (upfront quotes only). */
+function splitRows(
+  quote: X402QuoteSummary | null,
+  upfrontFee: bigint | null,
+): (readonly [string, string])[] {
+  if (quote === null || quote.openerKind !== "upfront") return [];
+  return [
+    ["price", formatUsdc(quote.amount)],
+    [
+      "non-refundable",
+      `${formatUsdc(quote.upfrontAmount ?? 0n)} (per-call charge, paid to the seller at settlement${upfrontFee === null ? "" : `; protocol fee ${formatUsdc(upfrontFee)} as the seller reports it`})`,
+    ],
+    [
+      "refundable",
+      `${formatUsdc(quote.refundableAmount ?? 0n)} (metered; the most any refund can return)`,
+    ],
+  ];
+}
+
+/**
+ * The settlement transaction hash from the facilitator's `PAYMENT-RESPONSE`,
+ * when it carries a well-formed one. Anything else (absent, empty, not a
+ * 32-byte hash) is `null`: a malformed value is never printed as a hash.
+ */
+export function settlementTransaction(
+  paymentResponse: { readonly transaction?: unknown } | null | undefined,
+): `0x${string}` | null {
+  const value = paymentResponse?.transaction;
+  return typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value)
+    ? (value as `0x${string}`)
+    : null;
+}
+
+const minBig = (a: bigint, b: bigint | undefined): bigint =>
+  b !== undefined && b < a ? b : a;
+
+/**
+ * The mandate this command signs: a standing `METRIK_AGENT_MANDATE_*` ceiling
+ * INTERSECTED with every flag (the most restrictive value wins), or, with no
+ * standing ceiling, one sized to the flags. A flag can only tighten a
+ * standing ceiling, never loosen or bypass it; an `--operator` outside a
+ * standing allowlist is refused outright.
+ */
+export function intersectCaps(
+  envCaps: ServerMandateCaps | null,
+  flags: {
+    readonly maxAmount: bigint | undefined;
+    readonly maxRate: bigint | undefined;
+    readonly maxDuration: number | undefined;
+    readonly operator: `0x${string}` | undefined;
+  },
+): ServerMandateCaps {
+  if (envCaps === null) {
+    const amount = flags.maxAmount as bigint;
+    return {
+      maxPerStreamUsdc: amount,
+      maxTotalUsdc: amount,
+      // No --max-rate: the price is the only cap on how fast the seller can
+      // earn it. Reported as minEarnSeconds so the buyer can see it.
+      maxRatePerSecondUsdc: flags.maxRate ?? amount,
+      maxDurationSeconds: flags.maxDuration ?? DEFAULT_MAX_DURATION_SECONDS,
+      allowedOperators: flags.operator === undefined ? [] : [flags.operator],
+      ttlSeconds: DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+    };
+  }
+  let allowedOperators = envCaps.allowedOperators;
+  if (flags.operator !== undefined) {
+    if (
+      allowedOperators.length > 0 &&
+      !allowedOperators.some(
+        (entry) => entry.toLowerCase() === flags.operator?.toLowerCase(),
+      )
+    ) {
+      throw new CliError(
+        `--operator ${flags.operator} is not in METRIK_AGENT_MANDATE_ALLOWED_OPERATORS`,
+        {
+          exitCode: 3,
+          hint: "a flag can only narrow the standing mandate, never widen it. Nothing was sent.",
+        },
+      );
+    }
+    allowedOperators = [flags.operator];
+  }
+  return {
+    maxPerStreamUsdc: minBig(envCaps.maxPerStreamUsdc, flags.maxAmount),
+    maxTotalUsdc: minBig(envCaps.maxTotalUsdc, flags.maxAmount),
+    maxRatePerSecondUsdc: minBig(envCaps.maxRatePerSecondUsdc, flags.maxRate),
+    maxDurationSeconds:
+      flags.maxDuration !== undefined &&
+      flags.maxDuration < envCaps.maxDurationSeconds
+        ? flags.maxDuration
+        : envCaps.maxDurationSeconds,
+    allowedOperators,
+    ttlSeconds: envCaps.ttlSeconds,
+  };
+}
+
+function requireX402(x402: CliX402 | undefined): CliX402 {
+  if (x402 === undefined) {
+    throw new CliError(
+      "this CLI build has no x402 dependency wired (CliDependencies.x402)",
+      { exitCode: 4 },
+    );
+  }
+  return x402;
+}
+
+function parseResourceUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw usageError(`<url> must be an absolute http(s) URL (got "${raw}")`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw usageError(`<url> must be http(s) (got "${url.protocol}")`);
+  }
+  return url.toString();
+}
+
+function buildRequest(context: CommandContext): RequestInit {
+  const { args } = context;
+  const data = stringFlag(args, "data");
+  const jsonValue = jsonBodyFlag(args);
+  const jsonAlias = stringFlag(args, "json-body");
+  if (jsonValue !== undefined && jsonAlias !== undefined) {
+    throw usageError(
+      "give the JSON body once: --json <body> or --json-body <body>",
+    );
+  }
+  const jsonBody = jsonValue ?? jsonAlias;
+  if (data !== undefined && jsonBody !== undefined) {
+    throw usageError("give either --data or --json <body>, not both");
+  }
+  if (jsonBody !== undefined) {
+    try {
+      JSON.parse(jsonBody);
+    } catch {
+      throw usageError("--json <body> must be valid JSON");
+    }
+  }
+  const body = jsonBody ?? data;
+  const method = (
+    stringFlag(args, "method") ?? (body === undefined ? "GET" : "POST")
+  ).toUpperCase();
+  const headers = parseHeaders(stringFlags(args, "header"));
+  if (jsonBody !== undefined && !hasHeader(headers, "content-type")) {
+    headers["content-type"] = "application/json";
+  }
+  for (const name of Object.keys(headers)) {
+    if (name === "payment-signature" || name === "x-payment") {
+      throw usageError(
+        `do not set the ${name} header: the payment is signed by this command, after the quote passes the mandate`,
+      );
+    }
+  }
+  return {
+    method,
+    headers,
+    ...(body === undefined ? {} : { body }),
+  };
+}
+
+function truncate(text: string): string {
+  return text.length <= MAX_PRINTED_BODY_CHARS
+    ? text
+    : `${text.slice(0, MAX_PRINTED_BODY_CHARS)}\n… (${text.length - MAX_PRINTED_BODY_CHARS} more characters; use --json for the whole body)`;
+}
+
+async function payOrExplain(
+  x402: CliX402,
+  input: Parameters<CliX402["pay"]>[0],
+): ReturnType<CliX402["pay"]> {
+  try {
+    return await x402.pay(input);
+  } catch (error) {
+    throw explainPayFailure(error);
+  }
+}
+
+/** Map the SDK's and the mandate's typed failures onto CLI exit codes. */
+export function explainPayFailure(error: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  switch (error.name) {
+    case "X402MandateDeniedError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: "raise --max-amount / --max-rate / --max-duration (or METRIK_AGENT_MANDATE_*) only if you mean to pay that much, that fast, for that long.",
+        cause: error,
+      });
+    case "X402PaymentRefusedError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: /maxUpfrontAmount/.test(error.message)
+          ? "the quote's NON-REFUNDABLE upfront (per-call) charge is above your cap (--max-upfront, default 0.10 USDC). Raise --max-upfront only if you accept losing that much per call whatever is delivered. Nothing was signed."
+          : /exceeds maxAmount|exceeds maxRatePerSecond/.test(error.message)
+            ? "that ceiling is your spend mandate's (--max-amount / --max-rate or METRIK_AGENT_MANDATE_*), handed to the SDK as a second gate. Nothing was signed."
+            : "the quote failed one of the SDK's protections (wrong network or token, unknown factory, payTo != factory.predict(terms), invalid upfront terms, not an opener payment, ...). Nothing was signed.",
+        cause: error,
+      });
+    case "X402PostSignatureError": {
+      // The signature was handed out: never say "nothing moved" unless the
+      // chain proves the authorization can never be used.
+      const post = error as X402PostSignatureError;
+      if (post.upfrontOnly && post.state === "used") {
+        return new CliError(error.message, {
+          exitCode: 4,
+          hint: "the money LEFT the payer as an upfront-only (minimum-charge) payment: the whole price was a non-refundable per-call charge and no stream was opened, so there is nothing to refund or reclaim. Keep this output as evidence if the response was not delivered (see docs/x402.md).",
+          cause: error,
+        });
+      }
+      const recover =
+        post.streamId === null
+          ? ""
+          : ` Recover the unearned part: metrik refund ${post.streamId} --refund-url <the seller's relay> --close --reclaim (or metrik reclaim ${post.streamId}).`;
+      return new CliError(error.message, {
+        exitCode: 4,
+        hint:
+          post.state === "used"
+            ? `the money LEFT the payer.${post.streamId === null ? " Its stream could not be identified on-chain; keep this output as evidence (see docs/x402.md)." : ` It is in stream ${post.streamId} (opener ${post.opener}).`}${recover}`
+            : post.state === "possibly-used"
+              ? "whether the authorization was used could not be established: treat the payment as SPENT and check USDC.authorizationState before paying again (see docs/x402.md)."
+              : post.state === "unused-but-valid"
+                ? "it has not moved yet, but the seller holds a signature valid until its validBefore: treat it as spent, or cancel it with USDC.cancelAuthorization (needs gas). See docs/x402.md."
+                : "the authorization was never used and has expired: nothing moved.",
+        cause: error,
+      });
+    }
+    default:
+      return error;
+  }
+}

package/src/cli/commands/reclaim-unverified.ts

@@ -14,6 +14,7 @@ import { writeClientOptions } from "../deps.js";
 import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient } from "../deps.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 /**
  * The acknowledgement this command will not run without.
@@ -88,7 +89,7 @@ export const reclaimUnverifiedCommand: CommandSpec = {
     const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
-    await assertCanPayGas(read, account.address);
+    await assertCanPayGas(read, account.address, config.network);
 
     const stream = await read.getStreamV2(streamId);
     if (stream.reclaimed) {
@@ -107,7 +108,12 @@ export const reclaimUnverifiedCommand: CommandSpec = {
     // prevent.
     const grace = await readEscapeGrace(read);
     const now = await readChainNow(read, deps.nowSeconds());
-    const window = escapeHatchWindow(stream, grace, now.seconds);
+    const window = escapeHatchWindow(
+      stream,
+      grace,
+      now.seconds,
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
     if (!window.ready) {
       throw notReady(streamId, window, now.source);
     }