@bnbagent/studio-cli 0.0.6-alpha.1 → 0.0.6-alpha.2

package/dist/bag.js

@@ -2,6 +2,7 @@
 import {
   B402_RUNTIME_KEYS,
   CliExit,
+  DEFAULT_B402_PRICE_USD,
   act,
   agentcoreFlavor,
   b402Credentials,
@@ -19,6 +20,7 @@ import {
   hasMcpFace,
   hasX402Face,
   nativeProtocolOf,
+  normalizeB402PriceUsd,
   normalizeProtocolFaces,
   printErr,
   printOut,
@@ -34,8 +36,11 @@ import {
   trialFromDeployCliJson,
   whichBin,
   withDeployFiles,
-  x402DeploySummary
-} from "./chunk-M3ODFCA7.js";
+  x402DeploySummary,
+  x402SellerIsFree,
+  x402SellerPricingState,
+  x402SellerUsesB402
+} from "./chunk-6EYSXRFD.js";
 import {
   TWAK_CLI_MIN_VERSION,
   TWAK_CLI_VERSION,
@@ -97,7 +102,7 @@ import {
 var CAMPAIGN_DOC_URL = "https://www.bnbchain.org/en/blog/bnb-agent-studio-is-live-on-bnb-chain-ai-agents-from-one-prompt";
 var CAMPAIGN_CHECK_TIMEOUT_MS = 6e3;
 async function fetchCampaignActive() {
-  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-N6TPN6XA.js");
+  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-3U2FESF4.js");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CAMPAIGN_CHECK_TIMEOUT_MS);
   try {
@@ -2095,6 +2100,77 @@ function devPortInUse(port = 9e3, timeoutMs = 250) {
   });
 }
 
+// src/cli/_erc8183Config.ts
+var ERC8183_ADDRESS_OVERRIDE_KEYS = [
+  "ERC8183_COMMERCE_ADDRESS",
+  "ERC8183_ROUTER_ADDRESS",
+  "ERC8183_POLICY_ADDRESS"
+];
+var MAX_UINT256 = 2n ** 256n - 1n;
+function erc8183PricingState(pay) {
+  const priceRaw = pay.price;
+  const price = String(priceRaw ?? "").trim();
+  if (!price) return { kind: "unset" };
+  if (typeof priceRaw !== "string") {
+    return { kind: "invalid", field: "price", value: price };
+  }
+  const minRaw = pay.min_price;
+  const maxRaw = pay.max_price;
+  const minPrice = String(minRaw ?? "").trim() || "0";
+  const maxPrice = String(maxRaw ?? "").trim();
+  if (minRaw !== void 0 && typeof minRaw !== "string") {
+    return { kind: "invalid", field: "min_price", value: minPrice };
+  }
+  if (maxRaw !== void 0 && typeof maxRaw !== "string") {
+    return { kind: "invalid", field: "max_price", value: maxPrice };
+  }
+  for (const [field, value] of [
+    ["price", price],
+    ["min_price", minPrice],
+    ["max_price", maxPrice]
+  ]) {
+    if ((field !== "max_price" || value !== "") && !/^\d+$/.test(value)) {
+      return { kind: "invalid", field, value };
+    }
+  }
+  const list = BigInt(price);
+  const min = BigInt(minPrice);
+  const max = maxPrice ? BigInt(maxPrice) : MAX_UINT256;
+  if (list > MAX_UINT256 || min > MAX_UINT256 || max > MAX_UINT256) {
+    const [field, value] = list > MAX_UINT256 ? ["price", price] : min > MAX_UINT256 ? ["min_price", minPrice] : ["max_price", maxPrice];
+    return { kind: "invalid", field, value };
+  }
+  const clampedToMax = list < max ? list : max;
+  const effective = min > clampedToMax ? min : clampedToMax;
+  const base = {
+    listPrice: list,
+    minPrice: min,
+    maxPrice: max,
+    effectivePrice: effective
+  };
+  if (list > 0n && effective === 0n) {
+    return { kind: "clamped_to_zero", ...base };
+  }
+  return { kind: effective === 0n ? "free" : "paid", ...base };
+}
+function erc8183ContractOverrideState(env = process.env) {
+  const present = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => Boolean(env[key]?.trim())
+  );
+  const missing = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => !env[key]?.trim()
+  );
+  const invalid = present.filter(
+    (key) => !/^0x[0-9a-fA-F]{40}$/.test(env[key]?.trim() ?? "")
+  );
+  return {
+    mode: present.length === 0 ? "canonical" : invalid.length > 0 ? "invalid" : missing.length === 0 ? "custom" : "partial",
+    present: [...present],
+    missing: [...missing],
+    invalid
+  };
+}
+
 // src/cli/config.ts
 var MAX_QUOTE_TTL_SECONDS = NegotiationHandler.MAX_QUOTE_TTL_SECONDS;
 function registerConfig(program) {
@@ -2273,6 +2349,38 @@ function validateKnownKey(parts, value) {
   }
   return null;
 }
+function isErc8183AmountKey(parts) {
+  return parts.length === 3 && parts[0] === "payments" && parts[1] === "erc8183" && ["price", "min_price", "max_price"].includes(parts[2]);
+}
+function isB402PriceKey(parts) {
+  return parts.length === 3 && parts[0] === "payments" && parts[1] === "x402_seller" && parts[2] === "price_usd";
+}
+function coerceKnownValue(parts, rawValue, typeFlag) {
+  if (!isErc8183AmountKey(parts) && !isB402PriceKey(parts)) {
+    return coerceValue(rawValue, typeFlag);
+  }
+  if (isB402PriceKey(parts)) {
+    if (typeFlag !== "auto" && typeFlag !== "string") {
+      throw new Error(
+        `${parts.join(".")} is stored as a decimal string; use --type string or omit --type.`
+      );
+    }
+    return normalizeB402PriceUsd(rawValue);
+  }
+  if (typeFlag !== "auto" && typeFlag !== "string") {
+    throw new Error(
+      `${parts.join(".")} is stored as a decimal string; use --type string or omit --type.`
+    );
+  }
+  const value = rawValue.trim();
+  const isUnboundedMax = parts[2] === "max_price" && value === "";
+  if (!isUnboundedMax && !/^\d+$/.test(value)) {
+    throw new Error(
+      `${parts.join(".")} must be a non-negative integer string in token base units; got ${JSON.stringify(rawValue)}.`
+    );
+  }
+  return value;
+}
 function setDottedKey(text2, parts, value) {
   const key = parts[parts.length - 1];
   const section = parts.slice(0, -1).join(".");
@@ -2347,7 +2455,7 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
   }
   let value;
   try {
-    value = coerceValue(rawValue, typeFlag);
+    value = coerceKnownValue(parts, rawValue, typeFlag);
   } catch (err) {
     printErr(`error: ${err instanceof Error ? err.message : String(err)}`);
     return 2;
@@ -2357,8 +2465,64 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
     printErr(`error: ${validationError}`);
     return 2;
   }
-  fs9.writeFileSync(tomlPath, setDottedKey(text2, parts, value), "utf-8");
+  const updatedText = setDottedKey(text2, parts, value);
+  fs9.writeFileSync(tomlPath, updatedText, "utf-8");
   printOut(`set ${key} = ${JSON.stringify(plainValue(value))}`);
+  if (parts.length === 3 && parts[0] === "payments" && parts[1] === "erc8183" && parts[2] === "price") {
+    const updated = parse4(updatedText);
+    const payments = updated.payments !== null && typeof updated.payments === "object" && !Array.isArray(updated.payments) ? updated.payments : {};
+    const erc = payments.erc8183 !== null && typeof payments.erc8183 === "object" && !Array.isArray(payments.erc8183) ? payments.erc8183 : {};
+    const pricing = erc8183PricingState(erc);
+    if (pricing.kind === "invalid" || pricing.kind === "unset") {
+      printErr(
+        "warning: price was saved, but existing min_price/max_price is invalid; run `bag doctor`."
+      );
+    }
+    if (pricing.kind === "free") {
+      printOut("pricing: FREE \u2014 buyers fund 0 token units; zero token escrow.");
+      const contracts = erc8183ContractOverrideState();
+      if (contracts.mode === "custom") {
+        printOut(
+          "ERC-8183 contracts: custom/QA contract stack selected with all three address overrides."
+        );
+      } else if (contracts.mode === "partial") {
+        printErr(
+          `warning: ERC-8183 contract override is incomplete; set ${contracts.missing.join(", ")} before running a job.`
+        );
+      } else if (contracts.mode === "invalid") {
+        printErr(
+          `warning: invalid ERC-8183 address override(s): ${contracts.invalid.join(", ")}.`
+        );
+      } else {
+        printErr(
+          "warning: FREE requires a zero-price-compatible contract stack; set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together before deploy."
+        );
+      }
+    } else if (pricing.kind === "clamped_to_zero") {
+      printErr(
+        "warning: PAID list price is clamped to 0; this is not an explicit FREE choice. Fix max_price or set price to 0."
+      );
+    } else if (pricing.kind === "paid") {
+      printOut(
+        `pricing: PAID \u2014 effective price ${pricing.effectivePrice} token base units after clamping.`
+      );
+    }
+  }
+  if (isB402PriceKey(parts)) {
+    const pricing = x402SellerPricingState({ price_usd: value });
+    if (pricing.kind === "free") {
+      printOut(
+        "x402 pricing: FREE \u2014 B402 verify/settle is bypassed; no payment or settlement audit."
+      );
+      printErr(
+        "warning: /x402 is now an anonymous FREE endpoint. Confirm that unrestricted public access is intended."
+      );
+    } else if (pricing.kind === "paid") {
+      printOut(
+        `x402 pricing: PAID \u2014 $${pricing.priceUsd} per request through B402.`
+      );
+    }
+  }
   if (parts[0] === "network") {
     if (await devPortInUse(8080)) {
       printErr(
@@ -6983,6 +7147,12 @@ function registerInit(program) {
       "--rails <rails>",
       "Commerce rail(s) to scaffold: 8183 (default), b402, or both."
     ).choices(["8183", "b402", "both"])
+  ).option(
+    "--erc8183-price <base-units>",
+    "ERC-8183 list price as a non-negative integer string in token base units. Use 0 for FREE. Default: 100000000000000000 (0.1 U)."
+  ).option(
+    "--b402-price <usd>",
+    "B402/x402 per-request price as a non-negative decimal USD string. Use 0 for FREE passthrough (no B402 verify/settle). Default: 0.01."
   ).addOption(
     new Option2(
       "--llm-provider <provider>",
@@ -7099,6 +7269,45 @@ async function cmdInit(nameArg, opts) {
     opts.llmProviderSource,
     isTty
   );
+  let rails = await resolveRails(opts.rails, isTty);
+  if (hasX402Face(faces) && rails === "8183") {
+    rails = "both";
+  } else if (hasX402Face(faces) && rails !== "both") {
+    rails = "b402";
+  }
+  if ((rails === "b402" || rails === "both") && !hasX402Face(faces)) {
+    faces = normalizeProtocolFaces([...faces, "X402"]);
+  }
+  if (opts.erc8183Price !== void 0 && rails === "b402") {
+    printErr(
+      "error: --erc8183-price requires the 8183 rail; use --rails 8183 or --rails both."
+    );
+    return 2;
+  }
+  if (opts.b402Price !== void 0 && rails === "8183") {
+    printErr(
+      "error: --b402-price requires the b402 rail; use --rails b402 or --rails both."
+    );
+    return 2;
+  }
+  let erc8183Price = DEFAULT_ERC8183_PRICE;
+  if (rails === "8183" || rails === "both") {
+    try {
+      erc8183Price = await resolveErc8183Price(opts.erc8183Price, isTty);
+    } catch (exc) {
+      printErr(`error: ${exc instanceof Error ? exc.message : exc}`);
+      return 2;
+    }
+  }
+  let b402Price = DEFAULT_B402_PRICE_USD;
+  if (rails === "b402" || rails === "both") {
+    try {
+      b402Price = await resolveB402Price(opts.b402Price, isTty);
+    } catch (exc) {
+      printErr(`error: ${exc instanceof Error ? exc.message : exc}`);
+      return 2;
+    }
+  }
   const enclosing = enclosingProjectRoot(path21.dirname(target));
   if (enclosing !== null) {
     printErr(
@@ -7196,16 +7405,7 @@ async function cmdInit(nameArg, opts) {
   }
   const budgetFlag = opts.enableAutoTopup ? "enable" : opts.autoTopup === false ? "disable" : null;
   const budgetChoice = walletKind2 === "altana" && llmProvider !== "pieverse-llm" && budgetFlag === null ? null : await resolveBudgetChoice(budgetFlag);
-  let rails = await resolveRails(opts.rails, isTty);
-  if (hasX402Face(faces) && rails === "8183") {
-    rails = "both";
-  } else if (hasX402Face(faces) && rails !== "both") {
-    rails = "b402";
-  }
-  if ((rails === "b402" || rails === "both") && !hasX402Face(faces)) {
-    faces = normalizeProtocolFaces([...faces, "X402"]);
-  }
-  if ((rails === "b402" || rails === "both") && !["evm-local", "twak"].includes(walletKind2)) {
+  if ((rails === "b402" || rails === "both") && x402SellerPricingState({ price_usd: b402Price }).kind === "paid" && !["evm-local", "twak"].includes(walletKind2)) {
     printErr(
       `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet. Re-run with --rails 8183 or a supported --wallet-kind.`
     );
@@ -7220,6 +7420,8 @@ async function cmdInit(nameArg, opts) {
       runtime,
       faces,
       rails,
+      erc8183Price,
+      b402Price,
       budgetChoice,
       ides,
       storageProvider: opts.storageProvider,
@@ -7318,8 +7520,9 @@ async function cmdInit(nameArg, opts) {
       "info: X402-only publishes only the /x402 gateway face; the native AgentCore A2A protocol declaration is suppressed from discovery."
     );
   } else if (faces.length === 1 && hasX402Face(faces) && destination === "self") {
+    const free = x402SellerPricingState({ price_usd: b402Price }).kind === "free";
     printErr(
-      "warning: X402-only uses an A2A-native AgentCore process internally, but exposes no public A2A face; the seller stays dormant until the B402 credentials are filled, and a self-hosted AgentCore target needs your own HTTP front to reach /x402."
+      free ? "warning: X402-only FREE mode uses an A2A-native AgentCore process internally, but exposes no public A2A face; a self-hosted AgentCore target still needs your own HTTP front to reach the anonymous /x402 passthrough." : "warning: X402-only uses an A2A-native AgentCore process internally, but exposes no public A2A face; the seller stays dormant until the B402 credentials are filled, and a self-hosted AgentCore target needs your own HTTP front to reach /x402."
     );
   }
   printConfigSummary(agentDir);
@@ -7438,7 +7641,13 @@ function scaffold(target, name, o) {
   fs22.mkdirSync(path21.dirname(envLocal), { recursive: true });
   fs22.writeFileSync(
     envLocal,
-    renderAgentEnvLocal(o.provider, o.storageProvider, o.walletKind, o.rails)
+    renderAgentEnvLocal(
+      o.provider,
+      o.storageProvider,
+      o.walletKind,
+      o.rails,
+      o.b402Price
+    )
   );
   fs22.writeFileSync(path21.join(agentRoot2, ".gitignore"), renderAgentGitignore());
   fs22.writeFileSync(
@@ -7755,14 +7964,14 @@ expected_recipient = ""
 allowed_hosts = ["llm.pieverse.io"]
 `;
 }
-function renderX402SellerSection() {
+function renderX402SellerSection(priceUsd) {
   return `
 [payments.x402_seller]
 # Public seller rail mounted at /x402. Credentials stay in
 # <workspace>/.studio/.env.local and are issued per B402 environment.
 enabled = true
-# Decimal USD string; "0" serves the work for free without a facilitator.
-price_usd = "0.01"
+# Decimal USD string; "0" is explicit FREE passthrough and bypasses B402.
+price_usd = "${priceUsd}"
 # v1 supports United Stables (U) through EIP-3009 only.
 assets = ["U"]
 # Empty means the agent wallet receives payment.
@@ -7817,7 +8026,7 @@ function renderAgentStudioToml(name, o) {
   const model = o.model ?? PROVIDER_DEFAULT_MODEL[o.provider] ?? "";
   const pieverseSection = o.provider === "pieverse-llm" ? renderPieverseSections() : "";
   const x402Section = o.provider === "pieverse-llm" ? renderX402Section() : "";
-  const x402SellerSection = o.rails === "b402" || o.rails === "both" || hasX402Face(o.faces) ? renderX402SellerSection() : "";
+  const x402SellerSection = o.rails === "b402" || o.rails === "both" || hasX402Face(o.faces) ? renderX402SellerSection(o.b402Price) : "";
   const budgetSection = renderBudgetSection(o.budgetChoice);
   const storageSection = renderAgentStorageSection(o.storageProvider);
   const azureSection = o.runtime === "azure-foundry" ? renderAzureSection(name, o.azureAccount, o.azureProject) : "";
@@ -7828,9 +8037,10 @@ function renderAgentStudioToml(name, o) {
 [payments.erc8183]
 # Read by the Agent: it quotes the FIXED \`price\`, CLAMPS it to [min,max],
 # freezes a short-TTL offer, and EIP-191 signs it \u2014 pricing is rule-based, the
-# LLM never prices.
+# LLM never prices. price=0 is FREE and needs a zero-price-compatible
+# ERC-8183 stack selected with all three ERC8183_*_ADDRESS overrides.
 currency = "${currencyAddr}"   # $U token address \u2014 prefilled from [network].default
-price = "100000000000000000"                   # wei \u2014 your list price (0.1 U); what every quote charges
+price = "${o.erc8183Price}"                    # token base units; 0 = FREE (zero token escrow)
 min_price = "0"                                # wei \u2014 clamp floor
 max_price = ""                                 # wei \u2014 clamp ceiling; SET before going live
 quote_ttl_seconds = 900                        # seconds a signed quote stays valid; SDK caps at 900 (~15min work window)
@@ -7868,7 +8078,7 @@ ${pieverseSection}${erc8183Section}
 ${storageSection}
 ${x402Section}${x402SellerSection}${budgetSection}${azureSection}`;
 }
-function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails) {
+function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails, b402Price) {
   const keyEnv = PROVIDER_KEY_ENV[provider];
   const lines = [
     "# \u26A0\uFE0F  SECRETS \u2014 do NOT paste this file into issue trackers, logs, or AI chats.",
@@ -7931,10 +8141,11 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails) {
     );
   }
   if (rails === "b402" || rails === "both") {
+    const free = x402SellerPricingState({ price_usd: b402Price }).kind === "free";
     lines.push(
       "",
       "# B402 merchant credentials (issued per environment after manual approval).",
-      "# All four absent = x402 rail dormant; partial = boot error naming the missing vars.",
+      free ? "# FREE price 0 does not use these credentials; leave them empty until switching to PAID." : "# PAID requires all four; all absent = dormant, partial = boot error.",
       "B402_BASE_URL=",
       "B402_CLIENT_ID=",
       "B402_ACCESS_TOKEN=",
@@ -7942,6 +8153,17 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails) {
       "# (alternative one-line PKCS#8 DER: B402_PRIVATE_KEY_B64=)"
     );
   }
+  if (rails === "8183" || rails === "both") {
+    lines.push(
+      "",
+      "# Optional ERC-8183 contract-stack override (QA/custom). Set all three",
+      "# together; partial overrides can mix incompatible deployments.",
+      "# Required for price=0 while canonical contracts reject zero funding.",
+      "# ERC8183_COMMERCE_ADDRESS=",
+      "# ERC8183_ROUTER_ADDRESS=",
+      "# ERC8183_POLICY_ADDRESS="
+    );
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -8183,6 +8405,69 @@ async function resolveRails(flagValue, isTty) {
   }
   return "8183";
 }
+var DEFAULT_ERC8183_PRICE = "100000000000000000";
+async function resolveErc8183Price(flagValue, isTty) {
+  if (flagValue !== void 0) {
+    const value = flagValue.trim();
+    if (!/^\d+$/.test(value)) {
+      throw new Error(
+        `--erc8183-price must be a non-negative integer string in token base units; got ${JSON.stringify(flagValue)}.`
+      );
+    }
+    return value;
+  }
+  if (!isTty) {
+    return DEFAULT_ERC8183_PRICE;
+  }
+  const choice = (await promptUser(
+    "ERC-8183 pricing [paid/free/custom, Enter = paid (0.1 U)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") {
+    return "0";
+  }
+  if (choice === "custom") {
+    const custom = (await promptUser(
+      "ERC-8183 list price in token base units (non-negative integer): "
+    )).trim();
+    if (!/^\d+$/.test(custom)) {
+      throw new Error(
+        `custom ERC-8183 price must be a non-negative integer string; got ${JSON.stringify(custom)}.`
+      );
+    }
+    return custom;
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(`hint: unknown ERC-8183 pricing choice '${choice}' \u2014 using paid.`);
+  }
+  return DEFAULT_ERC8183_PRICE;
+}
+async function resolveB402Price(flagValue, isTty) {
+  if (flagValue !== void 0) {
+    return normalizeB402PriceUsd(flagValue);
+  }
+  if (!isTty) {
+    return DEFAULT_B402_PRICE_USD;
+  }
+  const choice = (await promptUser(
+    "B402/x402 pricing [paid/free/custom, Enter = paid ($0.01)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") {
+    return "0";
+  }
+  if (choice === "custom") {
+    return normalizeB402PriceUsd(
+      await promptUser(
+        "B402/x402 per-request price in USD (non-negative decimal): "
+      )
+    );
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(
+      `hint: unknown B402/x402 pricing choice '${choice}' \u2014 using paid.`
+    );
+  }
+  return DEFAULT_B402_PRICE_USD;
+}
 async function promptPassword() {
   printOut("");
   printOut("Onboarding (TTY) \u2014 set a wallet password to finish in one go.");
@@ -8940,10 +9225,10 @@ function printNextSteps(name, provider, o = {}) {
     nextStep = 4;
   }
   printOut(
-    `  # ${nextStep}. set ERC-8183 pricing in studio.toml [payments.erc8183]`
+    `  # ${nextStep}. review ERC-8183 pricing in studio.toml [payments.erc8183]`
   );
   printOut(
-    "  #    (currency = $U token; price = list price in wei; min/max_price clamp before sign)"
+    "  #    (price was selected at init; `bag config set payments.erc8183.price 0` explicitly switches to FREE)"
   );
   nextStep += 1;
   printOut(`  # ${nextStep}. verify + run the agent locally`);
@@ -9011,13 +9296,26 @@ function printConfigSummary(agentRoot2) {
   const shown = (v, unset = "<unset \u2014 fill before going live>") => v === void 0 || v === null || v === "" ? unset : String(v);
   const table = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
   const faces = stackFaces(table(agent.stack), table(agent.payments));
+  const payments = table(agent.payments);
+  const erc8183 = table(payments.erc8183);
+  const x402Seller = table(payments.x402_seller);
+  const hasErc8183 = Object.keys(erc8183).length > 0;
+  const hasX402Seller = x402Seller.enabled === true;
+  const x402Pricing = x402SellerPricingState(x402Seller);
+  const isFreeX402 = hasX402Seller && x402Pricing.kind === "free";
+  const onlyX402 = hasX402Seller && !hasErc8183;
   const network = shown(g(agent, "network", "default"), "?");
   const provider = shown(g(agent, "llm", "provider"), "?");
   const model = shown(g(agent, "llm", "model"), "?");
   const modelTag = isFreeModel(String(model)) ? "Free, $0/token" : "paid \u2014 fund + topup to use";
   const currency = g(agent, "payments", "erc8183", "currency");
-  const price = shown(g(agent, "payments", "erc8183", "price"), "0");
+  const priceValue = g(agent, "payments", "erc8183", "price");
+  const price = shown(priceValue);
+  const minPrice = shown(g(agent, "payments", "erc8183", "min_price"), "0");
   const maxPrice = g(agent, "payments", "erc8183", "max_price");
+  const pricingState = erc8183PricingState(erc8183);
+  const isFreePrice = pricingState.kind === "free";
+  const contractOverrides = erc8183ContractOverrideState();
   const storageKind2 = shown(g(agent, "storage", "kind"), "?");
   const storageDesc = storageKind2 === "ipfs" ? "IPFS (durable, public)" : "local disk (offline dev only)";
   const walletKind2 = shown(g(agent, "wallet", "kind"), "evm-local");
@@ -9030,16 +9328,41 @@ function printConfigSummary(agentRoot2) {
   printOut("Your agent's configuration  (studio.toml, in plain language)");
   printOut(bar);
   printOut("");
-  printOut("Per task \u2014 how this seller earns $U:");
-  printOut(
-    "  buyer negotiates \u2192 the Agent (sole signer) QUOTES a signed price \u2192"
-  );
-  printOut(
-    "  on payment the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
-  );
   printOut(
-    "  after the dispute window, SETTLE releases the $U to your wallet."
+    onlyX402 && isFreeX402 ? "Per request \u2014 how this FREE x402 seller delivers work:" : onlyX402 ? "Per request \u2014 how this x402 seller earns $U:" : isFreePrice ? "Per task \u2014 how this FREE seller delivers work:" : "Per task \u2014 how this seller earns $U:"
   );
+  if (onlyX402 && isFreeX402) {
+    printOut(
+      "  anonymous request reaches /x402 \u2192 B402 verify/settle is bypassed \u2192"
+    );
+    printOut(
+      "  the Agent runs the work and returns the result with no payment."
+    );
+  } else if (onlyX402) {
+    printOut(
+      "  anonymous request receives a 402 challenge \u2192 B402 verifies and settles $U \u2192"
+    );
+    printOut("  the Agent runs the work and returns the paid result.");
+  } else {
+    printOut(
+      "  buyer negotiates \u2192 the Agent (sole signer) QUOTES a signed price \u2192"
+    );
+    if (isFreePrice) {
+      printOut(
+        "  buyer funds 0 token units \u2192 the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
+      );
+      printOut(
+        "  after the dispute window, SETTLE completes the job with no token payout."
+      );
+    } else {
+      printOut(
+        "  on payment the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
+      );
+      printOut(
+        "  after the dispute window, SETTLE releases the $U to your wallet."
+      );
+    }
+  }
   printOut("");
   printOut("Agent (the value + the ONLY key-holder/signer)");
   printOut(`  project   : ${shown(g(agent, "project", "name"), "?")}`);
@@ -9086,19 +9409,35 @@ function printConfigSummary(agentRoot2) {
     const ar = autoRenew ? "on \u2014 tops the API key up from your Pieverse balance (no wallet spend)" : "off";
     printOut(`  auto-alloc: ${ar}`);
   }
-  printOut(
-    `  pricing   : list price ${weiToU(String(price))} per job; clamp ceiling ${shown(maxPrice)}`
-  );
-  printOut(
-    `              quote frozen ${shown(
-      g(agent, "payments", "erc8183", "quote_ttl_seconds"),
-      "?"
-    )}s; job timeout ${shown(
-      g(agent, "payments", "erc8183", "default_estimated_completion_seconds"),
-      "?"
-    )}s`
-  );
-  printOut(`              currency ($U token): ${shown(currency)}`);
+  if (hasErc8183) {
+    if (isFreePrice) {
+      printOut(
+        `  pricing   : FREE \u2014 ${weiToU(String(price))} per job; zero token escrow`
+      );
+      printOut(
+        contractOverrides.mode === "custom" ? "              contracts: custom/QA stack selected (all three address overrides)" : "              contracts: configure all three ERC8183_*_ADDRESS overrides before deploy"
+      );
+    } else {
+      printOut(
+        `  pricing   : list price ${weiToU(String(price))} per job; clamp ceiling ${shown(maxPrice)}`
+      );
+    }
+    printOut(
+      `              quote frozen ${shown(
+        g(agent, "payments", "erc8183", "quote_ttl_seconds"),
+        "?"
+      )}s; job timeout ${shown(
+        g(agent, "payments", "erc8183", "default_estimated_completion_seconds"),
+        "?"
+      )}s`
+    );
+    printOut(`              currency ($U token): ${shown(currency)}`);
+  }
+  if (hasX402Seller) {
+    printOut(
+      isFreeX402 ? "  x402      : FREE \u2014 anonymous passthrough; B402 verify/settle is bypassed" : `  x402      : PAID \u2014 $${shown(x402Seller.price_usd, DEFAULT_B402_PRICE_USD)} per request through B402`
+    );
+  }
   printOut(
     `  storage   : ${storageDesc}  (options: local | ipfs \u2014 ipfs required to deploy)`
   );
@@ -9108,12 +9447,22 @@ function printConfigSummary(agentRoot2) {
   }
   printOut("");
   const todo = [];
-  if (!currency) {
+  if (hasErc8183 && !currency) {
     todo.push("[payments.erc8183].currency \u2014 the $U token address");
   }
-  if (!maxPrice) {
+  if (hasErc8183 && !maxPrice && !isFreePrice) {
     todo.push("[payments.erc8183].max_price \u2014 the price clamp ceiling");
   }
+  if (hasErc8183 && isFreePrice && contractOverrides.mode !== "custom") {
+    todo.push(
+      "ERC8183_COMMERCE_ADDRESS / ROUTER_ADDRESS / POLICY_ADDRESS \u2014 select one zero-price-compatible QA/custom contract stack"
+    );
+  }
+  if (hasX402Seller && !isFreeX402) {
+    todo.push(
+      "B402_BASE_URL / CLIENT_ID / ACCESS_TOKEN / private key \u2014 required for PAID /x402"
+    );
+  }
   if (storageKind2 === "local") {
     todo.push(
       "[storage].kind \u2014 switch to 'ipfs' + set STORAGE_API_URL/STORAGE_API_KEY before deploy (local disk is NOT deployable)"
@@ -9392,8 +9741,13 @@ function runtimeEnvKeys(agentDir) {
   if (resolvable("RPC_URL")) {
     keys.push("RPC_URL");
   }
+  if (commerceRails(cfg).erc8183) {
+    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
   const runtime = String(tableOf7(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && commerceRails(cfg).x402) {
+  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
     for (const key of B402_RUNTIME_KEYS) {
       if (resolvable(key)) keys.push(key);
     }
@@ -9777,8 +10131,11 @@ Switch to Node \u226522 so it wins on PATH, then reopen the shell and retry. Ver
     );
   }
   if (hasX402Face(faces)) {
+    const free = x402SellerIsFree(
+      loadStudioToml10(path22.join(agentDir, "studio.toml"))
+    );
     printOut(
-      `bag dev: x402 seller at http://localhost:${agentPort}/x402 (active when B402 credentials are configured)`
+      free ? `bag dev: x402 seller at http://localhost:${agentPort}/x402 (FREE \u2014 anonymous passthrough; B402 bypassed)` : `bag dev: x402 seller at http://localhost:${agentPort}/x402 (PAID \u2014 active when B402 credentials are configured)`
     );
   }
   await launch();
@@ -9885,8 +10242,13 @@ function runtimeEnvKeys2(agentRoot2) {
   if (resolvable("RPC_URL")) {
     keys.push("RPC_URL");
   }
+  if (commerceRails(cfg).erc8183) {
+    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
   const runtime = String(tableOf2(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && commerceRails(cfg).x402) {
+  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
     for (const key of B402_RUNTIME_KEYS) {
       if (resolvable(key)) keys.push(key);
     }
@@ -10226,51 +10588,76 @@ async function checkPieverseKeyHash(root, _target) {
     }
   ];
 }
-var MIN_PRICE_WEI = 1000000000n;
-var MAX_UINT256 = 2n ** 256n - 1n;
 function erc8183RailChecks(cfg) {
   const c2 = tableOf2(tableOf2(cfg, "payments"), "erc8183");
-  const raw = (key, dflt) => {
-    const s = String(c2[key] ?? "").trim();
-    if (!s) {
-      return dflt;
-    }
-    try {
-      return BigInt(s);
-    } catch {
-      return dflt;
-    }
-  };
   const out = [];
-  const minPrice = raw("min_price", 0n);
-  const maxPrice = raw("max_price", MAX_UINT256);
-  const listPrice = raw("price", 0n);
-  const clampedToMax = listPrice < maxPrice ? listPrice : maxPrice;
-  const effective = minPrice > clampedToMax ? minPrice : clampedToMax;
-  if (effective < MIN_PRICE_WEI) {
-    const priceUnset = !String(c2.price ?? "").trim();
-    const clamped = listPrice >= MIN_PRICE_WEI && MIN_PRICE_WEI > effective;
-    let cause;
-    if (priceUnset) {
-      cause = "[payments.erc8183].price is unset, so every quote defaults to 0";
-    } else if (clamped) {
-      cause = `the list price (${listPrice} wei) is clamped to ${effective} wei by [payments.erc8183].max_price`;
-    } else {
-      cause = `the effective quote price is ${effective} wei`;
-    }
+  const contracts = erc8183ContractOverrideState();
+  if (contracts.mode === "partial") {
     out.push({
       level: Level.CRITICAL,
-      name: "commerce_price_below_min",
-      message: `${cause}; the agent would quote for free / below the contract minimum of ${MIN_PRICE_WEI} wei (1 gwei). v1 rejects price-0 / sub-gwei tasks, so no job can ever fund. Set [payments.erc8183].price (and check max_price) in studio.toml.`,
-      fixCmd: "bag config set payments.erc8183.price 1000000000",
+      name: "commerce_contract_override_incomplete",
+      message: `The ERC-8183 contract override is incomplete. Set ${contracts.missing.join(", ")} so commerce, router, and policy come from one compatible contract stack.`,
       details: {
-        effective_wei: String(effective),
-        list_price_wei: String(listPrice),
-        min_price_wei: String(minPrice),
-        max_price_wei: String(maxPrice),
-        min_required_wei: String(MIN_PRICE_WEI)
+        present: contracts.present,
+        missing: contracts.missing
       }
     });
+  } else if (contracts.mode === "invalid") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_contract_override_invalid",
+      message: `The following ERC-8183 contract overrides are not valid EVM addresses: ${contracts.invalid.join(", ")}.`,
+      details: { invalid: contracts.invalid }
+    });
+  }
+  const pricing = erc8183PricingState(c2);
+  if (pricing.kind === "unset") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_price_unset",
+      message: "[payments.erc8183].price is unset. Set it explicitly to 0 for a free job or to a positive integer amount in token base units.",
+      fixCmd: "bag config set payments.erc8183.price 100000000000000000",
+      details: {}
+    });
+  } else if (pricing.kind === "invalid") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_price_invalid",
+      message: `[payments.erc8183].${pricing.field} must be a non-negative uint256 decimal string; got ${JSON.stringify(pricing.value)}.`,
+      fixCmd: "bag config set payments.erc8183.price 100000000000000000",
+      details: {
+        configured_field: pricing.field,
+        configured_value: pricing.value
+      }
+    });
+  } else if (pricing.kind === "clamped_to_zero") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_price_clamped_to_zero",
+      message: `The list price (${pricing.listPrice} token base units) is clamped to 0 by [payments.erc8183].max_price. Set price explicitly to 0 to opt into free jobs, or fix the clamp.`,
+      details: {
+        effective_wei: "0",
+        list_price_wei: String(pricing.listPrice),
+        min_price_wei: String(pricing.minPrice),
+        max_price_wei: String(pricing.maxPrice)
+      }
+    });
+  } else if (pricing.kind === "free") {
+    if (contracts.mode === "canonical") {
+      out.push({
+        level: Level.CRITICAL,
+        name: "commerce_zero_price_contract_unsupported",
+        message: "ERC-8183 pricing is FREE (zero token escrow), but the canonical contract stack rejects zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible QA/custom stack.",
+        details: { effective_wei: "0", contract_profile: "canonical" }
+      });
+    } else if (contracts.mode === "custom") {
+      out.push({
+        level: Level.INFO,
+        name: "commerce_zero_price_enabled",
+        message: "ERC-8183 pricing is FREE \u2014 buyers fund 0 token units with zero token escrow; a complete custom/QA contract stack is selected.",
+        details: { effective_wei: "0", contract_profile: "custom" }
+      });
+    }
   }
   if (String(c2.currency ?? "").trim() === "") {
     out.push({
@@ -10306,15 +10693,24 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
   const rails = commerceRails(cfg);
   const credentials = b402Credentials(agentRoot2);
   const out = [];
+  const pricing = x402SellerPricingState(seller);
+  const free = rails.x402 && pricing.kind === "free";
+  const paid = rails.x402 && pricing.kind === "paid";
   if (sellerPresent) {
-    const price = seller.price_usd === void 0 ? "0.01" : typeof seller.price_usd === "string" ? seller.price_usd : "";
-    if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(price)) {
+    if (pricing.kind === "invalid") {
       out.push({
         level: Level.CRITICAL,
         name: "x402_price_invalid",
         message: '[payments.x402_seller].price_usd must be a non-negative decimal string; "0" is valid and enables the free passthrough.',
         details: {}
       });
+    } else if (free) {
+      out.push({
+        level: Level.INFO,
+        name: "x402_zero_price_enabled",
+        message: "The x402 seller is explicitly FREE. /x402 is anonymous, and B402 verify/settle, token payment, and settlement audit are bypassed.",
+        details: { price_usd: pricing.priceUsd, facilitator_bypassed: true }
+      });
     }
     const assets = seller.assets ?? ["U"];
     if (!Array.isArray(assets) || assets.length !== 1 || assets[0] !== "U") {
@@ -10336,7 +10732,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
     }
   }
   const walletKind2 = String(tableOf2(cfg, "wallet").kind ?? "evm-local");
-  if (rails.x402 && !["evm-local", "twak"].includes(walletKind2)) {
+  if (paid && !["evm-local", "twak"].includes(walletKind2)) {
     out.push({
       level: Level.CRITICAL,
       name: "x402_wallet_kind_unsupported",
@@ -10344,7 +10740,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: { walletKind: walletKind2 }
     });
   }
-  if (credentials.any && !credentials.complete) {
+  if (paid && credentials.any && !credentials.complete) {
     out.push({
       level: Level.CRITICAL,
       name: "x402_credentials_partial",
@@ -10352,7 +10748,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: { present: credentials.presentKeys }
     });
   }
-  if (credentials.bothPrivateKeyFormats) {
+  if (paid && credentials.bothPrivateKeyFormats) {
     out.push({
       level: Level.WARNING,
       name: "x402_private_key_ambiguous",
@@ -10360,7 +10756,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: {}
     });
   }
-  if (rails.x402 && !credentials.any) {
+  if (paid && !credentials.any) {
     out.push({
       level: rails.erc8183 ? Level.WARNING : Level.CRITICAL,
       name: "x402_credentials_missing",
@@ -10368,15 +10764,15 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: {}
     });
   }
-  if (!rails.x402 && credentials.any) {
+  if ((!rails.x402 || free) && credentials.any) {
     out.push({
       level: Level.WARNING,
       name: "x402_credentials_unused",
-      message: "B402 credentials are configured but the x402 seller rail is absent or disabled; they will not be synchronized.",
+      message: free ? "B402 credentials are configured but FREE x402 bypasses the facilitator; they will not be synchronized." : "B402 credentials are configured but the x402 seller rail is absent or disabled; they will not be synchronized.",
       details: { present: credentials.presentKeys }
     });
   }
-  if (credentials.baseUrl !== null) {
+  if (paid && credentials.baseUrl !== null) {
     const network = String(
       tableOf2(cfg, "network").default ?? "bsc-mainnet"
     ).toLowerCase();
@@ -10393,12 +10789,12 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
   }
   const destination = String(tableOf2(cfg, "deploy").destination ?? "self");
   const stackRuntime2 = String(tableOf2(cfg, "stack").runtime ?? "agentcore");
-  if (rails.x402 && credentials.complete && destination !== "platform" && (target !== "agentcore" || stackRuntime2 !== "agentcore")) {
+  if (rails.x402 && (free || credentials.complete) && destination !== "platform" && (target !== "agentcore" || stackRuntime2 !== "agentcore")) {
     const blocking = target !== "agentcore" ? target : stackRuntime2;
     out.push({
       level: Level.WARNING,
       name: "x402_forced_dormant_runtime",
-      message: `x402 seller credentials are complete, but the ${blocking} runtime has no x402 path; this target is forced dormant. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`,
+      message: `x402 pricing is ready, but the ${blocking} runtime has no x402 path; this target is forced dormant. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`,
       details: { destination, target, stackRuntime: stackRuntime2 }
     });
   }
@@ -12243,6 +12639,7 @@ async function runPrepare(opts = {}) {
           checkLocalKeystoreExists,
           checkWalletPasswordEnvSet,
           checkLlmProviderKeySet,
+          checkCommerceReady,
           ...azureFoundryChecks
         ],
         root,
@@ -13315,6 +13712,8 @@ function printAccessNextSteps(root, _invokeUrl) {
   const agentRoot2 = findSubProjectRoot15("agent", root) ?? root;
   const access = buyerAccess(agentRoot2);
   const x402Only = access.faces.length === 1 && hasX402Face(access.faces);
+  const x402Free = x402SellerIsFree(loadAgentCfg(agentRoot2));
+  const x402RouteLabel = x402Free ? "anonymous FREE route" : "anonymous paid route";
   emit("\nAccess your agent \u2014");
   if (access.agentId) {
     if (!x402Only) {
@@ -13332,7 +13731,7 @@ function printAccessNextSteps(root, _invokeUrl) {
       );
     }
     if (hasX402Face(access.faces)) {
-      emit(`  x402 endpoint:  ${access.x402Url}  (anonymous paid route)`);
+      emit(`  x402 endpoint:  ${access.x402Url}  (${x402RouteLabel})`);
     }
     if (!x402Only) {
       emit(
@@ -13357,7 +13756,7 @@ function printAccessNextSteps(root, _invokeUrl) {
       );
     }
     if (hasX402Face(access.faces)) {
-      emit(`  x402 endpoint:  ${rtTmpl}/x402  (anonymous paid route)`);
+      emit(`  x402 endpoint:  ${rtTmpl}/x402  (${x402RouteLabel})`);
     }
     if (x402Only) {
       emit("  protocol discovery is suppressed for this X402-only deployment.");
@@ -13388,7 +13787,9 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   const tokenSteps = `  1) run \`bag platform invoke-client new\` -> client_id + client_secret (secret shown ONCE).
   2) POST client_credentials to ${tokenUrl} with scope \`${scope}\` -> access_token.
   3) send \`Authorization: Bearer <token>\`.`;
-  const rails = commerceRails(loadAgentCfg(agentRoot2));
+  const agentCfg = loadAgentCfg(agentRoot2);
+  const rails = commerceRails(agentCfg);
+  const x402Free = x402SellerIsFree(agentCfg);
   const x402Only = faces.length === 1 && hasX402Face(faces) || rails.x402 && !rails.erc8183;
   const x402Summary = x402DeploySummary(agentRoot2, "platform", access.x402Url);
   const endpoints = [];
@@ -13406,7 +13807,7 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   }
   if (x402Only) {
     endpoints.push(
-      `  [X402] Anonymous paid endpoint: ${access.x402Url ?? `${rt}/x402`}
+      `  [X402] Anonymous ${x402Free ? "FREE" : "paid"} endpoint: ${access.x402Url ?? `${rt}/x402`}
          Protocol discovery is suppressed.`
     );
   }
@@ -13454,7 +13855,7 @@ function printAgentClientPrompt(root, invokeUrl, status) {
     ] : [],
     "",
     "YOUR TASK",
-    x402Only ? "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
+    x402Only ? x402Free ? "Call the anonymous FREE /x402 endpoint directly. Do not create a payment or call the OAuth2 ERC-8183 endpoint." : "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
     CLIENT_PROMPT_RULE
   ];
   const text2 = lines.join("\n");
@@ -14731,7 +15132,9 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
   const tokenSteps = `  1) token endpoint ${tokenUrl} (scope \`${scope}\`); ${credentialStep}.
   2) POST client_credentials -> access_token.
   3) send \`Authorization: Bearer <token>\` AND header \`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <stable id >= 33 chars>\`.`;
-  const rails = commerceRails(loadAgentCfg2(agentRoot2) ?? {});
+  const agentCfg = loadAgentCfg2(agentRoot2) ?? {};
+  const rails = commerceRails(agentCfg);
+  const x402Free = x402SellerIsFree(agentCfg);
   const x402Only = rails.x402 && !rails.erc8183;
   const x402Summary = x402DeploySummary(agentRoot2, destination, null);
   const faces = agentFacesOf(agentRoot2);
@@ -14784,7 +15187,7 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
     ] : [],
     "",
     "YOUR TASK",
-    x402Only ? "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
+    x402Only ? x402Free ? "Call the anonymous FREE /x402 endpoint directly. Do not create a payment or call the OAuth2 ERC-8183 endpoint." : "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
     CLIENT_PROMPT_RULE2
   ];
   const text2 = lines.join("\n");
@@ -15426,7 +15829,9 @@ async function cmdDoctor(opts) {
   checks.push(...await checkLlm(data, projectRoot));
   checks.push(...await checkNetwork(data, opts.network));
   checks.push(...checkCurrency(data));
+  checks.push(...checkErc8183Pricing(data));
   checks.push(...checkPriceBounds(data));
+  checks.push(...checkX402Seller(data, projectRoot));
   checks.push(...checkStorage(data));
   checks.push(...await checkBalances(projectRoot, data, opts.network));
   checks.push(...await checkPieverseMainnetU(projectRoot, data));
@@ -16034,10 +16439,94 @@ function checkCurrency(data) {
   }
   return [];
 }
+function checkErc8183Pricing(data) {
+  const payValue = tableOf13(data, "payments").erc8183;
+  if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
+    return [];
+  }
+  const pay = payValue;
+  const pricing = erc8183PricingState(pay);
+  if (pricing.kind === "unset") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: "[payments.erc8183].price is unset \u2014 set it explicitly to 0 for FREE or to a positive integer string in token base units."
+      }
+    ];
+  }
+  if (pricing.kind === "invalid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `[payments.erc8183].${pricing.field} must be a non-negative uint256 decimal string; got ${JSON.stringify(pricing.value)}.`
+      }
+    ];
+  }
+  if (pricing.kind === "clamped_to_zero") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `PAID list price ${pricing.listPrice} is clamped to 0 by max_price. Set price explicitly to 0 for FREE or fix the clamp.`
+      }
+    ];
+  }
+  const contracts = erc8183ContractOverrideState();
+  const priceMode = pricing.kind === "free" ? "FREE \u2014 zero token escrow" : `PAID \u2014 effective list price ${pricing.effectivePrice} token base units`;
+  if (contracts.mode === "partial") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `${priceMode}, but the ERC-8183 contract override is incomplete. Set ${contracts.missing.join(", ")} so commerce, router, and policy come from one compatible stack.`
+      }
+    ];
+  }
+  if (contracts.mode === "invalid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `${priceMode}, but these contract overrides are not valid EVM addresses: ${contracts.invalid.join(", ")}.`
+      }
+    ];
+  }
+  if (pricing.kind === "paid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: PASS,
+        detail: `${priceMode}.`
+      }
+    ];
+  }
+  if (contracts.mode === "custom") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: PASS,
+        detail: "FREE \u2014 zero token escrow; custom/QA contract stack selected with all three ERC-8183 address overrides."
+      }
+    ];
+  }
+  return [
+    {
+      name: "erc8183 pricing",
+      status: FAIL,
+      detail: "FREE \u2014 zero token escrow, but the canonical ERC-8183 contracts reject zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible QA/custom stack."
+    }
+  ];
+}
 function checkPriceBounds(data) {
-  const pay = tableOf13(tableOf13(data, "payments"), "erc8183");
+  const payValue = tableOf13(data, "payments").erc8183;
+  if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
+    return [];
+  }
+  const pay = payValue;
   const maxPrice = String(pay.max_price ?? "").trim();
-  if (!maxPrice || maxPrice === "0") {
+  if (!maxPrice && erc8183PricingState(pay).kind !== "free") {
     return [
       {
         name: "erc8183 price bounds",
@@ -16048,6 +16537,84 @@ function checkPriceBounds(data) {
   }
   return [];
 }
+function checkX402Seller(data, agentRoot2) {
+  const payments = tableOf13(data, "payments");
+  const sellerValue = payments.x402_seller;
+  if (sellerValue === null || typeof sellerValue !== "object" || Array.isArray(sellerValue)) {
+    return [];
+  }
+  const seller = sellerValue;
+  if (seller.enabled !== true) return [];
+  const pricing = x402SellerPricingState(seller);
+  if (pricing.kind === "invalid") {
+    return [
+      {
+        name: "x402 pricing",
+        status: FAIL,
+        detail: "[payments.x402_seller].price_usd must be a non-negative decimal string."
+      }
+    ];
+  }
+  const runtime = String(tableOf13(data, "stack").runtime ?? "agentcore");
+  const hasErc8183 = payments.erc8183 !== null && typeof payments.erc8183 === "object" && !Array.isArray(payments.erc8183);
+  const fallbackStatus = hasErc8183 ? WARN : FAIL;
+  if (pricing.kind === "free") {
+    const out2 = [
+      {
+        name: "x402 pricing",
+        status: PASS,
+        detail: "FREE \u2014 /x402 is anonymous; B402 verify/settle, token payment, and settlement audit are bypassed."
+      }
+    ];
+    const credentials2 = b402Credentials(agentRoot2);
+    if (credentials2.any) {
+      out2.push({
+        name: "x402 credentials",
+        status: INFO,
+        detail: "configured B402 credentials are unused in FREE mode and will not be synchronized."
+      });
+    }
+    if (runtime !== "agentcore") {
+      out2.push({
+        name: "x402 runtime",
+        status: fallbackStatus,
+        detail: `${runtime} has no /x402 route; FREE pricing does not remove that runtime limitation.`
+      });
+    }
+    return out2;
+  }
+  const out = [
+    {
+      name: "x402 pricing",
+      status: PASS,
+      detail: `PAID \u2014 $${pricing.priceUsd} per request through B402.`
+    }
+  ];
+  const walletKind2 = String(tableOf13(data, "wallet").kind ?? "evm-local");
+  if (!["evm-local", "twak"].includes(walletKind2)) {
+    out.push({
+      name: "x402 payout wallet",
+      status: FAIL,
+      detail: `PAID B402 supports evm-local or twak, not ${walletKind2}.`
+    });
+  }
+  const credentials = b402Credentials(agentRoot2);
+  if (!credentials.complete) {
+    out.push({
+      name: "x402 credentials",
+      status: credentials.any ? FAIL : fallbackStatus,
+      detail: credentials.any ? "B402 credentials are partial; set BASE_URL, CLIENT_ID, ACCESS_TOKEN, and exactly one private-key form." : "PAID mode needs the four B402 merchant credentials; without them the rail starts dormant."
+    });
+  }
+  if (runtime !== "agentcore") {
+    out.push({
+      name: "x402 runtime",
+      status: fallbackStatus,
+      detail: `${runtime} has no /x402 route; deploy this rail to AgentCore.`
+    });
+  }
+  return out;
+}
 function checkStorage(data) {
   const kind = String(tableOf13(data, "storage").kind ?? "local").toLowerCase();
   if (kind === "ipfs") {
@@ -18576,7 +19143,10 @@ function registerX402(program) {
       return 1;
     })
   );
-  sell.command("init").description("Add the x402 seller config and missing B402 placeholders.").action(act(() => cmdSellInit()));
+  sell.command("init").description("Add the x402 seller config and missing B402 placeholders.").option(
+    "--price-usd <amount>",
+    "Per-request decimal USD price; use 0 for FREE passthrough."
+  ).action(act((opts) => cmdSellInit(opts.priceUsd)));
   sell.command("status").description("Show x402 seller config and B402 capability status.").option("--no-probe", "Skip the authenticated B402 /supported probe.").action(act((opts) => cmdSellStatus(opts.probe)));
 }
 function hostOf(url) {
@@ -18661,39 +19231,83 @@ function resolveWallet2() {
 function printScopeError(host) {
   printErr(`error: ${SCOPE_NOTE.replace("{host}", host)}`);
 }
-function cmdSellInit() {
+async function cmdSellInit(priceFlag) {
   const loaded = loadSellerConfig();
   if (loaded === null) return 1;
   const [root, cfg] = loaded;
+  const tomlPath = path46.join(root, "studio.toml");
+  const original = fs44.readFileSync(tomlPath, "utf8");
+  const sellerExists = hasSection(original, "payments.x402_seller");
+  let priceUsd;
+  try {
+    priceUsd = priceFlag !== void 0 ? normalizeB402PriceUsd(priceFlag) : sellerExists ? X402SellerPolicy.fromToml(cfg).priceUsd : await resolveSellInitPrice(stdinIsTty());
+  } catch (exc) {
+    printErr(`error: ${errMsg6(exc)}`);
+    return 2;
+  }
+  const free = x402SellerPricingState({ price_usd: priceUsd }).kind === "free";
   const walletKind2 = String(tableOf15(cfg, "wallet").kind ?? "evm-local");
-  if (!["evm-local", "twak"].includes(walletKind2)) {
+  if (!free && !["evm-local", "twak"].includes(walletKind2)) {
     printErr(
       `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet.`
     );
     return 1;
   }
-  const tomlPath = path46.join(root, "studio.toml");
-  const original = fs44.readFileSync(tomlPath, "utf8");
-  if (!hasSection(original, "payments.x402_seller")) {
+  if (!sellerExists) {
     fs44.writeFileSync(
       tomlPath,
       updateSection(original, "payments.x402_seller", {
         enabled: true,
-        price_usd: "0.01",
+        price_usd: priceUsd,
         assets: ["U"],
         pay_to: "",
         work_timeout_seconds: 60
       }),
       "utf8"
     );
+  } else if (priceFlag !== void 0) {
+    fs44.writeFileSync(
+      tomlPath,
+      updateSection(original, "payments.x402_seller", {
+        price_usd: priceUsd
+      }),
+      "utf8"
+    );
   }
   const envPath = envLocalPath17(root);
   for (const key of B402_ENV_KEYS) {
     if (getEnvVar(envPath, key) === null) setEnvVar(envPath, key, "");
   }
-  printOut("\u2713 x402 seller config and B402 placeholders are ready.");
+  printOut(
+    free ? "\u2713 x402 seller config is ready in FREE mode; B402 credentials are not required." : "\u2713 x402 seller config and B402 placeholders are ready for PAID mode."
+  );
+  if (free) {
+    printErr(
+      "warning: /x402 is an anonymous FREE endpoint; B402 verify/settle and payment audit are bypassed."
+    );
+  }
   return 0;
 }
+async function resolveSellInitPrice(isTty) {
+  if (!isTty) return DEFAULT_B402_PRICE_USD;
+  const choice = (await promptUser(
+    "B402/x402 pricing [paid/free/custom, Enter = paid ($0.01)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") return "0";
+  if (choice === "custom") {
+    return normalizeB402PriceUsd(
+      await promptUser(
+        "B402/x402 per-request price in USD (non-negative decimal): "
+      )
+    );
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(
+      `hint: unknown B402/x402 pricing choice '${choice}' \u2014 using paid.`
+    );
+  }
+  return DEFAULT_B402_PRICE_USD;
+}
 async function cmdSellStatus(probe) {
   const loaded = loadSellerConfig();
   if (loaded === null) return 1;
@@ -18714,9 +19328,13 @@ async function cmdSellStatus(probe) {
   };
   const privateKeySet = presence.B402_PRIVATE_KEY || presence.B402_PRIVATE_KEY_B64;
   const credentialsComplete = presence.B402_BASE_URL && presence.B402_CLIENT_ID && presence.B402_ACCESS_TOKEN && privateKeySet;
-  const state = !policy.enabled ? "disabled" : credentialsComplete ? "active-config" : "dormant";
+  const free = x402SellerPricingState({ price_usd: policy.priceUsd }).kind === "free";
+  const state = !policy.enabled ? "disabled" : free ? "free" : credentialsComplete ? "active-config" : "dormant";
   printOut(`Rail state: ${state}`);
   printOut(`  price_usd: ${policy.priceUsd}`);
+  printOut(
+    `  Pricing: ${free ? "FREE \u2014 anonymous passthrough; no payment" : "PAID \u2014 B402 verify/settle required"}`
+  );
   printOut(`  assets: ${JSON.stringify(policy.assets)}`);
   printOut(`  pay_to: ${policy.payTo ?? "(agent wallet)"}`);
   printOut(`  work_timeout_seconds: ${policy.workTimeoutSeconds}`);
@@ -18729,6 +19347,10 @@ async function cmdSellStatus(probe) {
     printOut("B402 probe: skipped (--no-probe)");
     return 0;
   }
+  if (policy.enabled && free) {
+    printOut("B402 probe: skipped (FREE bypasses B402)");
+    return 0;
+  }
   if (!policy.enabled || !credentialsComplete) {
     printOut("B402 probe: skipped (rail disabled or credentials incomplete)");
     return 0;
@@ -19162,7 +19784,7 @@ function buildProgram() {
   return program;
 }
 function cliVersion() {
-  return "0.0.6-alpha.1";
+  return "0.0.6-alpha.2";
 }
 
 // src/cli/updateCheck.ts