@bnbagent/studio-cli 0.0.6-alpha.1

package/skills/bnbagent-studio.md

@@ -0,0 +1,107 @@
+---
+name: bnbagent-studio
+description: The single entry point for bnbagent-studio — a TypeScript CLI (`bag`) for building a blockchain SELLER agent that earns $U on BNB Chain via ERC-8004 + ERC-8183 + x402 (Pieverse LLM inside). Load this skill whenever the user works in a bnbagent-studio / `bag` project, or wants to create/scaffold, deploy, run, debug, operate, or monetize such a seller agent (composable A2A, MCP, and X402 faces; BNB Chain trial, AWS AgentCore, or Azure Foundry). All detailed playbooks ship as references/ files inside this skill — route via the decision tree in the body. When invoked with arguments, treat them as the user's intent and route the same way.
+---
+
+# bnbagent-studio (the single entry point)
+
+`bnbagent-studio` (CLI: `bag`) wires the `@bnbagent/sdk` protocol layer (wallet /
+ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploys it
+as a **single blockchain seller runtime**. A2A, MCP, and X402 are composable
+public faces selected with `--protocols`; A2A is the default. `bag deploy` uses
+**scheme C**: every new deploy
+or redeploy explicitly selects BNB, AWS, or Azure; a recorded deployment is
+used only to offer an explicit update action, never as a silent default. BNB is
+a 48h testnet trial and is disabled after expiry. AWS and Azure deploy into the
+user's own account. All cloud lifecycle calls go through the pinned
+`@bnbagent/deploy-cli`; never require `aws`, `az`, or `azd` CLIs.
+BNB/AWS share the agentcore scaffold; Azure requires the azure-foundry
+container scaffold and currently deploys A2A projects only (Foundry's
+Invocations contract is not the native MCP transport). Treat an incompatible provider row as unavailable—do not
+force through it or mutate the scaffold during deploy.
+
+Invoked as `/bnbagent-studio <ask>`? Treat `<ask>` as the user's intent and
+route it through the decision tree below, exactly like a natural-language ask.
+
+## The single seller runtime model (the invariants)
+
+One deployed runtime, one signer: a single valuable Agent serves the selected
+faces (A2A `src/main.ts` on `:9000`, MCP `src/mcpMain.ts` on `:8000/mcp`, or
+A2A-native `src/dualMain.ts` on `:9000` with tunneled `/mcp`),
+holds the key, and signs in-process. The ERC-8183 rail exposes exactly two
+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
+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
+`.studio/wallets/`, outside the deploy codeLocation, and is injected only via
+the selected provider's delegated secret channel. `settle` is manual
+(`bag erc8183 settle`). Full layout and lifecycle details live in the
+references below — read them before acting.
+
+## Decision tree — which reference to read next
+
+**References are plain markdown files installed in THIS skill's directory** at
+`references/<name>.md`. When a row matches, READ THAT FILE before acting — do
+not answer from memory.
+
+| User intent | Read / do |
+|---|---|
+| Create a brand new single seller project from zero | `references/bnbagent-studio-scaffolding-agent.md` |
+| 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` |
+| 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` |
+| Give the agent a PAID x402 capability — CMC market data / Binance Bazaar (B402) merchants / any pay-per-call API (`bag x402 trust`, x402-buyer recipe, 402 buyer errors) | `references/bnbagent-studio-buying-from-bazaar.md` |
+| Extend the EIP-712 signing allowlist (custom contract / new x402 service / diagnose `PolicyViolation` / `X402PolicyError`) | `references/bnbagent-studio-extending-signing.md` |
+| Project uses `[wallet].kind = "twak"` (create / fund / SIWE-bind / container deploy / known limitations) | `references/bnbagent-studio-using-twak-wallet.md` |
+| Project uses `[wallet].kind = "altana"` (admin keystore / bounded session / quote checker / x402 allowance / local dev) | `references/bnbagent-studio-using-altana-wallet.md` |
+| (Pieverse projects only) Fund the LLM, switch to a paid model, hit insufficient credits (`PieverseBudgetExhaustedError` / `PieverseAccountBalanceExhaustedError`) | skill `funding-pieverse-llm` (project-scope; emitted at `bag init --llm-provider pieverse-llm`) |
+
+If two or more match, read both — they're designed to be orthogonal.
+
+### Where the references live
+
+Next to this file: this skill installs as a directory with a `references/`
+subdirectory (Claude Code: `~/.claude/skills/bnbagent-studio/references/` or the
+project-scope `<project>/.claude/skills/bnbagent-studio/references/`; Cursor:
+`bnbagent-studio/references/` under the rules directory, beside the `.mdc`
+rules). If a reference file is missing, `bag skills install` (re)installs it.
+
+<!-- Maintainers: this skill's DESCRIPTION only carries ENTRY intents (identity
++ create/deploy/run/debug/operate/monetize). Mid-journey topics (twak, EIP-712,
+disputes, buyer flow, tool wiring, ...) are routed by the decision tree above and
+must NOT be added to the description — see docs/design/decisions.md §14. -->
+
+## 5 core commitments (always honor)
+
+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.
+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.
+
+## 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`.
+
+## Tool surface
+
+- **CLI** — write-side (wallet ops, on-chain register, x402 buy, deploy)
+- **MCP** — an external seller face (`bag init --protocols MCP`), composable
+  with A2A; dual mode is A2A-native so `HEALTHY_BUSY` preserves background work
+- **`@bnbagent/studio-runtime/tools`** — 15 pure read-only functions, wrapped into LLM tools by the chain-tools recipe (read `references/bnbagent-studio-wiring-llm-tools.md`)
+
+## Where docs live
+
+- `docs/design/architecture.md` — layered architecture
+- `docs/design/decisions.md` — decision records (Pieverse default, signing policy, chain tools, zero-deposit, skill reorg, **single seller runtime + protocol faces**)
+- `docs/guides/pieverse-integration.md` — Pieverse LLM full lifecycle
+- `docs/guides/user-guide.md` — end-user procedures

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

@@ -0,0 +1,241 @@
+---
+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.
+
+# 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.
+
+## 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.
+
+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).
+- Network access to BSC testnet RPC (default: `https://data-seed-prebsc-1-s1.binance.org:8545`).
+
+## Step 1 — Bootstrap studio config
+
+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):
+
+```bash
+bag init my-agent && cd my-agent   # creates ./my-agent/ 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.
+
+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)
+
+```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.
+
+## 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:
+
+```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`.
+
+## 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, AWS, or Azure; 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:
+
+```bash
+bag deploy prepare                 # readiness sweep
+bag deploy provision-cognito       # emits the Cognito CDK app you run (cdk deploy); wires discoveryUrl/clientId
+bag deploy --provider aws          # ship the Agent to AgentCore
+bag deploy verify --provider aws   # delegated status + reconcile ERC-8004 identity
+```
+
+Gotcha: to serve external buyers, configure the Cognito authorizer
+(`provision-cognito` → `cdk deploy --outputs-file` → `provision-cognito --wire`);
+`bag deploy prepare` warns (W9) if unset but does NOT block. With no authorizer
+the runtime is IAM/SigV4 owner-only (never anonymous) — external buyers without
+AWS creds just can't reach it.
+
+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
+
+```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`).
+
+If anything is red, fix and re-run `bag doctor` before deploying.
+
+## 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:
+
+```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`):
+
+```bash
+curl -s http://localhost:9000/.well-known/agent-card.json   # 2 skills: negotiate / notify_funded
+
+curl -X POST http://localhost:9000/ \
+  -H 'Content-Type: application/json' \
+  -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`).
+
+## 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).

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

@@ -0,0 +1,169 @@
+---
+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.
+---
+
+> **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.
+
+**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.
+
+**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
+
+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.
+
+> 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)
+
+```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:
+
+```toml
+[payments.x402.merchants.cmc]
+domain = "pro-api.coinmarketcap.com"
+pay_to = "0x3C5f3a6cE224BB89D72f5EB4232ecC27F67B3eeA"  # pinned; byte-compared on every payment
+per_call_cap_usd = 0.02                                 # clamps every call, LLM cannot widen
+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.
+
+## 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:
+
+```ts
+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
+
+```bash
+bag x402 quote "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1"   # free
+bag x402 buy   "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1" --max-usd 0.02
+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).
+
+## 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` |
+
+**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.