@bnbagent/studio-cli

Build and operate a TypeScript seller agent on BNB Chain by describing what you want in Claude Code or Cursor.

The bundled /bnbagent-studio skill is the primary interface. It turns your intent into a safe, reviewable workflow and drives the bag CLI for you. bag remains available as the executable interface for automation and for developers who prefer direct control.

Studio is under active development and may introduce breaking changes. Start on BSC testnet with a wallet funded only for the task.

What Studio builds

• One valuable agent, one wallet, one signer. The same runtime can serve A2A, MCP, and one B402 payment face (X402 or MPP) without splitting custody across services.
• On-chain identity. ERC-8004 makes the deployed agent discoverable and records its live service endpoint.
• Two ways to earn. ERC-8183 handles negotiated, escrowed jobs; x402 or MPP handles instant HTTP requests, with B402 settlement in paid mode.
• Bounded signing. Quotes and payment checks run in fixed code. Raw signing is never exposed to the LLM, whose chain tools are read-only.
• A project you own. Studio generates ordinary TypeScript under app/agent/; edit, fork, or move that code whenever you want.
• A guided path to production. Run locally, diagnose readiness, deploy to the managed BSC testnet trial, your own AWS AgentCore/Azure Foundry account, or CreateOS, then register the public endpoint.

Start with the skill

Requirements

• Node.js 22 or newer.
• Claude Code or Cursor.
• Corepack and pnpm 10 for the generated workspace.
• Bun 1.3 or newer when you deploy.
• Docker only for container paths such as a twak deployment. The AWS CLI is optional and is used only for a read-only AgentCore quota check.

1. Install Studio and its IDE skill

npm install --global @bnbagent/studio-cli
bag skills install

The npm install puts the bag CLI on your machine once; each agent you build later gets its own project directory (scaffolded by bag init, which the skill drives for you). bag skills install detects Claude Code and Cursor, lets you choose user or project scope, and installs the /bnbagent-studio router plus its on-demand playbooks. For a scripted install, choose the target and scope explicitly:

bag skills install --target both --scope user

Reload the IDE after installation so it discovers the skill.

2. Tell the skill what you want to sell

Open Claude Code or Cursor in the directory where the project should be created, then start with a prompt such as:

/bnbagent-studio Create a BNB Chain seller agent named weatheragent.
Start on BSC testnet, explain the available choices, then build and run it.

You can be more specific:

/bnbagent-studio Create an agent named researchagent that sells cited research reports.
Use ERC-8183, expose A2A and MCP, use the default wallet and LLM, store
deliverables on IPFS, and prepare it for the 48-hour BNB testnet trial.

Continue in natural language after creation:

/bnbagent-studio Implement the report-generation work, then run the agent locally
and diagnose anything blocking a funded delivery.

/bnbagent-studio Check deployment readiness, explain every permission and cost,
then deploy after I approve the target.

The skill asks for the decisions it needs in one round, shows its work as a todo list, and routes each stage to the relevant bundled playbook. You do not need to memorize the CLI.

3. Keep control of sensitive steps

The skill can prepare and run the workflow, but it leaves consequential decisions with you:

• approve each shell command in your IDE; do not grant a blanket bag:* permission because the CLI includes deploy and payment commands;
• enter wallet passwords through hidden prompts or .studio/.env.local, never in chat or command-line arguments;
• obtain testnet funds and decide how much value a wallet may hold;
• review cloud permissions, runtime-secret exposure, and possible costs before deployment;
• confirm on-chain transactions and buyer settlement actions.

The choices are composable

Studio does not force every agent through one fixed path. The skill guides these independent choices and checks incompatible combinations before it changes the project.

| Dimension | Choices | What to know | | --- | --- | --- | | Network | bsc-testnet, bsc-mainnet | Start on testnet. The managed BNB trial always uses BSC testnet. | | Wallet | evm-local, twak, altana | Local encrypted keystore, Trust Wallet Agent Kit custody, or a bounded Altana runtime session. | | LLM | Pieverse, OpenRouter, OpenAI, Anthropic, Bedrock | Pieverse is the default; auto/free starts at $0/token. Other providers use your own credentials. | | Commerce rails | ERC-8183, B402, or both | ERC-8183 is job escrow. B402 settles request payments. Rails and public faces are separate choices. | | Public faces | A2A, MCP, and either X402 or MPP | X402 and MPP are alternative adapters for the same B402 seller and cannot be selected together. | | Deployment | BNB managed trial, AWS AgentCore, Azure Foundry or CreateOS | Every deploy asks for bnb, aws, azure or nodeops; a previous deployment is never a silent default. | | Deliverable storage | local, IPFS, S3, Azure Blob | Self-hosted deploys are BYOS: use IPFS, S3, or Azure Blob with a stable public read URL. Platform deploys ignore the project's local/BYOS choice; the API injects an agent-scoped token and uses managed S3 on AWS or Azure Blob on Azure. Public deliverable URLs stay on bnbagent-api and return 404 after the Agent is deleted. |

Wallet choices

| Wallet | Custody model | Packaging | Important limits | | --- | --- | --- | --- | | evm-local (default) | Encrypted keystore in workspace-root .studio/wallets/ | Node code zip by default | Set WALLET_PASSWORD in the owner-only local env file. The keystore stays outside app/agent/. | | twak | Self-custody wallet managed by Trust Wallet Agent Kit in a project-dedicated home | Container | Requires the supported TWAK CLI. Docker is required for the managed-platform image path. | | altana | Local admin keystore grants a budget- and time-bounded runtime session | Node code zip | The runtime receives only the session. Pieverse SIWE activation is not supported; paid B402 payouts land at the admin address; renew or revoke the session explicitly. |

For AWS, runtime material is injected into infrastructure in your own account. For the managed BNB trial, the runtime runs in the operator's cloud: evm-local and twak signing material is transmitted to its managed secret store. Use a fresh testnet-only wallet and never reuse it on mainnet. An Altana deployment sends only its bounded session; keep the budget and expiry tight.

The end-to-end journey

The skill normally takes a new seller through six stages:

1. Install and design. It gathers the agent name, what it sells, network, wallet, LLM, rails, faces, storage, pricing, and deployment intent, then runs bag init.
2. Create custody and activate the model. It creates or adopts the selected wallet without putting a password on the command line, helps fund the testnet wallet, and activates or tests the LLM.
3. Implement the value. You edit the generated runWork hook in app/agent/src/sellerCore.ts. Pricing and signing stay in deterministic code.
4. Run and diagnose. bag doctor checks the project, wallet, balances, LLM, network, and local runtime; bag dev starts the selected faces. Before deployment, bag deploy prepare adds storage, provider, and deploy-tooling gates.
5. Deploy and publish identity. bag deploy prepare gates readiness, bag deploy --provider ... ships the runtime, and bag deploy verify --provider ... reconciles its ERC-8004 identity with the live endpoint.
6. Earn and settle. Buyers fund ERC-8183 jobs or pay an x402/MPP request. The agent verifies payment before work, submits the result, and records an audit trail.

What gets generated

weatheragent/
├── package.json                 workspace marker
├── pnpm-workspace.yaml
├── AGENTS.md                    generated safety rules for coding agents
├── agentcore/
│   ├── agentcore.json           deployment descriptor
│   └── aws-targets.json         AWS account and region for self-deploy
├── .studio/
│   ├── .env.local               gitignored secrets, mode 0600
│   └── wallets/                 encrypted keystore outside deployable code
└── app/agent/
    ├── studio.toml              network, wallet, LLM, policy, rails, faces
    └── src/
        ├── sellerCore.ts        the work your agent sells
        ├── signing.ts           fixed quote, verification, and submission path
        ├── tools.ts             read-only chain tools for the LLM
        ├── main.ts              A2A/X402 entrypoint
        ├── mcpMain.ts           MCP-only entrypoint
        └── dualMain.ts          combined A2A + MCP entrypoint

The generated agent depends on @bnbagent/studio-runtime, not on the CLI. Removing the global CLI does not remove or disable an already generated runtime.

How a seller gets paid

ERC-8183: negotiated work with escrow

ERC-8183 is the default rail for work that has a description, deliverables, quality standards, and a settlement decision.

1. A buyer calls negotiate. Fixed code reads [payments.seller].price_usd, converts it exactly for the selected asset, and signs a quote; no LLM participates in pricing.
2. The buyer creates the on-chain job, registers it, sets a budget, and funds escrow.
3. The buyer sends notify_funded with the job ID.
4. The seller verifies the signed terms, assigned provider, status, budget, and funded state on-chain before doing paid work.
5. The LLM performs only the requested work. A2A acknowledges first and delivers in the background; MCP completes inside the tool call.
6. The seller stores the deliverable and submits its reference on-chain.
7. The buyer fetches the result and manually chooses approve, reject, or dispute. Studio never silently auto-settles a buyer's job.

Canonical FREE pricing is explicit TOML:

[payments.seller]
price_usd = "0"

It creates a FREE ERC-8183 job and skips token escrow, but state-changing calls still need the configured gas or sponsored path. A paid job is bound to exactly one immutable catalog token; all configured tokens use the same USD price. Legacy U-only projects without [payments.seller] keep [payments.erc8183] price/min_price/max_price clamp semantics. Those bounds never clamp the canonical USD price, and combining canonical pricing with any legacy price or asset field is rejected as ambiguous.

x402: pay per HTTP request

The X402 face exposes /x402. Its seller rail has two intentional modes:

• a positive price_usd returns a payment challenge and uses B402 to verify and settle before work starts;
• [payments.seller] with price_usd = "0" is anonymous FREE passthrough and bypasses B402 credentials, verification, settlement, and payment auditing.

Paid mode requires a complete per-agent B402 merchant setup; any supported wallet kind can be the payout wallet (for altana the payout lands at the admin address). Payment settles before work; if later work fails, there is no automatic refund. On self-hosted AWS AgentCore the rail runs in-process, but a buyer-facing x402 URL requires your own gateway that authenticates its relay call to AgentCore and, for paid mode, a fixed-egress path to B402.

MPP+B402: the alternative request-payment protocol

Use bag init <name> --rails b402 --payment-protocol mpp. The generated project selects the MPP face, mounts /mpp, and uses the canonical [payments.b402_seller] policy. It emits only MPP—not x402—deployment publication metadata. Paid MPP additionally requires a 32-byte-or-longer MPP_SECRET_KEY, a stable MPP_REALM, and a durable atomic replay store shared by all production instances. See the MPP+B402 guide.

MPP buyer commands mirror the x402 workflow while remaining protocol-explicit:

bag mpp trust https://seller.example/mpp --yes
bag mpp quote https://seller.example/mpp --asset U
bag mpp buy https://seller.example/mpp --asset U --max-usd 0.10
bag recipe code mpp-buyer

The buyer requires a local EIP-712 signing backend, accepts EIP-3009 only, pins realm plus recipient before signing, and never falls back to x402. Mainnet USD1 is implemented on this path at 0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d (18 decimals; World Liberty Financial USD / 1 domain) and has no Permit2 route; real Commerce/facilitator verification remains a release gate. USDC/USDT are Permit2-only in the current catalog, so MPP Buyer returns a typed unsupported error for them. Testnet does not support USD1. Testnet U uses 0x330949Aed7d00FCe0558C64ED6FeC9792616cC39 with 6 decimals on B402/x402/MPP. Unknown post-dispatch outcomes are audited and never retried automatically. The emitted recipe is shared by AgentCore and Azure Foundry runtimes; managed Azure seller publication additionally depends on the platform's mpp capability.

Service faces

| Face | Local surface | Commerce behavior | | --- | --- | --- | | A2A | agent card plus JSON-RPC on port 9000 | negotiate and background notify_funded delivery over ERC-8183. | | MCP | Streamable HTTP at http://localhost:8000/mcp | The same seller operations, with funded delivery completed synchronously. | | A2A + MCP | A2A-native process on port 9000, with /mcp tunneled | Both faces share one seller core, wallet, and busy-state lifecycle. | | X402 | /x402 on the selected runtime entrypoint | One paid or explicitly FREE request; independent of ERC-8183 escrow. | | MPP | /mpp on the selected runtime entrypoint | Alternative to X402; standard MPP challenge/credential/receipt headers with B402 settlement. |

For an A2A project, inspect the local agent card at http://localhost:9000/.well-known/agent-card.json. A seller expects structured A2A data parts, so a plain-text chat box is not a complete commerce test.

Deployment targets

Run the readiness sweep before either target:

bag deploy prepare

To validate the exact managed backend explicitly (including Azure projects whose scaffold intent remains self-hosted), select the same provider/backend you will deploy:

bag deploy prepare --provider bnb --backend aws
bag deploy prepare --provider bnb --backend azure

These Platform targets use managed deliverable storage, so a project-local [storage].kind = "local" does not trigger a BYOS storage blocker.

BNB Chain managed trial

bag platform login
bag platform credit
bag deploy --provider bnb
bag deploy verify --provider bnb

For an evm-local or Altana BSC testnet project, successful GitHub login also requests the operator-configured tBNB/U faucet grant; retry explicitly with bag wallet fund. Altana signs locally with its encrypted admin keystore, and funds always go to that same admin address. Amounts and post-balance caps come from the API and are not hard-coded in Studio.

This is a 48-hour BSC testnet sandbox in the operator's cloud. The clock starts on the first successful deploy and redeploying does not reset it. Runtime and data are automatically reclaimed at expiry. Use a throwaway wallet, review the key-exposure notice, and destroy the deployment early if you are finished.

Your own AWS AgentCore account

bag deploy --provider aws
bag deploy verify --provider aws

The delegated deploy validates your AWS identity, builds the agent, provisions runtime secrets and inbound Cognito OAuth, and records the live endpoint. You own the account, IAM permissions, retained resources, and charges. A default evm-local code-zip deploy does not need Docker; container paths do.

For both providers, bag deploy verify checks live provider status and then registers or updates the ERC-8004 endpoint. bag erc8004 register --endpoint <url> is the manual path when you intentionally need an identity before the normal post-deploy verification step. Altana cannot perform the generic registration signature; use the custody-specific admin flow and verify with --skip-register.

Useful lifecycle commands:

bag deploy status
bag deploy logs --provider aws
bag deploy verify --provider aws
bag deploy destroy --provider aws          # dry-run plan
bag deploy destroy --provider aws --execute

When multiple deployments exist, select the provider explicitly for logs, verification, and destruction.

Fund a BSC testnet seller

ERC-8183 defaults to the 18-decimal testnet U token and also accepts an explicitly selected catalog USDC/USDT when the Commerce allowlist is active. tBNB pays fallback gas; it is not the escrow currency.

1. Run bag wallet show and copy the agent wallet address.
2. Claim ERC-8183 testnet U by messaging the official Telegram bot https://t.me/bnbchain_official_bot — send I would like to get U to my wallet <address>. More options: https://united-coin-u.github.io/u-faucet/.
3. Claim tBNB by messaging the official Telegram bot https://t.me/bnbchain_official_bot — send I would like to get tBNB to my wallet <address> (up to 0.3 tBNB/day). More options: https://docs.bnbchain.org/bnb-smart-chain/developers/faucet/.
4. Run bag wallet balance --all and bag doctor before testing paid work.

The shared SDK catalog defines Testnet TEST_U as 0xc70B8741B8B07A6d61E54fd4B20f22Fa648E5565 with 18 decimals and EIP-3009 only. Testnet TEST_USDC is rail-specific: ERC-8183 escrow binds 0x64544969ed7EBf5f083679233325356EbE738930 with 18 decimals, while B402/x402 settles on 0xEC1C60D64a06896Df296438c12edD14E974FDE47 with 6 decimals. Testnet TEST_USDT is 18 decimals on both rails; TEST_USDC and TEST_USDT use Permit2 Exact for B402. ERC-8183 and B402/x402 resolve the same canonical AssetId, but a split asset carries different contract facts per rail. Canonical ERC-8004 and testnet ERC-8183 calls may use the configured sponsored-gas path, but keep a little tBNB for unsupported methods, token approval, custom contracts, or relay fallback. No address in this README is evidence that a Commerce deployment or live payment has passed verification.

Direct CLI reference

Use the CLI directly for automation, incident response, or when you already understand the lifecycle. The skill calls the same commands and remains the best source of context-sensitive guidance.

| Area | Commands | | --- | --- | | Skills | skills install, skills list, skills uninstall | | Project | init, scan, recipe, dev, doctor, bundle | | Local feedback | feedback (creates an inspectable redacted bundle; never uploads it) | | Configuration | config, env, agents | | Wallet and policy | wallet, wallet session, budget, audit | | Identity | erc8004 register, show, resolve, update-endpoint, update-metadata | | Escrowed commerce | erc8183 list, buy, status, submit, fetch, settle | | Instant payments | x402 quote, buy, trust, sell init, sell status | | LLM | llm activate, test, status, list-models, usage, topup, auto-renew | | Deployment | deploy, deploy prepare, verify, status, info, logs, destroy | | Managed trial | platform login, whoami, credit, agents, invoke-client, kill |

Run bag --help and bag <command> --help for the executable reference. Run bag scan for a non-mutating project inspection and bag doctor for readiness diagnostics.

Normal commands keep local diagnostics under .studio/logs/ for at most seven days, 10 MiB, and 256 generated files. bag feedback creates a redacted .studio/logs/feedback-<UUID>.json file from the most recent failure within seven days (excluding cancellations), or the latest completed run if there is no failure. Review this JSON and upload it to the form's Upload diagnostic report field yourself. If no valid run exists, feedback remains available without an attachment. Set diagnostics.enabled = false in studio.toml (or BAG_NO_DIAGNOSTICS=1 for a single invocation) to disable recording.

Only bag feedback fetches the form configuration from the platform API's public GET /v1/platform/capabilities (the official BNB Agent API by default), without login or diagnostic data. The request has a three-second timeout; missing/disabled/invalid configuration or a failed request falls back to the default Google Form. The API owns the production form URL and optional safe prefill mapping, so changes do not require a bag upgrade. Studio validates the full HTTPS Google Forms URL, displays the form identity and URL, and asks before opening a browser. Non-interactive AI/CI sessions print the file and destination without prompting or opening a browser. Studio never uploads the report or submits feedback.

Feedback resolves its API address from the original shell environment: BNBAGENT_API_URL, then BAG_PLATFORM_API_BASE, then the official production API. It prints the selected API origin and identifies shell-configured form sources. Project-local values for either variable are ignored, even when a project value would otherwise take precedence over a shell variable. For isolated development only, set BAG_FEEDBACK_DEVELOPMENT_FORM_URL_TEMPLATE and pass bag feedback --allow-development-form; this skips the API request and labels the form as an untrusted development override. The value can be a plain Google Forms viewform URL, or a prefilled template whose entry.* values are safe placeholders such as {feedback_id}, {bag_version}, {command}, or {error_code}. Templates with prefill entries must include {feedback_id}.

With AI (recommended): Ask your assistant: "Run bag feedback. Give me a link to the generated .studio/logs/feedback-<UUID>.json file so I can review it and upload it to the feedback form. If no report is generated, explain why. Do not upload or submit anything automatically."

Manually: Run bag feedback in the Studio project, then review and upload the newly generated .studio/logs/feedback-<UUID>.json file. .studio is a hidden directory; on macOS, press Command-Shift-period in the file picker to show it.

Security model

• Keep .studio/.env.local, .studio/wallets/, TWAK custody files, and Altana admin material out of version control and chat.
• Treat .studio/logs/ as local diagnostic data. Review a bag feedback JSON bundle before manually attaching it; Studio never uploads the bundle or includes the financial audit log.
• Keep wallet files at the workspace root, never under deployable app/agent/.
• Keep quote creation, funded-job verification, submission, and x402 settlement in fixed code.
• Give the LLM only read-only chain tools; do not add raw signing or arbitrary transaction tools.
• Treat x402 host, recipient, asset, network, amount, retry, and daily budget as policy boundaries.
• Change signing allowlists only after reviewing the exact domain, primary type, contract, and spend authority being added.
• Use bag deploy; bypassing it skips Studio's readiness, secret-handling, and deployment reconciliation.

Package relationship

| Package | Role | | --- | --- | | @bnbagent/studio-cli | Development and operations layer: IDE skills, scaffolding, wallet setup, diagnostics, commerce commands, and deployment. | | @bnbagent/studio-runtime | Library imported by the generated agent: config, wallet providers, policy, audit, identity, commerce, payments, storage, LLM, and read-only tools. | | @bnbagent/sdk | Lower-level BNB Chain protocol implementations consumed through the runtime. |

The CLI and runtime are versioned and released together.

Disclaimer

Studio can create wallet material, sign blockchain transactions, spend tokens through configured commerce flows, and provision cloud resources. Blockchain transactions may be irreversible, and external contracts, RPC services, payment facilitators, model providers, storage providers, and cloud platforms may fail or change independently of this package.

You are responsible for protecting keys and credentials, reviewing every transaction and permission, limiting wallet funds and session budgets, evaluating buyer and seller counterparties, securing deployed infrastructure, and paying any resulting network or cloud costs. The managed BNB trial runs in the operator's cloud and receives the runtime material described in Wallet choices; use it only with a testnet wallet or a tightly bounded session.

This package is licensed under Apache-2.0 and provided as is, without warranties or guarantees. The authors and contributors are not responsible for lost funds, compromised credentials, service interruptions, unexpected charges, or other damages arising from its use. Nothing in this package is financial, investment, legal, or tax advice.

CreateOS (NodeOps)

Studio pins deploy 0.6.6 and loads its published Node.js SDK. Configure the agent:

[deploy.nodeops]
mode = "account"
packaging = "zip"
port = 8080
# health_path = "/ping"

Provide CREATEOS_API_KEY through the process environment, then use:

bag deploy prepare --provider nodeops
bag deploy --provider nodeops --yes
bag deploy list --provider nodeops --json
bag deploy status --provider nodeops --json
bag deploy verify --provider nodeops --skip-register
bag deploy logs --provider nodeops
bag deploy destroy --provider nodeops                 # preview
bag deploy destroy --provider nodeops --execute --yes # delete project

Account mode supports ZIP/container deployment, runtime secrets and updates. An unhealthy endpoint makes deploy exit nonzero while preserving .studio/deployments/nodeops.json; inspect logs and retry verification. Wallet runtime variables use settings.runEnvs through the pinned deploy 0.6.6; the pinned SDK 0.6.0 supports BSC nested Permit2 signing with explicit policy opt-in. The Studio bridge now supports bounded approval transactions with an explicit gas budget during authorized payments. Hosting renewal is not yet integrated. bag deploy wallet --json reads Gateway chains and USDC balances without signing or paying. CreateOS uses NodeOps infrastructure; AWS and Azure providers deploy into your own cloud account.

The installed skill includes references/bnbagent-studio-use-createos.md with configuration, capability limits and recovery steps.