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

package/dist/{chunk-M3ODFCA7.js → chunk-6EYSXRFD.js}

@@ -293,6 +293,44 @@ function mb(n) {
   return `${(n / (1024 * 1024)).toFixed(1)}MB`;
 }
 
+// src/cli/_x402SellerConfig.ts
+var DEFAULT_B402_PRICE_USD = "0.01";
+var PRICE_USD_RE = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
+var ZERO_PRICE_USD_RE = /^0(?:\.0+)?$/;
+function x402SellerPricingState(seller) {
+  const raw = seller.price_usd;
+  const priceUsd = raw === void 0 ? DEFAULT_B402_PRICE_USD : typeof raw === "string" ? raw : "";
+  if (!PRICE_USD_RE.test(priceUsd)) {
+    return { kind: "invalid", value: String(raw ?? "") };
+  }
+  return {
+    kind: ZERO_PRICE_USD_RE.test(priceUsd) ? "free" : "paid",
+    priceUsd
+  };
+}
+function normalizeB402PriceUsd(value) {
+  const normalized = value.trim();
+  if (!PRICE_USD_RE.test(normalized)) {
+    throw new Error(
+      `B402 price must be a non-negative decimal USD string; got ${JSON.stringify(value)}.`
+    );
+  }
+  return normalized;
+}
+function x402SellerUsesB402(cfg) {
+  const payments = table2(cfg.payments);
+  const seller = table2(payments.x402_seller);
+  return seller.enabled === true && x402SellerPricingState(seller).kind === "paid";
+}
+function x402SellerIsFree(cfg) {
+  const payments = table2(cfg.payments);
+  const seller = table2(payments.x402_seller);
+  return seller.enabled === true && x402SellerPricingState(seller).kind === "free";
+}
+function table2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
 // src/cli/exit.ts
 var CliExit = class extends Error {
   constructor(code) {
@@ -597,10 +635,10 @@ var B402_RUNTIME_KEYS = [
   "B402_PRIVATE_KEY_B64"
 ];
 function commerceRails(cfg) {
-  const payments = table2(cfg.payments);
+  const payments = table3(cfg.payments);
   return {
     erc8183: isTable(payments.erc8183),
-    x402: table2(payments.x402_seller).enabled === true
+    x402: table3(payments.x402_seller).enabled === true
   };
 }
 function b402Credentials(agentRoot) {
@@ -633,15 +671,36 @@ function loadDeployConfig(root) {
 function x402DeploySummary(root, destination, publicUrl) {
   const { agentRoot, cfg } = loadDeployConfig(root);
   if (!commerceRails(cfg).x402) return "";
+  const seller = table3(table3(cfg.payments).x402_seller);
+  const pricing = x402SellerPricingState(seller);
   const credentials = b402Credentials(agentRoot);
   const activation = "run the bnbagent-studio-selling-via-b402 skill, fill the four B402_* variables in .studio/.env.local, then redeploy.";
-  if (!credentials.complete) {
-    return `x402 rail is DORMANT. To activate: ${activation}`;
-  }
-  const runtime = String(table2(cfg.stack).runtime ?? "agentcore");
+  const runtime = String(table3(cfg.stack).runtime ?? "agentcore");
   if (destination !== "platform" && runtime !== "agentcore") {
     return `x402 rail is FORCED DORMANT: the ${runtime} runtime has no x402 path. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`;
   }
+  if (pricing.kind === "invalid") {
+    return "x402 rail is DORMANT: price_usd is invalid; run `bag doctor`.";
+  }
+  if (pricing.kind === "free") {
+    if (destination !== "platform") {
+      return [
+        "x402 rail is ACTIVE in FREE mode (self-hosted AgentCore).",
+        "B402 verify/settle is bypassed; no credentials, token payment, or settlement audit is used.",
+        "This target has no anonymous public URL; expose /x402 with your own HTTP front.",
+        'The front reaches the agent by wrapping each request as envelope-v1 JSON \u2014 {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"} \u2014 inside a SigV4-signed (or JWT bearer) InvokeAgentRuntime call. Limits: 1 MiB request, 5 MiB response, no streaming.'
+      ].join("\n");
+    }
+    const url2 = publicUrl ?? "<available after the platform agentId is assigned>";
+    return [
+      "x402 rail is ACTIVE in FREE mode.",
+      `Anonymous FREE URL: ${url2}`,
+      "B402 verify/settle is bypassed; no credentials, token payment, or settlement audit is used."
+    ].join("\n");
+  }
+  if (!credentials.complete) {
+    return `x402 rail is DORMANT. To activate: ${activation}`;
+  }
   const settlement = [
     "B402 settlement runs inside every paid request and normally adds 10\u201345 s; buyer timeout must be at least 120 s.",
     "Settlement happens before work. If work later fails, the payment is retained and is not refunded automatically."
@@ -663,7 +722,7 @@ function x402DeploySummary(root, destination, publicUrl) {
     ...settlement
   ].join("\n");
 }
-function table2(value) {
+function table3(value) {
   return isTable(value) ? value : {};
 }
 function isTable(value) {
@@ -735,14 +794,14 @@ function deployCommand(environment = process.env) {
   }
   return ["bunx", "--bun", DEPLOY_CLI_PACKAGE];
 }
-function providerPassthrough(studio, table3) {
-  const raw = tableOf(studio, "deploy")[table3];
+function providerPassthrough(studio, table4) {
+  const raw = tableOf(studio, "deploy")[table4];
   if (raw === void 0 || raw === null) {
     return {};
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
     throw new Error(
-      `studio.toml [deploy.${table3}] must be a TOML table of deploy-spec keys`
+      `studio.toml [deploy.${table4}] must be a TOML table of deploy-spec keys`
     );
   }
   return { ...raw };
@@ -835,10 +894,10 @@ function buildDeploySpec(root, opts) {
     }
     doc.foundry = foundry;
   } else {
-    for (const table3 of ["agentcore", "foundry"]) {
-      if (Object.keys(providerPassthrough(studio, table3)).length > 0) {
+    for (const table4 of ["agentcore", "foundry"]) {
+      if (Object.keys(providerPassthrough(studio, table4)).length > 0) {
         printErr(
-          `note: the bnb/trial platform does not allow custom provider configuration; [deploy.${table3}] ignored`
+          `note: the bnb/trial platform does not allow custom provider configuration; [deploy.${table4}] ignored`
         );
       }
     }
@@ -848,7 +907,7 @@ function buildDeploySpec(root, opts) {
   if (opts.inlineSecrets) {
     Object.assign(env, opts.inlineSecrets);
   }
-  if (opts.target === "bnb/trial" && tableOf(studio, "deploy").destination === "platform" && (!hasProtocolsArray || hasX402Face(faces)) && commerceRails(studio).x402 && b402Credentials(agentRoot).complete) {
+  if (opts.target === "bnb/trial" && tableOf(studio, "deploy").destination === "platform" && (!hasProtocolsArray || hasX402Face(faces)) && commerceRails(studio).x402 && (x402SellerIsFree(studio) || b402Credentials(agentRoot).complete)) {
     doc.x402 = {
       publicPaths: ["/x402"],
       tunnel: "http-envelope-v1"
@@ -1019,6 +1078,11 @@ export {
   entryStemOf,
   devPortOf,
   recipeModeOf,
+  DEFAULT_B402_PRICE_USD,
+  x402SellerPricingState,
+  normalizeB402PriceUsd,
+  x402SellerUsesB402,
+  x402SellerIsFree,
   whichBin,
   agentcoreFlavor,
   checkDocker,

package/dist/{deployCli-N6TPN6XA.js → deployCli-3U2FESF4.js}

@@ -17,7 +17,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-M3ODFCA7.js";
+} from "./chunk-6EYSXRFD.js";
 import "./chunk-7RAKL4AS.js";
 export {
   BNB_PLATFORM_API_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.6-alpha.1",
+  "version": "0.0.6-alpha.2",
   "description": "The `bag` CLI: scaffold, run, deploy, and monetize a single seller agent on BNB Chain (ERC-8004 identity, ERC-8183 commerce, x402 payments).",
   "license": "Apache-2.0",
   "repository": {
@@ -37,7 +37,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.6-alpha.1"
+    "@bnbagent/studio-runtime": "0.0.6-alpha.2"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

package/recipes/agent/code/{{PKG}}/signing.ts.tmpl

@@ -111,6 +111,17 @@ function defaultNetworkName(): string {
   return String(((cfg.network ?? {}) as TomlTable).default ?? "bsc-testnet");
 }
 
+/**
+ * Bind provider_sig to the same Commerce deployment used by the runtime
+ * client. QA/custom stacks override the canonical SDK registry via env.
+ */
+export function commerceVerifyingContract(
+  chainId: number,
+): `0x${string}` {
+  const override = process.env.ERC8183_COMMERCE_ADDRESS?.trim();
+  return (override || deployedAddresses(chainId).commerceProxy) as `0x${string}`;
+}
+
 /**
  * Return `[minPrice, maxPrice]` in raw wei from studio.toml.
  *
@@ -182,7 +193,7 @@ function getHandler(): NegotiationHandlerLike {
       ...negotiationSignerOptions(wallet),
       quoteTtlSeconds: ttl,
       chainId: network.chainId,
-      verifyingContract: deployedAddresses(network.chainId).commerceProxy,
+      verifyingContract: commerceVerifyingContract(network.chainId),
     });
   }
   return handler;

package/skills/bnbagent-studio.md

@@ -33,8 +33,9 @@ bounded operations — **`negotiate`** (rule-based price clamp + EIP-191 sign;
 **no LLM touches money**) and **`notify_funded`** (verify the funded job →
 produce the deliverable → submit on-chain; A2A acks then delivers in the
 background, MCP delivers synchronously in the tool call). The optional x402
-rail adds an anonymous paid HTTP request at `/x402`; it settles through B402
-before running work and does not expose a general signing tool. Read-only chain
+rail adds an anonymous HTTP request at `/x402`; positive prices settle through
+B402 before work, while explicit zero is FREE passthrough and bypasses the
+facilitator. It does not expose a general signing tool. Read-only chain
 tools remain available. ALL signing is fixed entrypoint code in
 `app/agent/src/signing.ts` or the runtime's bounded x402 payment handler, never
 an LLM-callable tool. The encrypted keystore lives at the workspace root
@@ -55,7 +56,7 @@ not answer from memory.
 | Add wallet / the single seller runtime to an existing TypeScript agent | `references/bnbagent-studio-adding-to-project.md` |
 | Run / debug / dev / doctor / RPC / balance / incident triage | `references/bnbagent-studio-operating.md` |
 | Implement what the Agent sells, tune pricing, publish over A2A and/or MCP, defend disputes (seller flow) | `references/bnbagent-studio-selling-via-8183.md` |
-| Sell one paid HTTP request through the B402-backed x402 rail (merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
+| Sell one paid or FREE HTTP request through the B402-backed x402 rail (pricing choice; paid merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
 | Deploy / redeploy / status / logs / destroy | Run `bag deploy` and explicitly choose a provider. Non-interactive deploy requires `--provider bnb\|aws\|azure --yes` (and `--allow-multiple` when keeping another provider active). Read `references/bnbagent-studio-use-bnb-trial.md`, `references/bnbagent-studio-use-aws-agentcore.md`, or `references/bnbagent-studio-use-azure-foundry.md` for the selected provider. `bag deploy status` lists every recorded provider; multi-deployment logs/verify/destroy require `--provider`. |
 | Wire chain-read tools into the Agent's LLM (AI SDK `tool()` wrappers, or any TS agent framework) | `references/bnbagent-studio-wiring-llm-tools.md` |
 | Buy a service from another ERC-8183 seller via CLI — incl. testing your own seller from the buyer side (v2/internal — NOT the v1 seller product flow) | `references/bnbagent-studio-buying-via-8183.md` |
@@ -84,10 +85,18 @@ must NOT be added to the description — see docs/design/decisions.md §14. -->
 
 1. **Agent project code is user-owned** — recipe-emitted files are theirs to edit; studio doesn't auto-rewrite them.
 2. **Private keys live in a user-controlled environment, never transmitted to studio or third parties** — the encrypted keystore lives at the workspace root, outside the deploy codeLocation (no packaging path can bundle it). Altana keeps its admin keystore there and gives local runtime only a bounded session; deployment is blocked. Other supported deploy paths inject only their required wallet material into the selected runtime secret channel. (Scoped, consented exception: provider `bnb`, the 48h testnet trial — testnet-forced, throwaway wallet recommended.)
-3. **Signing is fixed handler code, never an LLM-callable tool** — the ERC-8183 rail exposes bounded `negotiate` / `notify_funded` flows and the x402 rail exposes a bounded paid-request handler; raw/arbitrary signing is never exposed. Read-only chain queries remain read-only tools.
+3. **Signing is fixed handler code, never an LLM-callable tool** — the ERC-8183 rail exposes bounded `negotiate` / `notify_funded` flows and the x402 rail exposes a bounded request handler; raw/arbitrary signing is never exposed. Read-only chain queries remain read-only tools.
 4. **SDK protocol layer stays pure** — studio's opinions don't pollute `bnbagent-sdk`.
 5. **The user can jump ship at any point** — emitted code is theirs to edit / fork / migrate; studio depends on no closed SaaS. Emitted code imports from `@bnbagent/studio-runtime` and depends on that runtime lib (not the CLI), so uninstalling the `@bnbagent/studio-cli` package never breaks a deployed agent.
 
+Treat ERC-8183 amounts as decimal strings at CLI/config boundaries and
+`bigint` internally. `price = "0"` is an explicit FREE choice, not a missing
+value; it requires all three contract-address overrides from one verified
+zero-price-compatible stack.
+Treat B402 `price_usd` as a decimal string too. `"0"` is explicit anonymous
+FREE passthrough: B402 verify/settle and secret injection are skipped. Positive
+prices retain the paid merchant flow.
+
 ## CLI groups at a glance
 
 `init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` — see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure]` is the primary deploy command; `prepare`, `verify`, `status`, `info`, `destroy`, `logs`, `fix-gitignore`, and `provision-cognito` remain lifecycle subcommands (`deploy agent` is a deprecated compatibility alias). Provider deploy/status/logs/destroy and deploy-time credential validation are delegated to pinned `@bnbagent/deploy-cli@0.4.14`.

package/skills/references/bnbagent-studio-adding-to-project.md

@@ -131,6 +131,22 @@ the configured list price, clamps it to `[min_price, max_price]`, then
 from the request *before* clamping — the LLM still never sets the price. The
 buyer anchors the signed envelope on-chain via `createJob` + `fund`.
 
+Use `bag config set payments.erc8183.price 0` only for an explicit FREE
+product decision. Studio stores ERC-8183 amounts as decimal strings and reports
+FREE in `bag doctor`. Zero funding also requires commerce, router, and policy
+from one compatible stack: set all three `ERC8183_*_ADDRESS` overrides, then
+require `bag doctor` and `bag deploy prepare` to pass. The buyer still runs
+`setBudget(0)` and `fund(0)`, but no ERC-20 approval or token escrow occurs.
+
+For an X402 face, choose its request price independently. Use
+`bag config set payments.x402_seller.price_usd 0` only when the existing agent
+is intentionally becoming an unrestricted anonymous FREE API. This path
+bypasses B402 verify/settle, payment, and settlement audit; it needs no merchant
+credentials and Studio will not synchronize any configured B402 secrets.
+Positive prices retain the paid B402 onboarding and settle-before-work flow.
+Verify the choice with `bag x402 sell status`, `bag doctor`, and
+`bag deploy prepare`.
+
 ## Step 4c — LLM credit continuity (automatic, NOT an LLM tool)
 
 For Pieverse projects, the Agent's `buildModel()` factory in the emitted

package/skills/references/bnbagent-studio-buying-via-8183.md

@@ -56,13 +56,17 @@ flow now auto-adds dispute_window).
 ## Preconditions
 
 - `bag doctor` is clean (or only warns on LLM key)
-- Wallet has ≥ 0.05 tBNB (gas) and ≥ 0.2 U (token + slack). On BSC testnet the
+- For a paid job, the wallet has ≥ 0.05 tBNB (gas) and enough U for the budget
+  plus slack. On BSC testnet the
   ERC-8183 kernel writes (`createJob` / `fund` deposit / `settle` …) are
   gas-sponsored via the SDK's MegaFuel paymaster, so you spend far less tBNB than
   that — but **not zero**: `fund` sends an ERC-20 `approve` (a token call, not
   sponsored) when the token allowance is too low — typically just the first fund,
   since studio approves a floored cap that later jobs reuse. Keep a little tBNB for
-  it. (Mainnet is never sponsored.)
+  it. (Mainnet is never sponsored.) For a FREE job, use `--budget-u 0`: no U
+  balance, ERC-20 approval, or token escrow is needed, but the ERC-8183 writes
+  still need the selected gas/paymaster path and a zero-price-compatible
+  commerce/router/policy stack.
 - You know the **provider's wallet address** (the seller agent's address)
 - The seller is **reachable** (its A2A agent is deployed somewhere); discoverable
   via the provider's `bag erc8004 resolve <agent_id>` endpoint URI
@@ -110,6 +114,13 @@ bag erc8183 buy --provider <provider_addr> "<task description>" \
 # `--agent-id` resolves the endpoint + negotiates first.
 ```
 
+For a signed FREE quote:
+
+```bash
+bag erc8183 buy --provider <provider_addr> "<task description>" \
+  --budget-u 0 --deadline-min 30 --network bsc-testnet
+```
+
 > **Task can be passed two ways** (both accepted): as a positional argument
 > `bag erc8183 buy --provider <addr> "<task>"` OR via the flag
 > `bag erc8183 buy --provider <addr> --task "<task>"`. Pass it once — supplying
@@ -120,7 +131,8 @@ The 4 on-chain steps run sequentially:
 1. `createJob(provider, expiredAt, description)` → returns `job_id`
 2. `registerJob(jobId)`
 3. `setBudget(jobId, rawBudget)`
-4. `fund(jobId, rawBudget, approveFloor=rawBudget)` — auto-approves U
+4. `fund(jobId, rawBudget, approveFloor=rawBudget)` — auto-approves U only
+   when the positive budget needs allowance; budget 0 skips approval and escrow
 
 Output prints 4 tx hashes + `job_id`. Note the `job_id` for later.
 
@@ -212,6 +224,10 @@ bag erc8183 status $JOB
 bag erc8183 settle $JOB --action dispute
 ```
 
+For the FREE regression, change the budget to `0` and confirm the compatible
+contract job still reaches `FUNDED` and `SUBMITTED` without an ERC-20 approval
+or balance change.
+
 This is the exact end-to-end flow used to validate real-chain buying. See the
 references below for the canonical picture.
 

package/skills/references/bnbagent-studio-operating.md

@@ -32,6 +32,7 @@ the file when the topic comes up — don't answer from memory:
 - `bnbagent-studio-extending-signing.md` — `PolicyViolation` / `X402PolicyError` diagnosis + extending the EIP-712 allowlist
 - `bnbagent-studio-adding-to-project.md` — adding the seller runtime to an existing TypeScript project
 - `bnbagent-studio-buying-via-8183.md` — buyer flow (find provider → buy → fetch → settle)
+- `bnbagent-studio-selling-via-b402.md` — inbound x402 pricing mode, paid merchant setup, and B402 settlement operations
 
 This playbook covers **generic ops**: dev / doctor / balances / RPC / incident triage.
 For seller job-lifecycle decisions (settle / submit / dispute defense), read
@@ -49,6 +50,7 @@ For seller job-lifecycle decisions (settle / submit / dispute defense), read
 | "how much have I approved 0x... for?" | ⚠️ **v0.2 backlog — `bag erc20 allowance` does not exist in v0.0.x** |
 | "is my agent registered?" | `bag erc8004 show` (note: registration is normally automatic at `bag deploy verify` — manual `bag erc8004 register` only if you need an identity before deploy) |
 | "what's the status of job X?" | `bag erc8183 status <id>` (read-only — neutral) |
+| "is `/x402` paid or free?" | `bag x402 sell status` (`Rail state: paid` probes B402 unless `--no-probe`; `free` skips B402) |
 | "settle job X" | `bag erc8183 settle <id> --action approve\|reject\|dispute` (default `approve`) — **seller's manual step** after the dispute window; deeper context in `bnbagent-studio-selling-via-8183.md` (same directory) |
 | "submit work for job X" | **seller action** — read `bnbagent-studio-selling-via-8183.md` (same directory) for the submit/dispute flow |
 | "tx not confirming" | Read BscScan link from prior tx output + check `eth_getTransactionCount` |
@@ -158,6 +160,19 @@ The `--all` form is the right move when `app/agent/studio.toml`'s
 testnet U pays ERC-8183 jobs, mainnet U pays the Pieverse LLM auto-renew.
 Same wallet address on both chains.
 
+`bag doctor` prints ERC-8183 pricing as `PAID` or `FREE`. FREE is not ready on
+the canonical contract stack: select one zero-price-compatible QA/custom stack
+by setting `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and
+`ERC8183_POLICY_ADDRESS` together. A partial set fails because it can mix
+incompatible commerce, router, and policy deployments.
+
+For the inbound x402 seller rail, `bag doctor` also prints `PAID` or `FREE`.
+PAID requires the complete B402 merchant credential set and an `evm-local` or
+`twak` payout wallet. Explicit zero is anonymous FREE passthrough: it does not
+read B402 credentials, call the facilitator, settle a payment, or apply the
+paid-mode payout-wallet allowlist. Confirm the same state with
+`bag x402 sell status`.
+
 > ⚠️ **v0.2 backlog — not in v0.0.x.** There is **no** `bag wallet transfer`,
 > no `bag erc20 approve/allowance` group, and no `bag wallet balance --address`
 > / `--token` flag in v0.0.x — running any of them errors with
@@ -201,6 +216,10 @@ covered in `bnbagent-studio-selling-via-8183.md` (same directory).
 | `notify_funded` replies `{"status":"rejected","reason":...}` | `verifySignedJob` failed synchronously in the ack — a **permanent** failure | `reason` names it: not our signature / tampered terms / underfunded / expired (or `error` for a malformed `job_id`). The job is refused outright; re-fund/re-notify with a correct, fully-funded job |
 | Job stays `FUNDED`, never reaches `SUBMITTED` after an `accepted` ack | Background delivery failed (`runWork` / `submitResult` raised) — **not** visible in the A2A reply | The ack only confirms verify passed; delivery runs in the background. Observe the failure via the chain (job never leaves `FUNDED`) + CloudWatch logs; a later `notify_funded` re-attempts it via the sweep |
 | `ERC8183JobOps` has no such export from `@bnbagent/sdk` | package.json pinned an old `@bnbagent/sdk` (missing class) | Bump the dependency and reinstall |
+| FREE price fails doctor/prepare on canonical contracts | `price = "0"` is selected without a zero-price-compatible stack | Set all three `ERC8183_*_ADDRESS` overrides from the current apex-contracts `bscTestnetQa` entry, then rerun `bag doctor` and `bag deploy prepare` |
+| ERC-8183 contract override is incomplete | Only one or two of commerce/router/policy were selected | Set or remove all three together; never mix stacks |
+| `/x402` is public without a 402 challenge | `payments.x402_seller.price_usd = "0"` selected anonymous FREE passthrough | If payment is intended, set a positive decimal price, configure the complete B402 credential set, rerun `bag doctor`, and redeploy |
+| B402 credentials are missing but x402 reports FREE | Expected: FREE bypasses B402 and does not synchronize its secrets | No credential fix is needed; change to a positive price only when the route should charge |
 | `OPENROUTER_API_KEY env var is required` | Loading the entrypoint triggers the emitted `buildModel()` factory | Set the env var even for `bag dev --help` smoke |
 | RPC `limit exceeded` | Public RPC throttle | Retry, or set `STUDIO_BSC_TESTNET_RPC=<private rpc>` |
 

package/skills/references/bnbagent-studio-scaffolding-agent.md

@@ -117,6 +117,8 @@ The fields (give the user all of them at once):
 | 7 | **LLM model** | provider catalogue; for `pieverse-llm` the default `auto/free` runs at $0/token | `auto/free` |
 | 8 | **Auto-topup** | `enable` / `disable` — lets the Agent auto-pay $U from the wallet when LLM credits run low | deferred (non-interactive `bag init` records no `[budget]`; enable later with `bag budget enable`) |
 | 9 | **Scaffold destination** (`--destination`) | `self` (prepare the AgentCore scaffold for **your own** AWS account; runtime material stays under your cloud-account control) / `platform` (prepare for a 48h **testnet-only** trial on the BNB Chain managed platform — runs the *same* agent in the **operator's** AWS, so a wallet key **leaves your control**; it hard-forces `[network].default = bsc-testnet`, pins runtime=`agentcore`, packages an artifact, and auth is GitHub device flow. Use a **throwaway** `bag wallet new`, never your main wallet). This is scaffold intent only; deploy still explicitly selects `--provider`. | `platform` while the trial campaign runs (bare init falls back to `self` once it ends, or when `--network bsc-mainnet` / a non-agentcore `--runtime` is passed) |
+| 10 | **ERC-8183 price** (`--erc8183-price`) | non-negative integer string in token base units; `0` explicitly selects FREE | `100000000000000000` (0.1 U) |
+| 11 | **B402/x402 price** (`--b402-price`, when the b402 rail is selected) | non-negative decimal USD string; `0` explicitly selects anonymous FREE passthrough and bypasses B402 | `0.01` |
 
 v1 is **seller-only** — there is no role to choose. `bag init` scaffolds the
 single seller agent under `app/agent/` (serves the selected public faces,
@@ -215,7 +217,7 @@ Step 6b when `storage=ipfs`):
 > keep steps 3/4/6 below. Pass `--no-onboard` to `bag init` to make this
 > explicit and deterministic regardless of how the shell wires stdin.
 
-1. `bag init <name> --llm-provider <p> --network <n> --storage-provider <s> --wallet-kind <k> --no-onboard`
+1. `bag init <name> --llm-provider <p> --network <n> --storage-provider <s> --wallet-kind <k> --rails <8183|b402|both> [--erc8183-price <base-units>] [--b402-price <usd>] --no-onboard`
    — scaffold the v0.0.1 workspace. **`<name>` must start with a letter and be
    ≤23 chars after sanitizing** — `bag init` auto-drops `-`/`_` for the
    AgentCore name (printing what it used) but errors if the alphanumeric form
@@ -229,7 +231,16 @@ Step 6b when `storage=ipfs`):
    faces (omit for A2A default; `--protocol <one>` is only a legacy alias), add
    `--model <m>` only if the user overrode the provider default, and
    `--enable-auto-topup` / `--no-auto-topup` only if they made an explicit
-   choice (otherwise omit — consent stays deferred). **Destination:** while the
+   choice (otherwise omit — consent stays deferred). Pass
+   `--erc8183-price 0` only when the user explicitly chose FREE; omitting the
+   flag preserves the paid 0.1 U default. FREE additionally requires all three
+   `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and
+   `ERC8183_POLICY_ADDRESS` values from one zero-price-compatible QA/custom
+   stack; set them with `bag env set` after scaffolding. For B402, pass
+   `--b402-price 0` only after the user explicitly accepts an unrestricted
+   anonymous FREE `/x402` endpoint. FREE bypasses B402 verify/settle and needs
+   no merchant credentials; a positive price keeps the `$0.01` default and
+   requires the paid onboarding playbook. **Destination:** while the
    trial campaign runs, bare `bag init` (no `--destination`) defaults to
    `platform` — so pass `--destination self` **explicitly** whenever the user
    chose their own AWS, otherwise studio.toml silently records `platform` and the
@@ -344,7 +355,11 @@ Step 6b when `storage=ipfs`):
    brand-new seller can scaffold, run `bag dev`, and deploy with an empty
    wallet. `bag doctor` and `bag deploy` only **WARN** (never block) on zero
    balance. Funding is needed later only for: a paid LLM model, on-chain
-   settle, or paying ERC-8183 job buys. When that time comes, the wallet uses
+   settle, paying positive-price ERC-8183 job buys, or buying/smoking a PAID
+   B402 request. A FREE ERC-8183 buy needs no U
+   escrow or ERC-20 approval, but still needs the ERC-8183 state-changing calls
+   and their gas/paymaster path. A FREE B402/x402 request needs neither token
+   funding nor a facilitator call. When funding is needed, the wallet uses
    **TWO distinct U balances on TWO chains** (same wallet address, same private
    key, different chains):
 

package/skills/references/bnbagent-studio-selling-via-8183.md

@@ -106,6 +106,26 @@ quote_ttl_seconds = 300
 default_estimated_completion_seconds = 600
 ```
 
+An explicit `price = "0"` opts into free jobs when the selected ERC-8183
+contract supports zero-price funding. Keep `currency` configured because it
+remains part of the signed quote.
+
+Prefer the CLI so the zero-price choice is visible and remains a decimal
+string:
+
+```bash
+bag config set payments.erc8183.price 0
+bag env set ERC8183_COMMERCE_ADDRESS <qa-commerce-proxy>
+bag env set ERC8183_ROUTER_ADDRESS <qa-router-proxy>
+bag env set ERC8183_POLICY_ADDRESS <qa-policy>
+bag doctor
+bag deploy prepare
+```
+
+Take all three addresses from the same apex-contracts `bscTestnetQa` entry.
+Doctor/prepare reject canonical or partial contract selection for FREE and
+announce `zero token escrow` only when the complete custom/QA stack is selected.
+
 ## Stage 3 — LLM credit continuity (Pieverse projects only)
 
 If `[llm].provider = "pieverse-llm"`, the Agent's emitted

package/skills/references/bnbagent-studio-selling-via-b402.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio-selling-via-b402
-description: When the user wants a bnbagent-studio agent to sell paid HTTP requests through the B402-backed x402 rail. Owns per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
+description: When the user wants a bnbagent-studio agent to sell paid or FREE HTTP requests through the B402-backed x402 rail. Owns the explicit pricing choice and, for PAID mode, per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
 ---
 
 > **Reference file** of the `bnbagent-studio` router skill — installed at
@@ -9,24 +9,46 @@ description: When the user wants a bnbagent-studio agent to sell paid HTTP reque
 
 # Sell via B402
 
-Use this playbook to activate the x402 seller rail for one agent. B402 merchant
-credentials are per agent and per environment. Never reuse a merchant record
-across agent wallets, or mix sandbox and production values.
+Use this playbook to activate the x402 seller rail for one agent. First choose
+PAID or FREE explicitly. B402 merchant credentials are per agent and per
+environment and are needed only for PAID. Never reuse a merchant record across
+agent wallets, or mix sandbox and production values.
 
 ## Preconditions
 
-- The agent wallet already exists. Its address will receive the U payments.
+- The agent wallet already exists. In PAID mode its address receives U.
 - The project targets the managed platform or self-hosted AgentCore
   (azure-foundry cannot activate the rail).
-- Managed platform only: a platform bearer token is available for reading the
+- PAID managed platform only: a platform bearer token is available for reading the
   platform egress IPs — the GitHub-login access token from
   `bag platform login`, or a `bnbk_…` API token minted once by
   `bag platform token`.
 - `[payments.x402_seller]` exists. If not, run
   `bag x402 sell init`.
 
-The application uses the **agent wallet address**, not a developer treasury,
-buyer wallet, or platform wallet.
+The PAID application uses the **agent wallet address**, not a developer
+treasury, buyer wallet, or platform wallet.
+
+## Choose PAID or FREE
+
+Use one of these explicit boundaries:
+
+```bash
+bag init <name> --rails b402 --b402-price 0
+bag x402 sell init --price-usd 0
+bag config set payments.x402_seller.price_usd 0
+```
+
+`"0"` means anonymous FREE passthrough. The runtime returns work directly and
+does not issue a 402 challenge, call B402 `/supported`/verify/settle, transfer
+U, or write an `x402_sell` settlement audit. B402 credentials are ignored and
+not synchronized. Run `bag x402 sell status`, `bag doctor`, and
+`bag deploy prepare`; all must label the route FREE.
+
+This is unrestricted public access. Confirm that intent before continuing.
+Managed platform still publishes the route through its gateway; self-hosted
+AgentCore still needs an envelope-v1 front; Azure Foundry remains unsupported.
+If FREE is the selected product, skip the merchant/RSA/IP sections below.
 
 ## Generate the agent's RSA material
 
@@ -146,7 +168,7 @@ exactly one private-key form; do not set both.
 
 ## Verify and activate
 
-Check names and presence without exposing values:
+For PAID mode, check names and presence without exposing values:
 
 ```bash
 bag x402 sell status --no-probe
@@ -163,7 +185,7 @@ For a sandbox/trial agent, it must find exact/eip3009 U on `eip155:97`. For
 production it must find the mainnet environment expected by the project. A
 network mismatch is not safe to ignore.
 
-Run the deployment gate, then redeploy to activate the paid route:
+Run the deployment gate, then redeploy to activate the selected mode:
 
 ```bash
 bag deploy prepare
@@ -171,11 +193,12 @@ bag deploy --provider bnb   # managed platform
 bag deploy --provider aws   # self-hosted AgentCore
 ```
 
-On the managed platform the deploy summary must say `x402 rail is ACTIVE` and
-print the anonymous `/x402` URL. On a self-hosted AgentCore deploy it says
-`x402 rail is ACTIVE (self-hosted AgentCore)`: the rail runs in-process, but
-there is no anonymous URL — operate your own HTTP front that relays
-envelope-v1 JSON over SigV4-signed `InvokeAgentRuntime` calls (see
+On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or
+`ACTIVE in FREE mode`) and print the anonymous `/x402` URL. On a self-hosted
+AgentCore deploy it says `x402 rail is ACTIVE (self-hosted AgentCore)` or
+`ACTIVE in FREE mode (self-hosted AgentCore)`: the rail runs in-process, but
+there is no anonymous URL — operate your own HTTP front that relays envelope-v1
+JSON over SigV4-signed `InvokeAgentRuntime` calls (see
 `docs/guides/x402-selling.md`, "Self-hosted AgentCore access"). A dormant or
 forced-dormant summary means the rail was not activated; fix the named
 credential, runtime, network, or tunnel condition and redeploy.
@@ -190,5 +213,6 @@ credential, runtime, network, or tunnel condition and redeploy.
   does not trigger an automatic refund.
 - The rail activates on AgentCore targets only (managed platform or
   self-hosted); azure-foundry stays forced dormant.
-- The payout wallet must be `wallet.kind` `evm-local` or `twak`; other kinds
-  (including Altana) are rejected at init, `sell init`, and readiness.
+- PAID payout wallets must use `wallet.kind` `evm-local` or `twak`; FREE has
+  no payout and does not apply this B402-specific allowlist.
+- Never describe FREE as a zero-value B402 settlement. It bypasses B402.

package/skills/references/bnbagent-studio-use-aws-agentcore.md

@@ -197,8 +197,9 @@ bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
 ## Reference
 
 - b402/x402 selling on self-hosted AgentCore: the rail activates in-process
-  when the B402 credentials are set, but there is no anonymous URL — operate
-  your own HTTP front that relays envelope-v1 over `InvokeAgentRuntime`. See
+  with complete B402 credentials for PAID, or without them when explicit zero
+  selects FREE. There is no anonymous URL — operate your own HTTP front that
+  relays envelope-v1 over `InvokeAgentRuntime`. See
   `bnbagent-studio-selling-via-b402` and `docs/guides/x402-selling.md`.
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
 - `agentcore/agentcore.json` — name (resource naming continuity), protocol, authorizer, envVars

package/skills/references/bnbagent-studio-using-altana-wallet.md

@@ -58,10 +58,11 @@ x402 buying remains separate and exact-bounded:
 bag wallet session x402-setup --allowance-u <U> --yes
 ```
 
-Altana cannot be the b402 **seller** payout wallet (the rail allows
-`evm-local` and `twak` only); init, `bag x402 sell init`, and deploy
-readiness reject the combination. Only the outbound buying authority above
-is available.
+Altana cannot be the b402 **seller** payout wallet for a positive price (paid
+mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and
+deploy readiness reject that paid combination. Explicit
+`price_usd = "0"` is allowed because FREE passthrough performs no payout and
+bypasses B402. The outbound buying authority above remains a separate feature.
 
 For troubleshooting, run `bag doctor` and `bag wallet session status`. Do not
 print, parse, or copy the `signer` portion of the serialized session, and never