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

package/src/gateway/http-server.ts

@@ -20,12 +20,13 @@ import {
   DEFAULT_ORACLE_SIGNER_CACHE_SECONDS,
 } from "./probe-auth.js";
 import { PROBE_MARKER_HEADER_NAME } from "../capability/probe-capability.js";
-import { networkForCaip2 } from "@absol-labs/sdk";
+import { networkForCaip2, networkOpenerFactories } from "@absol-labs/sdk";
 import {
   chainIdFromNetwork,
   assertSchemaDeclaration,
   assertValidPrice,
   assertValidTerms,
+  assertValidUpfrontTerms,
   isHttpLink,
   type OpenerTerms,
   type X402SchemaDeclaration,
@@ -459,6 +460,13 @@ export interface CallerAuthGatewayX402OpenerEnvConfig {
   readonly assetVersion: string;
   readonly terms: OpenerTerms;
   readonly price: bigint;
+  /**
+   * `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT`: selects the upfront opener kind
+   * (then `factoryAddress` is the upfront factory). Undefined = stream kind.
+   */
+  readonly upfrontAmount?: bigint;
+  /** The registry's implementation of the upfront factory, when it records one. */
+  readonly upfrontImplementation?: Address;
   readonly maxTimeoutSeconds: number;
   /** Per-request facilitator HTTP timeout, ms. */
   readonly facilitatorTimeoutMs: number;
@@ -643,6 +651,16 @@ export function parseCallerAuthGatewayEnvConfig(
  * - `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS` (required).
  * - `METRIK_GATEWAY_X402V2_PRICE` (required) — base units per paid request (= deposit),
  *   `0 < price <= rate * maxDuration`.
+ * - `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT` — base units; when SET the listing
+ *   quotes the UPFRONT ("minimum charge") opener instead: `amount = price`,
+ *   `payTo = upfrontFactory.predict(6 terms)`; `upfrontAmount` is paid to the
+ *   seller at settlement and is NOT refundable, only `price - upfrontAmount`
+ *   (`<= rate * maxDuration`) is metered and refundable. `= PRICE` is
+ *   upfront-only (no stream). Validated with the factory's rules at startup.
+ * - `METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS` — the
+ *   `X402UpfrontStreamOpenerFactory`; default the network registry's (only
+ *   with `_UPFRONT_AMOUNT`). `_FACTORY_ADDRESS` names the STREAM factory and is
+ *   refused together with `_UPFRONT_AMOUNT`.
  * - `METRIK_GATEWAY_X402V2_NETWORK` — default `eip155:<METRIK_GATEWAY_CHAIN_ID>`.
  * - `METRIK_GATEWAY_X402V2_ASSET` — default the network's registered USDC.
  * - `METRIK_GATEWAY_X402V2_ASSET_NAME` / `_ASSET_VERSION` — EIP-712 domain, default the
@@ -699,8 +717,55 @@ export function parseGatewayX402OpenerEnvConfig(
   // Defaults come from the registry entry for THIS network only.
   const registered = networkForCaip2(network);
   const factoryRaw = env.METRIK_GATEWAY_X402V2_FACTORY_ADDRESS?.trim();
+  const upfrontRaw = env.METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT?.trim();
+  const upfrontFactoryRaw =
+    env.METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS?.trim();
+  const upfrontMode = upfrontRaw !== undefined && upfrontRaw.length > 0;
+  if (
+    !upfrontMode &&
+    upfrontFactoryRaw !== undefined &&
+    upfrontFactoryRaw.length > 0
+  ) {
+    throw new Error(
+      "METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS needs METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT (it selects the upfront opener)",
+    );
+  }
   let factoryAddress: Address;
-  if (factoryRaw === undefined || factoryRaw.length === 0) {
+  let upfrontImplementation: Address | undefined;
+  if (upfrontMode) {
+    if (factoryRaw !== undefined && factoryRaw.length > 0) {
+      throw new Error(
+        "METRIK_GATEWAY_X402V2_FACTORY_ADDRESS names the STREAM opener factory; with METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT set the listing quotes the upfront factory — set METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS (or nothing, for the registry's) instead",
+      );
+    }
+    const registeredUpfront =
+      registered === undefined
+        ? []
+        : networkOpenerFactories(registered).filter(
+            (entry) => entry.kind === "upfront",
+          );
+    if (upfrontFactoryRaw === undefined || upfrontFactoryRaw.length === 0) {
+      const current = registeredUpfront.find((entry) => !entry.legacy);
+      if (current === undefined) {
+        throw new Error(
+          `METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS is required on ${network}: the network registry has no upfront opener factory for it`,
+        );
+      }
+      factoryAddress = current.address;
+      upfrontImplementation = current.implementation ?? undefined;
+    } else if (isAddress(upfrontFactoryRaw)) {
+      factoryAddress = upfrontFactoryRaw;
+      upfrontImplementation =
+        registeredUpfront.find(
+          (entry) =>
+            entry.address.toLowerCase() === upfrontFactoryRaw.toLowerCase(),
+        )?.implementation ?? undefined;
+    } else {
+      throw new Error(
+        "METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS must be an EVM address",
+      );
+    }
+  } else if (factoryRaw === undefined || factoryRaw.length === 0) {
     if (registered?.openerFactory == null) {
       throw new Error(
         `METRIK_GATEWAY_X402V2_FACTORY_ADDRESS is required on ${network}: the network registry has no opener factory for it`,
@@ -742,9 +807,18 @@ export function parseGatewayX402OpenerEnvConfig(
     ),
   };
   const price = requireUintEnv(env, "METRIK_GATEWAY_X402V2_PRICE");
-  // Startup validation: rate/duration > 0 and 0 < price <= rate * maxDuration.
-  assertValidTerms(terms);
-  assertValidPrice(price, terms);
+  let upfrontAmount: bigint | undefined;
+  if (upfrontMode) {
+    upfrontAmount = requireUintEnv(env, "METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT");
+    // Startup validation, fail closed: the upfront factory's own validateTerms
+    // rules, 0 < price, upfrontAmount <= price, and the metered part
+    // (price - upfrontAmount) <= rate * maxDuration.
+    assertValidUpfrontTerms({ ...terms, price, upfrontAmount });
+  } else {
+    // Startup validation: rate/duration > 0 and 0 < price <= rate * maxDuration.
+    assertValidTerms(terms);
+    assertValidPrice(price, terms);
+  }
   const maxTimeoutSeconds = requirePositiveIntEnv(
     env,
     "METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS",
@@ -828,6 +902,8 @@ export function parseGatewayX402OpenerEnvConfig(
     ),
     terms,
     price,
+    ...(upfrontAmount === undefined ? {} : { upfrontAmount }),
+    ...(upfrontImplementation === undefined ? {} : { upfrontImplementation }),
     maxTimeoutSeconds,
     facilitatorTimeoutMs: facilitatorTimeoutSeconds * 1000,
     ...(resourceBaseUrl === undefined || resourceBaseUrl.length === 0
@@ -1032,6 +1108,12 @@ export async function startCallerAuthGatewayServerFromEnv(
         assetVersion: config.x402Opener.assetVersion,
         terms: config.x402Opener.terms,
         price: config.x402Opener.price,
+        ...(config.x402Opener.upfrontAmount === undefined
+          ? {}
+          : { upfrontAmount: config.x402Opener.upfrontAmount }),
+        ...(config.x402Opener.upfrontImplementation === undefined
+          ? {}
+          : { upfrontImplementation: config.x402Opener.upfrontImplementation }),
         maxTimeoutSeconds: config.x402Opener.maxTimeoutSeconds,
         facilitatorTimeoutMs: config.x402Opener.facilitatorTimeoutMs,
         ...(config.x402Opener.resourceBaseUrl === undefined
@@ -1058,12 +1140,18 @@ export async function startCallerAuthGatewayServerFromEnv(
       },
       { rpcUrl: config.rpcUrl },
     );
+    const upfront = x402Opener.upfrontAmount;
     console.error(
       "[metrik-caller-auth-gateway] x402 v2 opener mode ENABLED: a request with neither a " +
         "capability nor PAYMENT-SIGNATURE gets a 402 quoting payTo " +
-        `${x402Opener.payTo} (the escrow opener for serviceRef ${config.serviceRef}), price ` +
-        `${config.x402Opener.price} base units. Payments settle into StreamEscrowV2 via the Metrik ` +
-        `opener facilitator at ${config.x402Opener.facilitatorUrl}, and only after the upstream answers < 400. ` +
+        `${x402Opener.payTo} (the ${x402Opener.openerKind} opener for serviceRef ${config.serviceRef}), price ` +
+        `${config.x402Opener.price} base units` +
+        (upfront === null
+          ? " (all of it escrowed and metered)"
+          : upfront === config.x402Opener.price
+            ? " (UPFRONT-ONLY: all of it a non-refundable per-call charge; no stream, nothing to refund)"
+            : ` (${upfront} a non-refundable per-call charge, ${config.x402Opener.price - upfront} escrowed, metered and refundable)`) +
+        `. Payments settle via the Metrik opener facilitator at ${config.x402Opener.facilitatorUrl}, and only after the upstream answers < 400. ` +
         `Refunds (no ETH needed, never automatic): ${x402Opener.refundBaseUrl}/streams/:streamId.`,
     );
     const refundHost = new URL(x402Opener.refundBaseUrl).hostname;

package/src/gateway/x402-opener-mode.ts

@@ -26,6 +26,11 @@ import {
   type PublicClient,
 } from "viem";
 
+import {
+  predictUpfrontOpenerAddress,
+  x402UpfrontStreamOpenerFactoryAbi,
+} from "@absol-labs/shared";
+
 import { x402StreamOpenerFactoryAbi } from "../x402-opener/abi.js";
 import {
   RegistryListingResolver,
@@ -35,6 +40,7 @@ import { readOpenerFacilitatorMarker } from "../x402-opener/scheme.js";
 import {
   assertValidPrice,
   assertValidTerms,
+  assertValidUpfrontTerms,
   chainIdFromNetwork,
   assertSchemaDeclaration,
   DEFAULT_OPENER_DOCS_URL,
@@ -43,7 +49,11 @@ import {
   OPENER_SCHEME,
   termsToExtra,
   termsTuple,
+  upfrontTermsToExtra,
+  upfrontTermsTuple,
+  type OpenerKind,
   type OpenerTerms,
+  type UpfrontOpenerTerms,
   type X402SchemaDeclaration,
 } from "../x402-opener/terms.js";
 
@@ -90,6 +100,18 @@ import {
  * - refuses to start if its price is below the facilitator's advertised
  *   minimum, or if its facilitator timeout would not outlast the facilitator's
  *   receipt wait.
+ *
+ * ## Two opener kinds
+ *
+ * Without `upfrontAmount` the listing quotes the `X402StreamOpenerFactory`
+ * (`"stream"`): the whole price funds a metered stream. With `upfrontAmount`
+ * it quotes the `X402UpfrontStreamOpenerFactory` (`"upfront"`, the "minimum
+ * charge"): `amount == price`, `payTo = predict(6 terms)`, the
+ * `upfrontAmount` is paid to the seller at settlement and is NOT refundable,
+ * and only `price - upfrontAmount` funds a metered, refundable stream. The 402
+ * description states that split. `upfrontAmount == price` is an upfront-only
+ * listing: no stream opens (the settlement reports `streamId: null`), the
+ * response is served, and no metered session or refund exists for it.
  */
 
 /** How long a successful `/supported` marker check is trusted, seconds. */
@@ -118,8 +140,24 @@ export interface GatewayX402OpenerModeConfig {
   readonly assetVersion: string;
   /** Opener terms. `operator` + `serviceRef` must resolve to one operator-signed listing. */
   readonly terms: OpenerTerms;
-  /** Price per paid request in token base units. Becomes the stream deposit. */
+  /**
+   * Price per paid request in token base units. For a stream opener it is the
+   * whole stream deposit; for an upfront opener the exact x402 amount, split
+   * into `upfrontAmount` (non-refundable) and `price - upfrontAmount` (deposit).
+   */
   readonly price: bigint;
+  /**
+   * Selects the UPFRONT opener kind (`factoryAddress` must then be an
+   * `X402UpfrontStreamOpenerFactory`): the non-refundable per-call part, base
+   * units, `0 <= upfrontAmount <= price`. Unset = the stream opener kind.
+   */
+  readonly upfrontAmount?: bigint;
+  /**
+   * The implementation the upfront factory must report (e.g. the registry's);
+   * checked at startup when given. `payTo` is always recomputed offline from
+   * the factory's own `implementation()` and must equal its on-chain `predict`.
+   */
+  readonly upfrontImplementation?: Address;
   /** Authorization validity the client signs for. Default 300s. */
   readonly maxTimeoutSeconds?: number;
   /** Public origin clients reach this gateway at, for the 402 `resource.url`. */
@@ -168,6 +206,11 @@ export interface GatewayX402OpenerModeConfig {
 export function describeOpenerPurchase(input: {
   readonly terms: OpenerTerms;
   readonly price: bigint;
+  /**
+   * Upfront openers only: the non-refundable per-call part. The description
+   * then states the split (non-refundable vs metered and refundable).
+   */
+  readonly upfrontAmount?: bigint;
   readonly assetDecimals: number;
   readonly assetSymbol: string;
   /** Refund URL template containing `{streamId}`. */
@@ -178,15 +221,42 @@ export function describeOpenerPurchase(input: {
   const amount = (value: bigint) =>
     `${formatUnits(value, input.assetDecimals)} ${input.assetSymbol}`;
   const { ratePerSecond, maxDuration } = input.terms;
-  const cap =
-    input.price < ratePerSecond * maxDuration
-      ? ` (the seller can earn at most ${amount(input.price)})`
-      : "";
   const prefix =
     input.serviceDescription === undefined ||
     input.serviceDescription.trim().length === 0
       ? ""
       : `${input.serviceDescription.trim()} `;
+  if (input.upfrontAmount !== undefined) {
+    const upfront = input.upfrontAmount;
+    const metered = input.price - upfront;
+    if (metered === 0n) {
+      return (
+        `${prefix}Pays for one call: ${amount(input.price)}, charged in full at settlement as a NON-REFUNDABLE per-call charge ` +
+        "(paid to the seller whatever is delivered). No escrow stream is opened, so nothing is metered and there is nothing to refund or reclaim. " +
+        `Docs: ${input.docsUrl}`
+      );
+    }
+    const meteredCap =
+      metered < ratePerSecond * maxDuration
+        ? ` (the seller can earn at most ${amount(metered)} of it)`
+        : "";
+    return (
+      `${prefix}Pays for one call: ${amount(input.price)} in total. ` +
+      (upfront === 0n
+        ? "Nothing of it is charged upfront. "
+        : `${amount(upfront)} is a NON-REFUNDABLE per-call charge, paid to the seller at settlement whatever is delivered. `) +
+      `The remaining ${amount(metered)} is metered and refundable: it funds a Metrik escrow stream of ` +
+      `${maxDuration.toString()} seconds at ${amount(ratePerSecond)}/s${meteredCap}; ` +
+      "the seller earns it only for seconds Metrik's verifier confirms the service is delivering, " +
+      `and any unearned part of it (at most ${amount(metered)}) is refundable to you (no ETH needed) via ${input.refundUrlTemplate}. ` +
+      "Refunds are not automatic: close the stream and reclaim there, using the streamId from the PAYMENT-RESPONSE. " +
+      `Docs: ${input.docsUrl}`
+    );
+  }
+  const cap =
+    input.price < ratePerSecond * maxDuration
+      ? ` (the seller can earn at most ${amount(input.price)})`
+      : "";
   return (
     `${prefix}Pays for one call. Your payment of ${amount(input.price)} funds a Metrik escrow stream of ` +
     `${maxDuration.toString()} seconds at ${amount(ratePerSecond)}/s${cap}; ` +
@@ -216,9 +286,13 @@ class OpenerExactServerScheme extends ExactEvmScheme {
       | Record<string, unknown>
       | undefined;
     const streamId = opened?.streamId;
+    // An upfront-only payment reports `streamId: null` (no stream): it gets no
+    // refund URL, since there is nothing to refund. bytes32(0) is treated the
+    // same, defensively.
     if (
       typeof streamId !== "string" ||
       !/^0x[0-9a-fA-F]{64}$/.test(streamId) ||
+      /^0x0{64}$/i.test(streamId) ||
       opened?.refundUrl !== undefined
     ) {
       return undefined;
@@ -249,6 +323,10 @@ export interface GatewayX402OpenerMode {
   readonly network: Network;
   readonly terms: OpenerTerms;
   readonly price: bigint;
+  /** `"stream"` or `"upfront"` (selected by `upfrontAmount`). */
+  readonly openerKind: OpenerKind;
+  /** The upfront kind's non-refundable part; `null` for the stream kind. */
+  readonly upfrontAmount: bigint | null;
   readonly resourceBaseUrl: string | undefined;
   /** The 402 `description` (what the payment buys). */
   readonly description: string;
@@ -417,9 +495,25 @@ export async function buildGatewayX402OpenerMode(
   config: GatewayX402OpenerModeConfig,
   deps: GatewayX402OpenerModeDeps = {},
 ): Promise<GatewayX402OpenerMode> {
+  const kind: OpenerKind =
+    config.upfrontAmount === undefined ? "stream" : "upfront";
+  const upfrontTerms: UpfrontOpenerTerms | undefined =
+    config.upfrontAmount === undefined
+      ? undefined
+      : {
+          ...config.terms,
+          price: config.price,
+          upfrontAmount: config.upfrontAmount,
+        };
   try {
-    assertValidTerms(config.terms);
-    assertValidPrice(config.price, config.terms);
+    if (upfrontTerms === undefined) {
+      assertValidTerms(config.terms);
+      assertValidPrice(config.price, config.terms);
+    } else {
+      // The factory's own validateTerms rules + amount == price + the metered
+      // part within rate * maxDuration: exactly what the SDK buyer requires.
+      assertValidUpfrontTerms(upfrontTerms);
+    }
   } catch (error) {
     throw new X402OpenerModeConfigError(
       error instanceof Error ? error.message : String(error),
@@ -501,24 +595,86 @@ export async function buildGatewayX402OpenerMode(
   const factory = getAddress(config.factoryAddress);
   const escrow = getAddress(config.escrowAddress);
   const asset = getAddress(config.asset);
-  const [factoryEscrow, factoryUsdc, predicted] = await Promise.all([
-    publicClient.readContract({
-      address: factory,
-      abi: x402StreamOpenerFactoryAbi,
-      functionName: "escrow",
-    }),
-    publicClient.readContract({
-      address: factory,
-      abi: x402StreamOpenerFactoryAbi,
-      functionName: "usdc",
-    }),
-    publicClient.readContract({
-      address: factory,
-      abi: x402StreamOpenerFactoryAbi,
-      functionName: "predict",
-      args: [termsTuple(config.terms)],
-    }),
-  ]);
+  let factoryEscrow: Address;
+  let factoryUsdc: Address;
+  let predicted: Address;
+  if (upfrontTerms === undefined) {
+    [factoryEscrow, factoryUsdc, predicted] = await Promise.all([
+      publicClient.readContract({
+        address: factory,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "escrow",
+      }),
+      publicClient.readContract({
+        address: factory,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "usdc",
+      }),
+      publicClient.readContract({
+        address: factory,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "predict",
+        args: [termsTuple(config.terms)],
+      }),
+    ]);
+  } else {
+    let implementation: Address;
+    [factoryEscrow, factoryUsdc, predicted, implementation] = await Promise.all(
+      [
+        publicClient.readContract({
+          address: factory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "escrow",
+        }),
+        publicClient.readContract({
+          address: factory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "usdc",
+        }),
+        publicClient.readContract({
+          address: factory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "predict",
+          args: [upfrontTermsTuple(upfrontTerms)],
+        }),
+        publicClient.readContract({
+          address: factory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "implementation",
+        }),
+      ],
+    ).catch((error: unknown) => {
+      throw new X402OpenerModeConfigError(
+        `factory ${factory} is not an X402UpfrontStreamOpenerFactory that accepts these upfront terms (${error instanceof Error ? (error.message.split("\n")[0] ?? "error") : String(error)})`,
+      );
+    });
+    if (
+      config.upfrontImplementation !== undefined &&
+      getAddress(implementation) !== getAddress(config.upfrontImplementation)
+    ) {
+      throw new X402OpenerModeConfigError(
+        `upfront factory ${factory} reports implementation ${implementation}, not the expected ${config.upfrontImplementation}`,
+      );
+    }
+    // The SDK buyer recomputes payTo OFFLINE; quote only a payTo both agree on.
+    const offline = predictUpfrontOpenerAddress({
+      factory,
+      implementation: getAddress(implementation),
+      terms: {
+        operator: getAddress(upfrontTerms.operator),
+        serviceRef: upfrontTerms.serviceRef.toLowerCase() as `0x${string}`,
+        ratePerSecond: upfrontTerms.ratePerSecond,
+        maxDuration: upfrontTerms.maxDuration,
+        price: upfrontTerms.price,
+        upfrontAmount: upfrontTerms.upfrontAmount,
+      },
+    });
+    if (getAddress(offline) !== getAddress(predicted)) {
+      throw new X402OpenerModeConfigError(
+        `factory.predict(terms) = ${predicted} disagrees with the offline CREATE2 derivation ${offline}; refusing to quote it`,
+      );
+    }
+  }
   if (getAddress(factoryEscrow) !== escrow) {
     throw new X402OpenerModeConfigError(
       `factory ${factory} settles into ${factoryEscrow}, not this gateway's escrow ${escrow}`,
@@ -577,22 +733,26 @@ export async function buildGatewayX402OpenerMode(
         { cause },
       );
     }
-    const kind = supported.kinds.find(
+    const supportedKind = supported.kinds.find(
       (candidate) =>
         candidate.x402Version === 2 &&
         candidate.scheme === OPENER_SCHEME &&
         candidate.network === config.network,
     );
-    const marker = readOpenerFacilitatorMarker(kind?.extra);
+    const marker = readOpenerFacilitatorMarker(supportedKind?.extra);
     if (
       marker === undefined ||
-      marker.factory !== factory ||
-      marker.escrow !== escrow ||
+      !markerSettles(
+        marker,
+        upfrontTerms === undefined ? "stream" : "upfront",
+        factory,
+        escrow,
+      ) ||
       marker.usdc !== asset ||
       marker.chainId !== chainId
     ) {
       throw new X402OpenerFacilitatorUnverifiedError(
-        `the x402 facilitator at ${config.facilitatorUrl} does not advertise Metrik opener settlement for factory ${factory} on ${config.network}. ` +
+        `the x402 facilitator at ${config.facilitatorUrl} does not advertise Metrik ${upfrontTerms === undefined ? "" : "upfront "}opener settlement for factory ${factory} on ${config.network}. ` +
           "Refusing to quote an opener payTo: a stock exact facilitator would transfer the payment straight to the opener and strand it permanently.",
       );
     }
@@ -624,6 +784,9 @@ export async function buildGatewayX402OpenerMode(
   const description = describeOpenerPurchase({
     terms: config.terms,
     price: config.price,
+    ...(config.upfrontAmount === undefined
+      ? {}
+      : { upfrontAmount: config.upfrontAmount }),
     assetDecimals,
     assetSymbol: config.assetName,
     refundUrlTemplate: `${refundBaseUrl}/streams/{streamId}`,
@@ -644,11 +807,21 @@ export async function buildGatewayX402OpenerMode(
           name: config.assetName,
           version: config.assetVersion,
           assetTransferMethod: "eip3009",
-          [OPENER_EXTRA_KEY]: {
-            ...termsToExtra(factory, config.terms),
-            refundUrl: `${refundBaseUrl}/streams/{streamId}`,
-            docsUrl,
-          },
+          [OPENER_EXTRA_KEY]:
+            upfrontTerms === undefined
+              ? {
+                  ...termsToExtra(factory, config.terms),
+                  refundUrl: `${refundBaseUrl}/streams/{streamId}`,
+                  docsUrl,
+                }
+              : {
+                  ...upfrontTermsToExtra(factory, upfrontTerms),
+                  // An upfront-only listing opens no stream: no refund URL.
+                  ...(upfrontTerms.upfrontAmount === upfrontTerms.price
+                    ? {}
+                    : { refundUrl: `${refundBaseUrl}/streams/{streamId}` }),
+                  docsUrl,
+                },
         },
       },
       maxTimeoutSeconds,
@@ -692,6 +865,7 @@ export async function buildGatewayX402OpenerMode(
   await ready();
   if (refundBaseUrl !== config.facilitatorUrl.replace(/\/+$/, "")) {
     await checkRefundRelayAt(refundBaseUrl, deps.fetch ?? fetch, {
+      kind,
       factory,
       escrow,
       asset,
@@ -705,6 +879,8 @@ export async function buildGatewayX402OpenerMode(
     network: config.network,
     terms: config.terms,
     price: config.price,
+    openerKind: kind,
+    upfrontAmount: config.upfrontAmount ?? null,
     resourceBaseUrl: config.resourceBaseUrl,
     description,
     refundBaseUrl,
@@ -729,6 +905,7 @@ async function checkRefundRelayAt(
   refundBaseUrl: string,
   fetchImpl: typeof fetch,
   expected: {
+    readonly kind: OpenerKind;
     readonly factory: Address;
     readonly escrow: Address;
     readonly asset: Address;
@@ -765,8 +942,7 @@ async function checkRefundRelayAt(
   const marker = readOpenerFacilitatorMarker(kind?.extra);
   if (
     marker === undefined ||
-    marker.factory !== expected.factory ||
-    marker.escrow !== expected.escrow ||
+    !markerSettles(marker, expected.kind, expected.factory, expected.escrow) ||
     marker.usdc !== expected.asset ||
     marker.chainId !== expected.chainId ||
     marker.refundRelay !== true
@@ -777,6 +953,27 @@ async function checkRefundRelayAt(
   }
 }
 
+/**
+ * Whether a facilitator marker settles THIS listing's opener kind: the stream
+ * factory is the marker's `factory`; the upfront factory its `upfrontOpener`.
+ */
+function markerSettles(
+  marker: NonNullable<ReturnType<typeof readOpenerFacilitatorMarker>>,
+  kind: OpenerKind,
+  factory: Address,
+  escrow: Address,
+): boolean {
+  if (kind === "upfront") {
+    return (
+      marker.upfrontOpener !== undefined &&
+      marker.upfrontOpener.factory === factory &&
+      marker.upfrontOpener.escrow === escrow &&
+      marker.escrow === escrow
+    );
+  }
+  return marker.factory === factory && marker.escrow === escrow;
+}
+
 /**
  * One x402-mode request, mirroring the reference `@x402/*` middleware: verify
  * via the facilitator, run the upstream, and settle ONLY when the upstream

package/src/mcp/server.ts

@@ -377,6 +377,18 @@ export interface StoredStreamRecord {
    * 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 {
@@ -456,6 +468,8 @@ export class FileStreamRegistry implements StreamRegistry {
           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));
@@ -480,6 +494,12 @@ export class FileStreamRegistry implements StreamRegistry {
             ? {}
             : { opener: record.opener as `0x${string}` }),
           ...(record.x402Reservation === true ? { x402Reservation: true } : {}),
+          ...(record.x402Charge === undefined
+            ? {}
+            : { x402Charge: record.x402Charge }),
+          ...(record.nonRefundableUsdc === undefined
+            ? {}
+            : { nonRefundableUsdc: BigInt(record.nonRefundableUsdc) }),
         },
       ]),
     );
@@ -496,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,
@@ -1129,21 +1152,27 @@ export function createVerifiedStreamMcpServer(
             // 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.x402Reservation === true
+              record.x402Charge === "upfront-only"
                 ? {
                     streamId: record.streamId,
-                    x402Reservation:
-                      "an x402 payment was signed but its stream could not be confirmed; its amount stays counted against the spend mandate",
+                    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",
                   }
-                : await options.agentClient
-                    .getStreamStatus(record.streamId)
-                    .then((value) =>
-                      serializeStreamStatus(value, record.streamId),
-                    )
-                    .catch((error) => ({
+                : record.x402Reservation === true
+                  ? {
                       streamId: record.streamId,
-                      statusError: asErrorMessage(error),
-                    }));
+                      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,
@@ -1154,6 +1183,9 @@ export function createVerifiedStreamMcpServer(
               maxDurationSeconds: record.maxDurationSeconds,
               openedAtSeconds: record.openedAtSeconds,
               mandateId: record.mandateId,
+              ...(record.nonRefundableUsdc === undefined
+                ? {}
+                : { nonRefundableUsdc: record.nonRefundableUsdc.toString() }),
               status,
             };
           }),