@bnbagent/studio-cli 0.0.6-alpha.4 → 0.0.6-alpha.5

package/dist/{chunk-7RAKL4AS.js → chunk-RO726HJG.js}

@@ -115,12 +115,13 @@ function twakDoubledHomeHint(walletFile) {
   return `hint: the resolved wallet path ${walletFile} nests .twak/.twak \u2014 [wallet].twak_home in studio.toml likely points at the .twak directory itself. Set it to the PARENT directory (the runtime appends .twak/wallet.json) and re-run.`;
 }
 function twakCreateGuidance(fields) {
-  return `error: wallet.kind = "twak" \u2014 \`bag wallet new\` does not create twak wallets.
-studio never puts a wallet password on argv (upstream S-8), so it will not shell
-out \`twak wallet create --password \u2026\` for you. Create the wallet ONCE
-(you choose the password; pick a strong one).
+  return `error: wallet.kind = "twak" \u2014 \`bag wallet new\` only adopts an existing
+twak wallet's address. Create the wallet ONCE (you choose the password; pick a
+strong one).
 
-RECOMMENDED \u2014 let studio drive the create step with the password OFF argv:
+RECOMMENDED \u2014 let studio drive the create step so you never type the password
+on a command line (twak requires --password on its own argv, so the value does
+reach that short-lived child process):
 
     bag wallet twak-init --password-stdin      # CI: printf %s "$PW" | bag wallet twak-init --password-stdin
     bag wallet twak-init --password-file <f>   # file must be chmod 600
@@ -136,13 +137,15 @@ secret, then run \`twak setup\` (without them \`twak wallet create\` fails with
 
     ${fields.setupCmd}
 
-then create the wallet \u2014 interactive (password on twak's own argv; twak warns,
-and it lands in your shell history \u2014 acceptable for a throwaway hot wallet):
+then create the wallet \u2014 interactive (you type the password on argv yourself;
+twak warns, and it lands in your shell history \u2014 acceptable for a throwaway hot
+wallet):
 
     ${fields.createCmd}
 
-  \u2014 or, to keep the password OFF argv (CI / scripts), pass it via the
-    environment and let \`twak setup\` create the wallet non-interactively:
+  \u2014 or, to keep the password out of your shell history (CI / scripts), pass it
+    via the environment and let \`twak setup\` create the wallet
+    non-interactively:
 
     TWAK_NONINTERACTIVE=1 TWAK_SETUP_WALLET=create TWAK_WALLET_PASSWORD=<pw> ${fields.setupCmd}
 

package/dist/{chunk-A7NAGZHR.js → chunk-VEOOFDSF.js}

@@ -5,7 +5,7 @@ import {
   runCaptureOut,
   runStream,
   whichTwak
-} from "./chunk-7RAKL4AS.js";
+} from "./chunk-RO726HJG.js";
 
 // src/cli/_deploy/deployCli.ts
 import * as fs4 from "fs";
@@ -296,6 +296,8 @@ function mb(n) {
 // src/cli/_x402SellerConfig.ts
 var DEFAULT_B402_PRICE_USD = "0.01";
 var DEFAULT_B402_TESTNET_BASE_URL = "https://qacb.sdtaop.com";
+var B402_DEVELOPER_ACCOUNT_URL = "https://developers.binance.com/en/docs/products/onchainpay-x402/basics/6.apply-developer-account";
+var B402_PAID_ONBOARDING_GUIDANCE = `Create the agent wallet first, then apply for a separate B402 merchant for that exact wallet and environment; never reuse merchant credentials across wallets. Apply: ${B402_DEVELOPER_ACCOUNT_URL}`;
 var PRICE_USD_RE = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
 var ZERO_PRICE_USD_RE = /^0(?:\.0+)?$/;
 function x402SellerPricingState(seller) {
@@ -687,7 +689,7 @@ function x402DeploySummary(root, destination, publicUrl) {
   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.";
+  const activation = `${B402_PAID_ONBOARDING_GUIDANCE} Then run the bnbagent-studio-selling-via-b402 skill, fill the four B402_* variables in .studio/.env.local, and redeploy.`;
   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.`;
@@ -701,7 +703,9 @@ function x402DeploySummary(root, destination, publicUrl) {
         "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.'
+        'The front wraps each request as envelope-v1 JSON, {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"}, inside an authenticated AgentCore invocation. The default Bag self-deploy uses Cognito OAuth over HTTPS; IAM runtimes may use SDK/SigV4. Limits: 1 MiB request, 5 MiB response, no streaming.',
+        "You may invoke AgentCore with envelope-v1 directly, but that is not a standard public x402 HTTP endpoint.",
+        "Gateway example: https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md"
       ].join("\n");
     }
     const url2 = publicUrl ?? "<available after the platform agentId is assigned>";
@@ -715,16 +719,18 @@ function x402DeploySummary(root, destination, publicUrl) {
     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."
+    "B402 settlement can add significant latency; 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.",
+    "Compatibility note: current @bnb-chain/b402@0.1.0 makes one settle call and classifies an asynchronous pending response as outcome unknown; reconcile it and do not replay the paid request."
   ];
   if (destination !== "platform") {
     return [
       "x402 rail is ACTIVE (self-hosted AgentCore).",
       "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.',
-      "B402 allowlists merchant egress IPs and this deploy has no fixed egress IP: route facilitator egress through a fixed-IP forward proxy you control and submit that IP with the merchant application (see the bnbagent-studio-selling-via-b402 reference).",
-      'See docs/guides/x402-selling.md, section "Self-hosted AgentCore access".',
+      'The front wraps each request as envelope-v1 JSON, {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"}, inside an authenticated AgentCore invocation. The default Bag self-deploy uses Cognito OAuth over HTTPS; IAM runtimes may use SDK/SigV4. Limits: 1 MiB request, 5 MiB response, no streaming.',
+      "You may invoke AgentCore with envelope-v1 directly, but the caller must unpack the inner HTTP response and the result is not a standard public x402 endpoint.",
+      "PAID also needs fixed facilitator egress. Operate a restricted B402 Relay on a fixed-IP host such as a user-managed VPS, or use AgentCore VPC mode with a private subnet, NAT Gateway, and Elastic IP.",
+      "Gateway and Relay examples: https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md",
       ...settlement
     ].join("\n");
   }
@@ -732,6 +738,8 @@ function x402DeploySummary(root, destination, publicUrl) {
   return [
     "x402 rail is ACTIVE.",
     `Anonymous paid URL: ${url}`,
+    "The managed platform supplies the x402 HTTP Gateway and the fixed-egress B402 Relay; no user-managed gateway, proxy, or VPC is required.",
+    "Payment policy and RSA signing remain inside the AgentCore seller. The B402 Relay only forwards the signed request to its fixed facilitator upstream.",
     ...settlement
   ].join("\n");
 }
@@ -996,28 +1004,76 @@ async function ensureRunnable(environment = process.env) {
   }
   return true;
 }
+var MODULE_MISSING_MARKER = "Cannot find module";
+var BUNX_TREE_HINT = [
+  `error: ${DEPLOY_CLI_PACKAGE} could not load its own dependencies \u2014 its `,
+  "bunx install directory is incomplete. Remove it and retry:\n",
+  '  rm -rf "${TMPDIR:-/tmp}"/bunx-*-@bnbagent\n',
+  "If it persists, clear Bun's package cache (`bun pm cache rm`), or point ",
+  "BNBAGENT_DEPLOY_COMMAND at a local checkout."
+].join("");
+function bunxInstallDir(environment = process.env) {
+  if (deployCommand(environment)[0] !== "bunx") {
+    return null;
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  return uid === null ? null : path5.join(os.tmpdir(), `bunx-${uid}-${DEPLOY_CLI_PACKAGE}`);
+}
+async function bunxTreeIsIncomplete() {
+  const [bin, ...prefix] = deployCommand();
+  const probe = await runCapture(bin, [...prefix, "--help"], {
+    timeoutMs: 12e4
+  });
+  return probe.code !== 0 && `${probe.stderr}
+${probe.stdout}`.includes(MODULE_MISSING_MARKER);
+}
+async function withBunxSelfHeal(hasFailed, attempt) {
+  const first = await attempt();
+  if (!hasFailed(first)) {
+    return first;
+  }
+  const dir = bunxInstallDir();
+  if (dir === null || !await bunxTreeIsIncomplete()) {
+    return first;
+  }
+  if (!fs4.existsSync(dir)) {
+    printErr(BUNX_TREE_HINT);
+    return first;
+  }
+  printErr(
+    `note: ${DEPLOY_CLI_PACKAGE} failed to load its dependencies; clearing its incomplete bunx install and retrying once (${dir}).`
+  );
+  fs4.rmSync(dir, { recursive: true, force: true });
+  const second = await attempt();
+  if (hasFailed(second)) {
+    printErr(BUNX_TREE_HINT);
+  }
+  return second;
+}
 async function runDeployCliStream(argv, opts = {}) {
   if (!await ensureRunnable()) {
     return 127;
   }
   const [bin, ...prefix] = deployCommand();
-  return runStream(bin, [...prefix, ...argv], {
-    cwd: opts.cwd,
-    env: opts.env ? { ...process.env, ...opts.env } : void 0
-  });
+  return withBunxSelfHeal(
+    (code) => code !== 0,
+    () => runStream(bin, [...prefix, ...argv], {
+      cwd: opts.cwd,
+      env: opts.env ? { ...process.env, ...opts.env } : void 0
+    })
+  );
 }
 async function runDeployCliJson(argv, opts = {}) {
   if (!await ensureRunnable()) {
     return { code: 127, data: {} };
   }
   const [bin, ...prefix] = deployCommand();
-  const { code, stdout } = await runCaptureOut(
-    bin,
-    [...prefix, ...argv, "--json"],
-    {
+  const { code, stdout } = await withBunxSelfHeal(
+    (result) => result.code !== 0,
+    () => runCaptureOut(bin, [...prefix, ...argv, "--json"], {
       cwd: opts.cwd,
       env: opts.env ? { ...process.env, ...opts.env } : void 0
-    }
+    })
   );
   let data = {};
   const trimmed = stdout.trim();
@@ -1093,6 +1149,8 @@ export {
   recipeModeOf,
   DEFAULT_B402_PRICE_USD,
   DEFAULT_B402_TESTNET_BASE_URL,
+  B402_DEVELOPER_ACCOUNT_URL,
+  B402_PAID_ONBOARDING_GUIDANCE,
   x402SellerPricingState,
   normalizeB402PriceUsd,
   isB402TestnetBaseUrl,
@@ -1124,6 +1182,7 @@ export {
   buildDeploySpec,
   renderSecretEnvFile,
   withDeployFiles,
+  bunxInstallDir,
   runDeployCliStream,
   runDeployCliJson,
   trialFromDeployCliJson,

package/dist/{deployCli-264UE6KB.js → deployCli-EEK75T67.js}

@@ -8,6 +8,7 @@ import {
   bnbEnv,
   bnbPlatformApiUrl,
   buildDeploySpec,
+  bunxInstallDir,
   deployCommand,
   deployEndpointValue,
   providerPassthrough,
@@ -17,8 +18,8 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-A7NAGZHR.js";
-import "./chunk-7RAKL4AS.js";
+} from "./chunk-VEOOFDSF.js";
+import "./chunk-RO726HJG.js";
 export {
   BNB_PLATFORM_API_URL,
   BNB_PLATFORM_API_URL_ENV,
@@ -28,6 +29,7 @@ export {
   bnbEnv,
   bnbPlatformApiUrl,
   buildDeploySpec,
+  bunxInstallDir,
   deployCommand,
   deployEndpointValue,
   providerPassthrough,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.6-alpha.4",
+  "version": "0.0.6-alpha.5",
   "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": {
@@ -19,6 +19,7 @@
     "dist",
     "skills",
     "recipes",
+    "README.md",
     "DISCLAIMER.md"
   ],
   "bin": {
@@ -37,7 +38,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.6-alpha.4"
+    "@bnbagent/studio-runtime": "0.0.6-alpha.5"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

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

@@ -59,14 +59,22 @@ flow now auto-adds dispute_window).
 - 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
+  gas-sponsored via the SDK's MegaFuel paymaster **when they target the
+  canonical contracts**, 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.) 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.
+  it. (Mainnet is never sponsored.) Sponsorship is granted per target contract
+  by the paymaster policy: a custom/QA stack selected via the
+  `ERC8183_*_ADDRESS` overrides is normally **not** covered, so every write
+  self-pays gas (the SDK logs `… is not sponsorable on this network;
+  self-paying gas` and falls back automatically) — keep tBNB for the whole
+  flow, or set `BNBAGENT_USE_PAYMASTER=0` to skip the per-transaction
+  sponsorship probe and self-pay directly. 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 — today that means a custom stack, so expect the
+  writes to self-pay gas as above.
 - 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

package/skills/references/bnbagent-studio-extending-signing.md

@@ -222,6 +222,9 @@ When deeper protocol details are needed:
 
 - Never bypass the policy with `_DANGEROUS_*` calls in agent code. They exist for tests and incident response.
 - Never instruct the user to widen caps / allowlists "to make it work" without explaining the security tradeoff.
-- Never persist the wallet password or signed payloads anywhere outside the keystore.
+- Persist the wallet password only in the generated, gitignored, owner-only
+  `.studio/.env.local` for local use or a managed secret channel for deploys;
+  never put it in argv, application code, logs, or chat.
+- Never persist signed payloads outside the keystore.
 - Always run `bag wallet policy show` after editing `[wallet.signing]` to confirm the change took effect.
 - Always restart the process — SigningPolicy is captured at wallet construction.

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

@@ -64,7 +64,8 @@ For seller job-lifecycle decisions (settle / submit / dispute defense), read
 ```bash
 # Configure secrets (idempotent — does NOT duplicate existing keys).
 # These write into .studio/.env.local (the Agent's secrets):
-bag env set WALLET_PASSWORD <your password>
+# Edit .studio/.env.local and set WALLET_PASSWORD there; bag auto-loads it.
+# Never put the wallet password on a command line.
 bag env set OPENROUTER_API_KEY <your key>   # or whichever provider app/agent/studio.toml [llm] uses
 
 # From the workspace root — `bag dev` serves the selected protocol:
@@ -129,7 +130,7 @@ Returns a rich table of checks across the `app/agent/` sub-project:
 | app/agent/studio.toml parseable | Missing or syntax error | `bag init` to regenerate, or hand-fix TOML |
 | Agent entrypoint imports | Protocol entrypoint raises on load (`src/main.ts` for A2A, `src/mcpMain.ts` for MCP) | Fix the error printed by the check (often a missing env var or a broken import) |
 | wallet keystore | No `<workspace>/.studio/wallets/*.json` | `bag wallet new` (writes to the workspace root keystore dir) |
-| WALLET_PASSWORD env | Not in `.studio/.env.local` / not exported | `bag env set WALLET_PASSWORD ...` (targets .studio/.env.local) |
+| WALLET_PASSWORD env | Not in `.studio/.env.local` / not exported | Edit the owner-only `.studio/.env.local`; never pass the password on argv |
 | LLM provider key | API key env not set | Edit `.studio/.env.local` or export the right `*_API_KEY` |
 | Network reachable | RPC down/wrong URL | Override via `STUDIO_BSC_TESTNET_RPC=...` (testnet) / `STUDIO_BSC_RPC=...` (mainnet) — per-network env vars read by `@bnbagent/studio-runtime/networks` `getNetwork` |
 | Wallet tBNB balance | 0 tBNB | Faucet: testnet.bnbchain.org/faucet-smart |

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

@@ -309,10 +309,10 @@ Step 6b when `storage=ipfs`):
    - **twak** (fully supported — opt in with `--wallet-kind twak`): `bag init` writes `[wallet].twak_home =
      "../../.studio/twak"` — a **project-dedicated** wallet isolated from your
      main `~/.twak`, so a deploy never pushes the main wallet's key material to
-     Secrets Manager. The user creates it ONCE themselves — the twak CLI forces
-     the password onto argv (upstream S-8), so studio never runs it — in their
-     own terminal:
-     own terminal — the 3-step `twak setup` wizard:
+     Secrets Manager. Setting it up is a ONE-TIME job: the user runs the
+     interactive 3-step `twak setup` wizard themselves in their own terminal,
+     then `bag wallet twak-init` creates the wallet (so the password never goes
+     into a command line). Start with the wizard:
      ```bash
      HOME=<workspace>/.studio/twak twak setup
      ```
@@ -332,17 +332,21 @@ Step 6b when `storage=ipfs`):
        WalletConnect` = your main wallet.)
 
      ```bash
-     HOME=<workspace>/.studio/twak twak wallet create --password <StrongPw> --no-keychain  # UPPER + lower + digit
+     cd app/agent && bag wallet twak-init                       # hidden prompt
+     printf %s "$PW" | bag wallet twak-init --password-stdin     # CI / scripts
      ```
      Use UPPER + lower + digit; put that same password in `.studio/.env.local`
-     as `TWAK_WALLET_PASSWORD`. `--no-keychain` keeps the password out of the OS
-     keychain (no macOS prompt); studio unlocks via the env. (If you omit it and a
-     macOS prompt *loops*, do NOT "Reset Default Keychain" — `pkill -9 -f twak`,
-     then re-run with `--no-keychain`.) Full detail: the
+     as `TWAK_WALLET_PASSWORD`. `twak-init` passes `--no-keychain`, which keeps
+     the password out of the OS keychain (no macOS prompt); studio unlocks via
+     the env. (If a macOS prompt *loops* on a manual `twak` run, do NOT "Reset
+     Default Keychain" — `pkill -9 -f twak`, then re-run with `--no-keychain`.)
+     It also adopts the address into `studio.toml` and echoes it — confirm it's
+     the intended wallet before funding/deploy, and there is no separate
+     `bag wallet new` step. The manual equivalent is
+     `HOME=<workspace>/.studio/twak twak wallet create --password <StrongPw> --no-keychain`
+     followed by `bag wallet new`. Full detail: the
      `bnbagent-studio-using-twak-wallet.md` reference (in the router skill's `references/` directory).
-     Then YOU run `bag wallet new`, which **adopts** the address into
-     `studio.toml` (and echoes it — confirm it's the intended wallet before
-     funding/deploy). To reuse an EXISTING wallet across agents, scaffold with
+     To reuse an EXISTING wallet across agents, scaffold with
      `bag init --twak-home <path-to-its-home>` instead. Reusing your main
      `~/.twak` is opt-in only (`--twak-home ~`) and discouraged. Full detail:
      the `bnbagent-studio-using-twak-wallet.md` reference (in the router skill's `references/` directory).

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

@@ -3,7 +3,7 @@ name: bnbagent-studio-selling-via-b402
 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
+> **Reference file** of the `bnbagent-studio` router skill, installed at
 > `bnbagent-studio/references/` and loaded on demand (not a standalone skill).
 > Route here via the router's decision tree.
 
@@ -19,10 +19,9 @@ agent wallets, or mix sandbox and production values.
 - 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).
-- 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`.
+- PAID managed platform only: an interactive GitHub-login session from
+  `bag platform login` is available for reading the platform Relay egress
+  IPs. A `bnbk_…` CI token does not satisfy this endpoint's GitHub-user check.
 - `[payments.x402_seller]` exists. If not, run
   `bag x402 sell init`.
 
@@ -59,66 +58,86 @@ call under the
 the runtime signs each request automatically once the credentials are stored.
 
 Work from the workspace root. Keep private material under `.studio/`, which is
-excluded from source and deploy artifacts:
+excluded from source and deploy artifacts. Generate a separate key pair for
+each environment:
 
 ```bash
 umask 077
-mkdir -p .studio/b402
-openssl genrsa -out .studio/b402/private.pem 2048
-openssl pkey -in .studio/b402/private.pem -pubout \
-  -out .studio/b402/public.pem
-openssl pkey -in .studio/b402/private.pem -pubout -outform DER |
-  openssl base64 -A > .studio/b402/public.der.b64
-openssl pkcs8 -topk8 -nocrypt -in .studio/b402/private.pem -outform DER |
-  openssl base64 -A > .studio/b402/private.der.b64
-chmod 600 .studio/b402/private.pem .studio/b402/private.der.b64
+b402_env=sandbox
+mkdir -p ".studio/b402/$b402_env"
+openssl genpkey -algorithm RSA \
+  -out ".studio/b402/$b402_env/private.pem" \
+  -pkeyopt rsa_keygen_bits:1024
+openssl pkey -in ".studio/b402/$b402_env/private.pem" -pubout \
+  -out ".studio/b402/$b402_env/public.pem"
+openssl pkey -in ".studio/b402/$b402_env/private.pem" -pubout -outform DER |
+  openssl base64 -A > ".studio/b402/$b402_env/public.der.b64"
+openssl pkcs8 -topk8 -nocrypt \
+  -in ".studio/b402/$b402_env/private.pem" -outform DER |
+  openssl base64 -A > ".studio/b402/$b402_env/private.der.b64"
+chmod 600 ".studio/b402/$b402_env/private.pem" \
+  ".studio/b402/$b402_env/private.der.b64"
 ```
 
 Do not print the private key or its base64 form. Submit only the public key
 material to B402.
 
-Studio generates a 2048-bit RSA key. The current B402 application form text
-mentions 1024 bits, while 2048-bit acceptance still requires confirmation from
-the B402 operator. Confirm that field with the operator; do not silently
-downgrade the key.
+The current B402 request-signing contract explicitly requires a 1024-bit RSA
+key and RSA-SHA256. Follow that protocol requirement even if a larger RSA key
+would normally be preferred elsewhere. Repeat with `b402_env=production`
+instead of reusing the sandbox pair.
 
 ## Collect the IP allowlist
 
-B402 allowlists the merchant's **outbound** (egress) IPs — the addresses the
+B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the
 agent's facilitator calls come FROM. Submit every part that applies to your
 deployment target:
 
-1. **Platform egress IPs (managed-platform deploys)** — the addresses
-   deployed-agent requests reach B402 from. Authenticated read (bearer from
-   the Preconditions):
+1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses
+   that the platform B402 Relay uses to reach the facilitator. The managed
+   deployment worker points only the AgentCore runtime copy of
+   `B402_BASE_URL` at this Relay. Refresh and read the interactive session
+   without printing its bearer:
 
    ```bash
-   curl -H "Authorization: Bearer $BNBAGENT_API_TOKEN" \
-     "https://bnbagent-api.bnbchain.world/v1/b402/whitelist-ips"
+   bag platform whoami >/dev/null
+   platform_session="$HOME/.bnbagent-deploy/bnb/session.json"
+   platform_access_token="$(jq -er '.access_token' "$platform_session")"
+   platform_api_url="$(jq -er '.apiUrl' "$platform_session")"
+   curl -H "Authorization: Bearer $platform_access_token" \
+     "$platform_api_url/v1/b402/whitelist-ips"
+   unset platform_access_token
    # → {"whitelist_ips": ["13.115.15.190", …], "cache_ttl_seconds": 300}
    ```
 
    Submit every address in `whitelist_ips`. The list is served with a short
-   cache TTL and can rotate — re-read it right before submitting the form.
-   Set `BAG_PLATFORM_API_BASE` to target a non-production platform
-   environment.
+   cache TTL and can rotate, so re-read it right before submitting the form.
+   The login session is stored mode `0600`. Do not echo, log, or paste its
+   access or refresh token. `bnbk_` tokens from `bag platform token` are
+   deliberately rejected by this GitHub-login-only endpoint.
 
-2. **Your local public IP** — required so a local `bag dev` run can reach
+2. **Your local public IP**: required so a local `bag dev` run can reach
    B402:
 
    ```bash
    curl ipinfo.io/ip
    ```
 
-3. **Self-hosted AgentCore egress (self-deploys)** — AgentCore gives the
-   container no fixed egress IP, so there is no address to submit directly.
-   Route the facilitator egress through a fixed-IP forward proxy you control
-   and submit THAT IP: set `HTTPS_PROXY` on the runtime and enable proxy
-   support for Node's fetch, which ignores proxy env vars by default —
-   install an undici `EnvHttpProxyAgent` global dispatcher in the agent
-   entrypoint, or run the container on Node 24+ with `--use-env-proxy`.
-   Without this, every verify/settle call is rejected as an unallowlisted
-   IP even though the deploy summary reports the rail ACTIVE.
+3. **Self-hosted AgentCore egress (self-deploys)**: operate a restricted B402
+   Relay on a host with a fixed public egress IP, such as a user-managed VPS,
+   and submit that IP. Set the runtime `B402_BASE_URL` to the Relay base URL.
+   The Relay exposes only
+   `supported`, `verify`, and `settle`, fixes the upstream facilitator, and
+   forwards the signed body and Tesla header allowlist without holding the
+   merchant private key or automatically retrying a settlement transport
+   failure. See the
+   [self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md)
+   for a TypeScript example.
+
+   As an alternative, use AWS-supported AgentCore VPC mode with a private subnet, NAT
+   Gateway, and Elastic IP. Submit the Elastic IP and keep
+   `B402_BASE_URL` pointed at the facilitator. Studio does not deploy or
+   manage that AWS network.
 
 Do not add the public inbound gateway IP, a transient build-runner IP, or
 guessed addresses. If the whitelist endpoint is unreachable, stop onboarding
@@ -134,10 +153,11 @@ production. Fill the form as follows:
 | Field | Value |
 |---|---|
 | Business Name | Your agent or business display name |
-| Website | Your project or service URL |
-| Wallet | The agent wallet address |
-| RSA Public Key | The contents of `.studio/b402/public.der.b64` in the format the operator confirms |
-| IP allowlist | Every platform egress IP from `/v1/b402/whitelist-ips` plus your local public IP (see "Collect the IP allowlist") |
+| Email | Primary contact email address |
+| Wallet address | The agent wallet for that environment |
+| Public key | The contents of `.studio/b402/<environment>/public.der.b64` |
+| IP allowlist | For managed deploys, every platform Relay IP from `/v1/b402/whitelist-ips`; for self-hosted deploys, the user's Relay or NAT Elastic IP; add the local public IP when `bag dev` must reach B402 directly |
+| Webhook callback URL | Supply only when the integration uses callbacks |
 
 Keep the two environments isolated:
 
@@ -152,20 +172,28 @@ Open the workspace `.studio/.env.local` in an editor and fill exactly four
 values:
 
 ```dotenv
-B402_BASE_URL=https://qacb.sdtaop.com
+B402_BASE_URL=
 B402_CLIENT_ID=
 B402_ACCESS_TOKEN=
 B402_PRIVATE_KEY_B64=
 ```
 
 Copy the single-line DER value from
-`.studio/b402/private.der.b64` into `B402_PRIVATE_KEY_B64`. Do not include the
-value in shell history, terminal output, source files, TOML, screenshots, or
-support tickets.
+`.studio/b402/<environment>/private.der.b64` into `B402_PRIVATE_KEY_B64`.
+`B402_BASE_URL`, `B402_CLIENT_ID`, and `B402_ACCESS_TOKEN` are the values
+issued together for that environment. Do not include any value in shell
+history, terminal output, source files, TOML, screenshots, or support tickets.
 
 `B402_PRIVATE_KEY` accepts the PEM representation as an alternative. Keep
 exactly one private-key form; do not set both.
 
+For the current managed BSC Testnet path, the platform-supported upstream is
+`https://qacb.sdtaop.com`; the worker projects only the AgentCore runtime copy
+to its Relay. For a generic self-hosted environment, use the authenticated
+base URL issued during onboarding. With your own Relay, set the runtime
+`B402_BASE_URL` to that Relay base URL and configure the Relay's fixed upstream
+to the issued URL.
+
 ## Verify and activate
 
 For PAID mode, check names and presence without exposing values:
@@ -197,22 +225,34 @@ 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.
+there is no anonymous URL. Operate your own HTTP front that relays envelope-v1
+JSON through an authenticated AgentCore invocation. The default Bag
+self-deploy uses Cognito OAuth over raw HTTPS; AWS SDK/SigV4 is only for a
+runtime deliberately configured with IAM authorization. PAID also needs your
+own fixed-egress B402 Relay or equivalent network path. The complete gateway
+wrapper, response parser, Relay example, and direct-invocation fallback are in
+the
+[self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md).
+A dormant or forced-dormant summary means the rail was not activated; fix the
+named credential, runtime, network, or tunnel condition and redeploy.
 
 ## Hard rules
 
 - Never log or print any B402 value or private key.
 - Never put a B402 value in `studio.toml` or a deploy descriptor.
-- Never retry a settlement whose outcome is unknown. Follow
+- Never replay a paid HTTP request whose outcome is unknown. Follow
   `docs/guides/x402-selling.md` and reconcile `(nonce, network, payer)` first.
+- Binance `/settle` is asynchronous. A parseable `success: false` response
+  with a transaction is pending and requires an idempotent poll with the same
+  settlement payload. Studio v0.0.6 and the latest
+  `@bnb-chain/b402@0.1.0` do not yet perform that poll; they classify pending
+  as unknown. Do not claim current mainnet readiness until this is updated.
 - Settlement happens before work. A later work failure retains the payment and
   does not trigger an automatic refund.
 - The rail activates on AgentCore targets only (managed platform or
   self-hosted); azure-foundry stays forced dormant.
-- PAID payout wallets must use `wallet.kind` `evm-local` or `twak`; FREE has
-  no payout and does not apply this B402-specific allowlist.
+- PAID B402 payout wallets must use `wallet.kind` `evm-local` (private-key
+  wallet stored as an encrypted keystore) or `twak`. Altana is unsupported.
+  FREE x402 bypasses B402, has no payout, and must not be described as Altana
+  B402 support.
 - Never describe FREE as a zero-value B402 settlement. It bypasses B402.

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

@@ -199,8 +199,11 @@ bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
 - b402/x402 selling on self-hosted AgentCore: the rail activates in-process
   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`.
+  relays envelope-v1 through the runtime's configured authorizer. The default
+  Bag deploy uses Cognito OAuth over HTTPS, not SDK/SigV4. PAID also needs a
+  fixed-egress B402 Relay or VPC/NAT/Elastic-IP path. See
+  `bnbagent-studio-selling-via-b402` and
+  `docs/guides/self-hosted-x402-gateway.md`.
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
 - `agentcore/agentcore.json` — name (resource naming continuity), protocol, authorizer, envVars
 - `agentcore/aws-targets.json` — AWS account + region