@bnbagent/studio-cli 0.0.6-alpha.7 → 0.0.6-alpha.8

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

@@ -3,189 +3,99 @@ name: bnbagent-studio-adding-to-project
 description: When the user wants to add bnbagent-studio's single ERC-8183 seller runtime (one valuable Agent on AWS Bedrock AgentCore that serves A2A by default or MCP optionally, holds the key, and signs in-process) to an existing TypeScript agent project.
 ---
 
-> **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.
+> **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.
 
 # bnbagent-studio-adding-to-project
 
-Procedure for adding `bnbagent-studio`'s **single selected-protocol seller** to an
-**existing** TypeScript/Node repo. Audience: Claude Code (or another agent)
-running with shell + edit access in the user's repo.
+Procedure for adding `bnbagent-studio`'s **single selected-protocol seller** to an **existing** TypeScript/Node repo. Audience: Claude Code (or another agent) running with shell + edit access in the user's repo.
 
 ## The single seller runtime model (v1 workspace)
 
-studio turns the user's existing valuable agent into a paid blockchain seller as
-a **thin workspace root with one sub-project** under it:
-
-- **Agent (`app/agent/` sub-project, → AWS Bedrock AgentCore).** The user's
-  agent value (LLM / memory / tools / KB) AND the **sole key-holder/signer**.
-  AgentCore runs the container with the selected protocol (A2A:
-  `0.0.0.0:9000`; MCP: `0.0.0.0:8000/mcp`), so the Agent **serves directly** —
-  it is its own public HTTPS surface, gated by a mandatory Cognito OAuth2
-  authorizer. Owns its own `app/agent/package.json`, `app/agent/studio.toml`,
-  and `.studio/.env.local`; the keystore lives at the WORKSPACE root
-  `.studio/wallets/` (outside the AgentCore codeLocation, so no deploy packaging
-  path can bundle it — at deploy it is injected via AWS Secrets Manager as
-  `WALLET_KEYSTORE_JSON`). The outward surface is A2A's `SellerAgentExecutor`
-  (`negotiate` / `notify_funded` skills) or the MCP server's tools with the same
-  bounded operations; ALL signing is fixed `app/agent/src/signing.ts` code,
-  never an LLM tool.
-
-There is **no** second service: the Agent signs in-process and answers buyers
-directly over its selected protocol. (The earlier two-layer split — an
-invoke-only Agent plus a public keyless EC2 service relaying to it — was removed
-once AgentCore could serve the protocol surface on a public endpoint; see
-`docs/design/single-seller-agent.md` for the A2A decision history.)
-
-"Adding to an existing project" in v1 means **scaffolding a fresh workspace and
-migrating your value into it** — `bag init` always creates a *new* workspace
-directory (there is no in-place adoption); you then move your existing agent's
-LLM / tools / memory code into the generated `app/agent/` sub-project.
+studio turns the user's existing valuable agent into a paid blockchain seller as a **thin workspace root with one sub-project** under it:
+
+- **Agent (`app/agent/` sub-project, → AWS Bedrock AgentCore).** The user's agent value (LLM / memory / tools / KB) AND the **sole key-holder/signer**. AgentCore runs the container with the selected protocol (A2A: `0.0.0.0:9000`; MCP: `0.0.0.0:8000/mcp`), so the Agent **serves directly** - it is its own public HTTPS surface, gated by a mandatory Cognito OAuth2 authorizer. Owns its own `app/agent/package.json`, `app/agent/studio.toml`, and `.studio/.env.local`; the keystore lives at the WORKSPACE root `.studio/wallets/` (outside the AgentCore codeLocation, so no deploy packaging path can bundle it - at deploy it is injected via AWS Secrets Manager as `WALLET_KEYSTORE_JSON`). The outward surface is A2A's `SellerAgentExecutor` (`negotiate` / `notify_funded` skills) or the MCP server's tools with the same bounded operations; ALL signing is fixed `app/agent/src/signing.ts` code, never an LLM tool.
+
+There is **no** second service: the Agent signs in-process and answers buyers directly over its selected protocol. (The earlier two-layer split - an invoke-only Agent plus a public keyless EC2 service relaying to it - was removed once AgentCore could serve the protocol surface on a public endpoint; see `docs/design/single-seller-agent.md` for the A2A decision history.)
+
+"Adding to an existing project" in v1 means **scaffolding a fresh workspace and migrating your value into it** - `bag init` always creates a _new_ workspace directory (there is no in-place adoption); you then move your existing agent's LLM / tools / memory code into the generated `app/agent/` sub-project.
 
 v1 is **seller-only**; chat / buyer roles are deferred to v2.
 
 ## Preconditions
 
 - The repo is a TypeScript/Node project (has a `package.json`).
-- The user has Node.js ≥22 and can install the CLI — `npm install -g @bnbagent/studio-cli` (auto-pulls the `@bnbagent/studio-runtime` lib); for local dev use a monorepo clone (`pnpm install` at the workspace root).
+- The user has Node.js ≥22 and can install the CLI - `npm install -g @bnbagent/studio-cli` (auto-pulls the `@bnbagent/studio-runtime` lib); for local dev use a monorepo clone (`pnpm install` at the workspace root).
 - Network access to BSC testnet RPC (default: `https://data-seed-prebsc-1-s1.binance.org:8545`).
 
-## Step 1 — Bootstrap studio config
+## Step 1 - Bootstrap studio config
 
-Check for the v1 workspace layout — `app/agent/studio.toml` (not a root-level
-`studio.toml`):
+Check for the v1 workspace layout - `app/agent/studio.toml` (not a root-level `studio.toml`):
 
 ```bash
 ls app/agent/studio.toml 2>/dev/null || echo MISSING
 ```
 
-If missing, scaffold a new workspace. `bag init <name>` **always creates a new
-directory `<name>/` under the current working directory** — it does not adopt the
-current repo in place. Pick a workspace name, then migrate your existing agent's
-value into the generated `app/agent/` sub-project (Step 4):
+If missing, scaffold a new workspace. `bag init <name>` **always creates a new directory `<name>/` under the current working directory** - it does not adopt the current repo in place. Pick a workspace name, then migrate your existing agent's value into the generated `app/agent/` sub-project (Step 4):
 
 ```bash
-bag init my-agent && cd my-agent   # creates ./my-agent/ with the single app/agent/ sub-project
+bag init myagent && cd myagent   # creates ./myagent/ with the single app/agent/ sub-project
 ```
 
-**Scaffold note:** while the trial campaign runs, bare `bag init` defaults to
-`--destination platform` (the 48h managed-platform testnet trial — no AWS
-account needed). Pass `--destination self` to make AWS the scaffold intent.
-Both AgentCore variants include a Studio-rendered local deploy descriptor so a
-later explicit AWS deployment does not require re-scaffolding. Deploy provider
-selection remains explicit in Step 5.
+**Scaffold note:** while the trial campaign runs, bare `bag init` defaults to `--destination platform` (the 48h managed-platform testnet trial - no AWS account needed). Pass `--destination self` to make AWS the scaffold intent. Both AgentCore variants include a Studio-rendered local deploy descriptor so a later explicit AWS deployment does not require re-scaffolding. Deploy provider selection remains explicit in Step 5.
 
-Verify the workspace tree: `app/agent/studio.toml`, `.studio/.env.local`,
-`.studio/wallets/` at the root, and `.gitignore` at root + sub-project. A
-runtime=`agentcore` scaffolds (including platform-destined ones) also have
-`agentcore/agentcore.json` + `agentcore/aws-targets.json`. The managed BNB
-platform does not consume those local AWS files; they exist only to permit a
-later explicit `bag deploy --provider aws` choice.
+Verify the workspace tree: `app/agent/studio.toml`, `.studio/.env.local`, `.studio/wallets/` at the root, and `.gitignore` at root + sub-project. A runtime=`agentcore` scaffolds (including platform-destined ones) also have `agentcore/agentcore.json` + `agentcore/aws-targets.json`. The managed BNB platform does not consume those local AWS files; they exist only to permit a later explicit `bag deploy --provider aws` choice.
 
-## Step 2 — Detect framework (best-effort)
+## Step 2 - Detect framework (best-effort)
 
 ```bash
 bag scan
 ```
 
-**v1 note**: `scan` is a stub — it just reports detected files. Don't rely on
-its decisions; ask the user what their existing agent is built with (AI SDK /
-LangChain.js / a custom express service) before emitting recipes.
+**v1 note**: `scan` is a stub - it just reports detected files. Don't rely on its decisions; ask the user what their existing agent is built with (AI SDK / LangChain.js / a custom express service) before emitting recipes.
 
-## Step 3 — Emit the agent
+## Step 3 - Emit the agent
 
-A seller is the single Agent serving the selected protocol. `bag init` already
-composes it from recipes — `agent` (the fixed-code `src/signing.ts`) and
-`runtimes/agentcore` (A2A: `src/main.ts` (the express + A2A entrypoint) +
-`src/sellerCore.ts` (the protocol-neutral core; executor inherits it) +
-`src/executor.ts` + `src/agentCard.ts`; MCP: `src/mcpMain.ts`; shared
-`src/tools.ts` + `src/model.ts` + `Dockerfile`).
-Use `bag recipe code` to inspect or re-emit a piece:
+A seller is the single Agent serving the selected protocol. `bag init` already composes it from recipes - `agent` (the fixed-code `src/signing.ts`) and `runtimes/agentcore` (A2A: `src/main.ts` (the express + A2A entrypoint) + `src/sellerCore.ts` (the protocol-neutral core; executor inherits it) + `src/executor.ts` + `src/agentCard.ts`; MCP: `src/mcpMain.ts`; shared `src/tools.ts` + `src/model.ts`; a `Dockerfile` is added only for a container deployment path such as TWAK). Use `bag recipe code` to inspect or re-emit a piece:
 
 ```bash
 bag recipe code agent              > /dev/null   # inspect; bag init writes app/agent/src/signing.ts for you
 bag recipe code runtimes/agentcore > /dev/null   # inspect; bag init writes the A2A serving files for you
 ```
 
-In practice `bag init` already scaffolds `app/agent/`. Use `bag recipe code agent`
-/ `bag recipe code runtimes/agentcore` to inspect or re-emit (emits under
-`{{PKG}}` = the agent's `src/` dir, or pass `--pkg <name>` explicitly).
-
-Gotcha: token is **U** (USD-pegged stablecoin on BSC), not BNB. All ERC-8183
-amounts are denominated in U.
-
-## Step 4 — Wire your existing agent's value into the Agent
-
-The Agent sub-project (`app/agent/`) is where your existing valuable agent
-lives. Move your LLM construction / tools / memory / KB wiring into it, and
-implement the `runWork` developer hook (in `app/agent/src/sellerCore.ts` for
-A2A, `app/agent/src/mcpMain.ts` for MCP; called from `notify_funded`'s
-delivery) to produce the deliverable. Read-only chain tools go in
-`app/agent/src/tools.ts` (see `bnbagent-studio-wiring-llm-tools`). ALL signing
-stays in `app/agent/src/signing.ts` — never expose a signing call as an LLM
-tool.
-
-Tune the price in `app/agent/studio.toml` (`[payments.erc8183]` `min_price`/
-`max_price`): the `negotiate` path is **rule-based, no LLM** — fixed code takes
-the configured list price, clamps it to `[min_price, max_price]`, then
-`signing.ts` EIP-191-signs the offer. For per-task pricing, compute the price
-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
-`app/agent/src/model.ts` returns an AI SDK model wrapped with credit-ensure
-middleware. Its **automatic, budget-gated auto-renew hook** (the stack-neutral
-logic lives in `@bnbagent/studio-runtime/pieverse` `PieverseCreditEnsurer`;
-the AI-SDK shell is the emitted file) tops up the active Pieverse key from the
-wallet (when
-`[budget].enabled = true`) before an LLM call whose cached balance is below
-`[llm.auto_renew].min_balance_usd`. The Agent keeps delivering jobs even if it
-runs low mid-shift — the resilience is transparent.
-
-Crucially this is **not** an LLM tool. It rides on the hardened x402 buyer
-kernel (`@bnbagent/studio-runtime/x402`, the payment signer) — but the Agent
-(the sole key-holder) drives it transparently inside the model wrapper; the LLM
-never decides to spend. The LLM-credit self-top-up you get for free is the
-managed-model auto-renew hook described above.
-
-If the budget gate is off / exhausted, the hook raises
-`PieverseAccountBalanceExhaustedError` — let it surface so the buyer can dispute;
-refill with `bag llm topup` or enable the budget with `bag budget enable`.
-
-## Step 5 — Deploy the agent
-
-`bag deploy` always asks the operator to choose BNB or AWS; it never
-silently reuses `[deploy].destination` or the last provider.
-
-**Platform scaffold** (the bare-init default while the campaign runs) — one
-command; first run does a GitHub device-flow login, the wallet key goes to the
-operator's Secrets Manager (testnet-forced, use a throwaway wallet):
+In practice `bag init` already scaffolds `app/agent/`. Use `bag recipe code agent` / `bag recipe code runtimes/agentcore` to inspect or re-emit (emits under `{{PKG}}` = the agent's `src/` dir, or pass `--pkg <name>` explicitly).
+
+Gotcha: token is **U** (USD-pegged stablecoin on BSC), not BNB. All ERC-8183 amounts are denominated in U.
+
+## Step 4 - Wire your existing agent's value into the Agent
+
+The Agent sub-project (`app/agent/`) is where your existing valuable agent lives. Move your LLM construction / tools / memory / KB wiring into it, and implement the `runWork` developer hook (in `app/agent/src/sellerCore.ts` for A2A, `app/agent/src/mcpMain.ts` for MCP; called from `notify_funded`'s delivery) to produce the deliverable. Read-only chain tools go in `app/agent/src/tools.ts` (see `bnbagent-studio-wiring-llm-tools`). ALL signing stays in `app/agent/src/signing.ts` - never expose a signing call as an LLM tool.
+
+Tune the price in `app/agent/studio.toml` (`[payments.erc8183]` `min_price`/ `max_price`): the `negotiate` path is **rule-based, no LLM** - fixed code takes the configured list price, clamps it to `[min_price, max_price]`, then `signing.ts` EIP-191-signs the offer. For per-task pricing, compute the price 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 `app/agent/src/model.ts` returns an AI SDK model wrapped with credit-ensure middleware. Its **automatic, budget-gated auto-renew hook** (the stack-neutral logic lives in `@bnbagent/studio-runtime/pieverse` `PieverseCreditEnsurer`; the AI-SDK shell is the emitted file) tops up the active Pieverse key from the wallet (when `[budget].enabled = true`) before an LLM call whose cached balance is below `[llm.auto_renew].min_balance_usd`. The Agent keeps delivering jobs even if it runs low mid-shift - the resilience is transparent.
+
+Crucially this is **not** an LLM tool. It rides on the hardened x402 buyer kernel (`@bnbagent/studio-runtime/x402`, the payment signer) - but the Agent (the sole key-holder) drives it transparently inside the model wrapper; the LLM never decides to spend. The LLM-credit self-top-up you get for free is the managed-model auto-renew hook described above.
+
+If the budget gate is off / exhausted, the hook raises `PieverseAccountBalanceExhaustedError` - let it surface so the buyer can dispute; refill with `bag llm topup` or enable the budget with `bag budget enable`.
+
+## Step 5 - Deploy the agent
+
+`bag deploy` always asks the operator to choose BNB or AWS; it never silently reuses `[deploy].destination` or the last provider.
+
+**Platform scaffold** (the bare-init default while the campaign runs) - one command; first run does a GitHub device-flow login, the wallet key goes to the operator's Secrets Manager (testnet-forced, use a throwaway wallet):
 
 ```bash
 bag platform login                 # prints GitHub device URL + code; does not open a browser
 bag deploy --provider bnb          # ship to the managed platform (48h testnet trial)
 ```
 
-**Self-deploy scaffold** (`--destination self`) — the Agent serves the selected
-protocol directly behind a mandatory Cognito authorizer; register
-ERC-8004/8183 **last** with the deployed AgentCore endpoint:
+**Self-deploy scaffold** (`--destination self`) - the Agent serves the selected protocol directly behind a mandatory Cognito authorizer; register ERC-8004/8183 **last** with the deployed AgentCore endpoint:
 
 ```bash
 bag deploy prepare                 # readiness sweep
@@ -193,42 +103,29 @@ bag deploy --provider aws          # ship the Agent to AgentCore
 bag deploy verify --provider aws   # delegated status + reconcile ERC-8004 identity
 ```
 
-Gotcha: `bag deploy --provider aws` provisions the Cognito user pool and the
-buyer M2M client itself and prints the token URL, client id, and scope — hand
-those to each buyer (Cognito has no public M2M self-registration; retrieve the
-client secret read-only from the AWS Console). Do not run
-`bag deploy provision-cognito`: it is deprecated and its CDK pool is never used
-by a deploy.
+Gotcha: `bag deploy --provider aws` provisions the Cognito user pool and the buyer M2M client itself and prints the token URL, client id, and scope - hand those to each buyer (Cognito has no public M2M self-registration; retrieve the client secret read-only from the AWS Console). Do not run `bag deploy provision-cognito`: it is deprecated and its CDK pool is never used by a deploy.
 
-Gotcha: `dispute_window` is read from the on-chain policy contract (24h on
-testnet). Buyers can dispute within that window after submit — the Agent can't
-claim funds until the window closes.
+Gotcha: `dispute_window` is read from the on-chain policy contract (24h on testnet). Buyers can dispute within that window after submit - the Agent can't claim funds until the window closes.
 
-## Step 6 — Verify
+## Step 6 - Verify
 
 ```bash
 bag doctor    # run from workspace root; scans the agent sub-project
 ```
 
-Should show green for: `app/agent/studio.toml` present, wallet decryptable (needs
-`WALLET_PASSWORD` set in `.studio/.env.local`), RPC reachable, 8004 identity
-registered (if applicable), LLM key present (if `[llm]` configured in
-`app/agent/studio.toml`).
+Should show green for: `app/agent/studio.toml` present, wallet decryptable (needs `WALLET_PASSWORD` set in `.studio/.env.local`), RPC reachable, 8004 identity registered (if applicable), LLM key present (if `[llm]` configured in `app/agent/studio.toml`).
 
 If anything is red, fix and re-run `bag doctor` before deploying.
 
-## Step 7 — Smoke test the Agent locally
+## Step 7 - Smoke test the Agent locally
 
-`bag dev` from the workspace root launches the Agent with the selected protocol.
-Locally it runs without Cognito env, so the A2A card / MCP metadata is reachable
-without a token:
+`bag dev` from the workspace root launches the Agent with the selected protocol. Locally it runs without Cognito env, so the A2A card / MCP metadata is reachable without a token:
 
 ```bash
 bag dev               # A2A on :9000, or MCP on :8000/mcp
 ```
 
-For A2A projects, in another shell, fetch the card and send a `negotiate` message
-(`message/send` JSON-RPC with a single `DataPart`):
+For A2A projects, in another shell, fetch the card and send a `negotiate` message (`message/send` JSON-RPC with a single `DataPart`):
 
 ```bash
 curl -s http://localhost:9000/.well-known/agent-card.json   # 2 skills: negotiate / notify_funded
@@ -238,20 +135,12 @@ curl -X POST http://localhost:9000/ \
   -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","messageId":"nego-1","parts":[{"kind":"data","data":{"skill":"negotiate","task_description":"summarize a webpage"}}]}}}'
 ```
 
-The reply data part is the SDK `NegotiationResult` envelope, signed by the agent:
-the quoted `price`, `currency`, and the signature fields (`negotiation_hash`,
-`provider_sig`). The buyer anchors it on-chain via `createJob` + `fund`, then
-sends a `notify_funded` message; the agent acks `accepted` at once and delivers in
-the background, and the buyer reads the result from the chain (SUBMITTED →
-`deliverable_url`). For MCP projects, connect an MCP client to
-`http://localhost:8000/mcp`; `notify_funded` verifies, runs the work, and submits
-synchronously inside the tool call (see `bnbagent-studio-selling-via-8183.md` (same directory) and
-`docs/design/erc8183-buyer-push.md`).
+The reply data part is the SDK `NegotiationResult` envelope, signed by the agent: the quoted `price`, `currency`, and the signature fields (`negotiation_hash`, `provider_sig`). The buyer anchors it on-chain via `createJob` + `fund`, then sends a `notify_funded` message; the agent acks `accepted` at once and delivers in the background, and the buyer reads the result from the chain (SUBMITTED → `deliverable_url`). For MCP projects, connect an MCP client to `http://localhost:8000/mcp`; `notify_funded` verifies, runs the work, and submits synchronously inside the tool call (see `bnbagent-studio-selling-via-8183.md` (same directory) and `docs/design/erc8183-buyer-push.md`).
 
 ## Reference
 
 - `docs/design/single-seller-agent.md` (the A2A deploy model and history).
 - `docs/design/erc8183-buyer-push.md` (how a buyer drives a sale: negotiate → fund → notify_funded).
 - `docs/design/decisions.md` (single seller runtime + protocol-choice decision records).
-- `docs/design/architecture.md` (recipes, selected-protocol runtime, project layout — §2.5 / §9.2).
-- `bnbagent-studio-selling-via-8183.md` (same directory) — the runtime seller flow (negotiate/notify_funded/settle, disputes).
+- `docs/design/architecture.md` (recipes, selected-protocol runtime, project layout - §2.5 / §9.2).
+- `bnbagent-studio-selling-via-8183.md` (same directory) - the runtime seller flow (negotiate, notify_funded, submit, and dispute defense); buyer settlement lives in the buying reference.

package/skills/references/bnbagent-studio-buying-from-bazaar.md

@@ -1,69 +1,45 @@
 ---
 name: bnbagent-studio-buying-from-bazaar
-description: When the user wants their agent to buy a paid x402 capability — market data, inference, any pay-per-call API — from the Binance Bazaar (B402) or any other x402 service. Owns discovery (browse the Bazaar / studio recommendations), trusting a merchant (`bag x402 trust`), wiring the buyer @tools (x402-buyer recipe), verifying with a paid test call, and the mainnet-money caveats.
+description: When the user wants their agent to buy a paid x402 capability - market data, inference, any pay-per-call API - from the Binance Bazaar (B402) or any other x402 service. Owns discovery (browse the Bazaar / studio recommendations), trusting a merchant (`bag x402 trust`), wiring the buyer @tools (x402-buyer recipe), verifying with a paid test call, and the mainnet-money caveats.
 ---
 
-> **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.
+> **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.
 
 # bnbagent-studio-buying-from-bazaar
 
-Procedure to give an agent a **paid capability**: the agent calls an
-x402-protected API (e.g. CoinMarketCap market data), receives a `402 Payment
-Required`, signs a $U payment locally, retries, and gets the data — all
-automatic at runtime. This is the buyer counterpart of what the seller side
-already does over x402.
+Procedure to give an agent a **paid capability**: the agent calls an x402-protected API (e.g. CoinMarketCap market data), receives a `402 Payment Required`, signs a $U payment locally, retries, and gets the data - all automatic at runtime. This is the buyer counterpart of what the seller side already does over x402.
 
 **The three roles, kept separate** (do not conflate):
 
-- **Bazaar** (`https://www.binance.com/bapi/ramp/v1/public/ramp/b402/bazaar/…`)
-  — a public, auth-free **catalog** of x402 merchants. It is never in the data
-  path and never in the payment path.
-- **The merchant** (e.g. CMC) — the agent talks to it **directly**: request →
-  402 → signed retry → data.
-- **B402 facilitator** (verify/settle, gas fronted) — the **merchant's**
-  payment plumbing. The agent never calls it.
+- **Bazaar** (`https://www.binance.com/bapi/ramp/v1/public/ramp/b402/bazaar/…`) - a public, auth-free **catalog** of x402 merchants. It is never in the data path and never in the payment path.
+- **The merchant** (e.g. CMC) - the agent talks to it **directly**: request → 402 → signed retry → data.
+- **B402 facilitator** (verify/settle, gas fronted) - the **merchant's** payment plumbing. The agent never calls it.
 
-**Recommendation, not admission**: studio ships a reviewed shelf
-(the CLI's built-in recommended-merchants table — today: CMC's 4 market-data
-endpoints), but
-any x402 service can be trusted by URL. Studio recommends; it never
-gate-keeps the user's own spending choices.
+**Recommendation, not admission**: studio ships a reviewed shelf (the CLI's built-in recommended-merchants table - today: CMC's 4 market-data endpoints), but any x402 service can be trusted by URL. Studio recommends; it never gate-keeps the user's own spending choices.
 
-## Step 0 — know what's on offer
+## Step 0 - know what's on offer
 
-Studio-reviewed (the fast path): run `bag x402 trust cmc` and skip to Step 1.
-CMC's 4 endpoints (all `$0.01/call`, base `https://pro-api.coinmarketcap.com`):
+Studio-reviewed (the fast path): run `bag x402 trust cmc` and skip to Step 1. CMC's 4 endpoints (all `$0.01/call`, base `https://pro-api.coinmarketcap.com`):
 
 | Endpoint | Path | Good for |
-|---|---|---|
+| --- | --- | --- |
 | Quotes Latest | `/x402/v3/cryptocurrency/quotes/latest?id=1` | prices, holdings briefs, price alerts |
 | Listings Latest | `/x402/v3/cryptocurrency/listings/latest?start=1&limit=10` | top-N market overviews, rotation signals |
 | DEX Search | `/x402/v1/dex/search?q=bnb` | new-token discovery, name checks |
 | DEX Pairs Quotes | `/x402/v4/dex/pairs/quotes/latest?pair_address=0x…` | pool liquidity/volume, LP monitoring |
 
-Browsing the wider Bazaar (optional): the discovery API is public JSON —
-`GET …/bazaar/search?query=<keyword>&limit=10`, `…/bazaar/resources`,
-`…/bazaar/merchant?payTo=0x…`. Each resource carries `accepts[]` (who gets
-paid, in what asset, on which chain) and 30-day quality signals
-(`l30DaysTotalCalls`, `l30DaysUniquePayers`). Merchants found there are
-**unreviewed** — trust them by URL only after checking the payTo out-of-band.
+Browsing the wider Bazaar (optional): the discovery API is public JSON - `GET …/bazaar/search?query=<keyword>&limit=10`, `…/bazaar/resources`, `…/bazaar/merchant?payTo=0x…`. Each resource carries `accepts[]` (who gets paid, in what asset, on which chain) and 30-day quality signals (`l30DaysTotalCalls`, `l30DaysUniquePayers`). Merchants found there are **unreviewed** - trust them by URL only after checking the payTo out-of-band.
 
-> Doc lag warning: a merchant's human docs may lag its live 402 (CMC's page
-> documents only Base/USDC; the live challenge also accepts BSC $U via
-> EIP-3009). Machine decisions always come from the live `accepts[]` — which
-> is exactly what `bag x402 trust` and `bag x402 quote` read.
+> Doc lag warning: a merchant's human docs may lag its live 402 (CMC's page documents only Base/USDC; the live challenge also accepts BSC $U via EIP-3009). Machine decisions always come from the live `accepts[]` - which is exactly what `bag x402 trust` and `bag x402 quote` read.
 
-## Step 1 — trust the merchant (writes config, never pays)
+## Step 1 - trust the merchant (writes config, never pays)
 
 ```bash
 bag x402 trust cmc                       # studio-reviewed: pinned payTo byte-compared vs live 402
 bag x402 trust https://api.example.com/thing --cap 0.05   # any other x402 service (unreviewed)
 ```
 
-What it does: probes the live 402 (free), shows **who gets paid and how much
-per call**, then — after your explicit confirmation — writes:
+What it does: probes the live 402 (free), shows **who gets paid and how much per call**, then - after your explicit confirmation - writes:
 
 ```toml
 [payments.x402.merchants.cmc]
@@ -73,19 +49,15 @@ per_call_cap_usd = 0.02                                 # clamps every call, LLM
 verified = true                                         # studio-reviewed shelf
 ```
 
-Hard-stop cases: a reviewed merchant whose live payTo drifts from the studio
-pin (address rotation or tampering — upgrade studio or verify out-of-band and
-pass `--pay-to`), and `--cap` below the live per-call price.
+Hard-stop cases: a reviewed merchant whose live payTo drifts from the studio pin (address rotation or tampering - upgrade studio or verify out-of-band and pass `--pay-to`), and `--cap` below the live per-call price.
 
-## Step 2 — wire the buyer tools into the agent
+## Step 2 - wire the buyer tools into the agent
 
 ```bash
 bag recipe code x402-buyer        # emits src/x402Buyer.ts (next to src/tools.ts)
 ```
 
-Then wire the set into the agent's LLM in `src/main.ts` (A2A) or
-`src/mcpMain.ts` (MCP) — the scaffold's `tools:` line carries this exact hint
-in a comment:
+Then wire the set into the agent's LLM in `src/main.ts` (A2A) or `src/mcpMain.ts` (MCP) - the scaffold's `tools:` line carries this exact hint in a comment:
 
 ```ts
 import { X402_BUYER_TOOLS } from "./x402Buyer.js";
@@ -93,32 +65,16 @@ import { X402_BUYER_TOOLS } from "./x402Buyer.js";
 tools: { ...LLM_READ_TOOLS, ...X402_BUYER_TOOLS },
 ```
 
-This is the whole point of the feature: the DEPLOYED agent buys the data
-itself at work time (e.g. inside `notify_funded` while producing a
-deliverable) — the CLI commands below are only the operator's test rig.
-The LLM gets two tools:
-
-- `buy_with_x402(url, max_usd, method="GET")` — pay + fetch. The LLM chooses
-  **which** allowed URL to call and with what query params; it can NEVER
-  choose who gets paid (pinned `pay_to`) or widen the caps (per-call cap,
-  `[budget].max_per_day_usd`, `[payments.x402].max_per_request_usd`).
-- `quote_x402(url, method="GET")` — free 402 inspection.
-
-This is commitment #3 intact: signing stays fixed handler code; the merchant
-table is user-confirmed config, not an LLM-writable surface.
-
-> **For the agent's LLM — the one invariant it keeps getting wrong:** x402
-> merchants need **NO API key**. CMC's x402 endpoints (and every Bazaar
-> merchant) authenticate the caller by the on-chain EIP-3009 payment the
-> agent's wallet signs — there is no `Authorization` / `X-API-KEY` header
-> anywhere. So when a funded task asks for CMC/paid data and `buy_with_x402`
-> is in the toolset, the LLM MUST call it — it must never fall back to "I need
-> an API key / I can't do this without a key." Payment is already fenced by
-> `per_call_cap_usd` + `[budget].max_per_day_usd`, so the call is always safe
-> to make. The recipe bakes this into the tool description and the scaffold's
-> `system` prompt; keep it there if you edit them.
-
-## Step 3 — verify end to end
+This is the whole point of the feature: the DEPLOYED agent buys the data itself at work time (e.g. inside `notify_funded` while producing a deliverable) - the CLI commands below are only the operator's test rig. The LLM gets two tools:
+
+- `buy_with_x402(url, max_usd, method="GET")` - pay + fetch. The LLM chooses **which** allowed URL to call and with what query params; it can NEVER choose who gets paid (pinned `pay_to`) or widen the caps (per-call cap, `[budget].max_per_day_usd`, `[payments.x402].max_per_request_usd`).
+- `quote_x402(url, method="GET")` - free 402 inspection.
+
+This is commitment #3 intact: signing stays fixed handler code; the merchant table is user-confirmed config, not an LLM-writable surface.
+
+> **For the agent's LLM - the one invariant it keeps getting wrong:** x402 merchants need **NO API key**. CMC's x402 endpoints (and every Bazaar merchant) authenticate the caller by the on-chain EIP-3009 payment the agent's wallet signs - there is no `Authorization` / `X-API-KEY` header anywhere. So when a funded task asks for CMC/paid data and `buy_with_x402` is in the toolset, the LLM MUST call it - it must never fall back to "I need an API key / I can't do this without a key." Payment is already fenced by `per_call_cap_usd` + `[budget].max_per_day_usd`, so the call is always safe to make. The recipe bakes this into the tool description and the scaffold's `system` prompt; keep it there if you edit them.
+
+## Step 3 - verify end to end
 
 ```bash
 bag x402 quote "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1"   # free
@@ -126,44 +82,27 @@ bag x402 buy   "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/
 bag dev        # then ask the agent something that needs the paid data
 ```
 
-`buy` needs `WALLET_PASSWORD` set and the wallet funded with mainnet $U (see
-money section below). A successful `buy` prints `✓ Paid: 0.01 USD` plus the
-response body — that is the whole x402 loop proven.
-
-## The money — read before funding
-
-- **Mainnet, real $U.** CMC (and current Bazaar merchants) settle **only** on
-  BSC mainnet (`eip155:56`); there is no testnet channel. This is independent
-  of your project's `[network].default` — a testnet seller can still buy
-  mainnet data.
-- **Exposure is fenced** three ways: per-call `per_call_cap_usd`, per-request
-  `max_per_request_usd`, and the daily `[budget].max_per_day_usd` (shared
-  ledger at `.studio/spend-ledger.json`).
-- **Platform trials:** `bag deploy` warns (never blocks) when
-  `[deploy].destination = "platform"` meets a merchants table — the trial
-  ships the wallet key to the operator's Secrets Manager under
-  testnet-scoped consent. For paid-capability agents prefer self-deploy, or
-  keep a throwaway wallet holding only pocket money.
-- **Funding**: buy $U on PancakeSwap
-  (`?outputCurrency=0xcE24439F2D9C6a2289F741120FE202248B666666`) to the agent
-  wallet address (`bag wallet status`). A few dollars covers hundreds of CMC
-  calls; x402 payments themselves are gasless for the buyer (the facilitator
-  fronts gas).
+`buy` needs `WALLET_PASSWORD` set and the wallet funded with mainnet $U (see money section below). A successful `buy` prints `✓ Paid: 0.01 USD` plus the response body - that is the whole x402 loop proven.
+
+## The money - read before funding
+
+- **Mainnet, real $U.** CMC (and current Bazaar merchants) settle **only** on BSC mainnet (`eip155:56`); there is no testnet channel. This is independent of your project's `[network].default` - a testnet seller can still buy mainnet data.
+- **Exposure is fenced** three ways: per-call `per_call_cap_usd`, per-request `max_per_request_usd`, and the daily `[budget].max_per_day_usd` (shared ledger at `.studio/spend-ledger.json`).
+- **Platform trials:** `bag deploy` warns (never blocks) when `[deploy].destination = "platform"` meets a merchants table - the trial ships the wallet key to the operator's Secrets Manager under testnet-scoped consent. For paid-capability agents prefer self-deploy, or keep a throwaway wallet holding only pocket money.
+- **Funding**: buy $U on PancakeSwap (`?outputCurrency=0xcE24439F2D9C6a2289F741120FE202248B666666`) to the agent wallet address (`bag wallet status`). A few dollars covers hundreds of CMC calls; x402 payments themselves are gasless for the buyer (the facilitator fronts gas).
 
 ## Troubleshooting
 
 | Symptom | Meaning / fix |
-|---|---|
+| --- | --- |
 | `X402HostNotAllowedError` | Merchant not trusted yet → `bag x402 trust <merchant\|url>` |
 | `X402RecipientRequiredError` | No pinned recipient for that host → same fix |
-| `X402RecipientMismatchError` | Live payTo drifted from the pin — do NOT override casually; re-verify the merchant |
-| `X402BudgetExhaustedError` | Per-call cap or daily budget hit — raise `per_call_cap_usd` / `[budget].max_per_day_usd` deliberately |
-| `x402 402 has no EIP-3009-payable option` | Merchant offers only permit2/other methods for $U on this network — not payable by this buyer today |
-| `X402PolicyError` / `PolicyViolation` | Signing allowlist — see `bnbagent-studio-extending-signing.md` |
+| `X402RecipientMismatchError` | Live payTo drifted from the pin - do NOT override casually; re-verify the merchant |
+| `X402BudgetExhaustedError` | Per-call cap or daily budget hit - raise `per_call_cap_usd` / `[budget].max_per_day_usd` deliberately |
+| `x402 402 has no EIP-3009-payable option` | Merchant offers only permit2/other methods for $U on this network - not payable by this buyer today |
+| `X402PolicyError` / `PolicyViolation` | Signing allowlist - see `bnbagent-studio-extending-signing.md` |
 
 **Different from**:
-- `bnbagent-studio-buying-via-8183.md` (same directory) — buying from an
-  **ERC-8183 seller agent** (jobs, disputes, settle windows). This file is
-  about flat pay-per-call x402 APIs; no job lifecycle.
-- `bnbagent-studio-extending-signing.md` — the signing-policy allowlist
-  mechanics that back all of this.
+
+- `bnbagent-studio-buying-via-8183.md` (same directory) - buying from an **ERC-8183 seller agent** (jobs, disputes, settle windows). This file is about flat pay-per-call x402 APIs; no job lifecycle.
+- `bnbagent-studio-extending-signing.md` - the signing-policy allowlist mechanics that back all of this.