@bnbagent/studio-runtime

The TypeScript runtime library behind bnbagent-studio seller agents: configuration, wallet custody, signing policy, audit, ERC-8004 identity, ERC-8183 commerce, x402 or MPP payments over B402, Pieverse credit, deliverable storage, and read-only chain tools.

Most users should not start by programming against this package. Install @bnbagent/studio-cli, run bag skills install, and use /bnbagent-studio in Claude Code or Cursor. The skill designs the workflow; bag init generates the agent; the generated agent imports this runtime.

The runtime is under active development and may introduce breaking changes before 1.0. Start on BSC testnet and pin compatible Studio and SDK versions.

Where it sits

Claude Code / Cursor
        │  /bnbagent-studio
        ▼
@bnbagent/studio-cli (`bag`)       design, scaffold, diagnose, deploy, operate
        │  generates
        ▼
your app/agent source              business value, prompts, faces, fixed signing
        │  imports
        ▼
@bnbagent/studio-runtime           config, custody, policy, commerce, storage, tools
        │  uses
        ▼
@bnbagent/sdk + BNB Chain          protocol and on-chain implementation

The runtime is a deployment dependency; the CLI is not. An emitted agent keeps running if the global CLI is removed. Studio releases the CLI and runtime together so newly generated code and its runtime surface stay aligned.

What the runtime provides

• A consistent studio.toml and workspace-discovery model for local and deployed execution.
• Exactly three wallet backends: encrypted evm-local, Trust Wallet Agent Kit twak, and bounded-session altana.
• Fixed signing policy and spend boundaries for ERC-8183 and x402 operations.
• ERC-8004 registration, resolution, metadata, and service-endpoint reconciliation.
• ERC-8183 quote verification plus buy, submit, fetch, and settle workflows.
• Guarded x402 and native MPP+B402 buyers with host, recipient, asset, network, per-request, retry/dispatch, receipt, and daily-budget checks.
• A protocol-selecting B402 seller with alternative x402 and MPP adapters, settle-before-work paid requests, explicit FREE passthrough, and replay protection.
• Pieverse authentication, model discovery, usage, credit, x402 top-up, and renewal building blocks.
• Local or IPFS deliverable storage and append-only redacted audit events.
• Fifteen read-only tools that can be wrapped for Vercel AI SDK, MCP, or another agent framework.

Install

Recommended: let Studio wire it for you

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

Then ask the installed skill to create or extend a seller:

/bnbagent-studio Create a BNB Chain seller agent named researchagent and help me
choose its commerce rail, service faces, wallet, LLM, storage, and deployment.

bag init writes a compatible runtime and SDK dependency into app/agent/package.json.

Direct library installation

npm install @bnbagent/studio-runtime @bnbagent/sdk

Requirements and package formats:

• Node.js 22 or newer;
• peer dependency @bnbagent/sdk >=0.6.1 <0.7.0 (0.6.1 is the security floor: it carries the SDK bug-bounty fixes the seller gate and wallet flows rely on);
• ESM, CommonJS, and TypeScript declarations for the root and every documented subpath;
• framework-neutral core: no agent framework or web server is imported by this package.

LLM model resolution uses the Vercel AI SDK. Chain access and transaction types use viem and @bnbagent/sdk.

Root API

The root export is intentionally small and matches the conveniences used by generated code:

import {
  findProjectRoot,
  getPolicy,
  getWallet,
  loadStudioToml,
} from "@bnbagent/studio-runtime";

const projectRoot = findProjectRoot();
if (projectRoot === null) {
  throw new Error("studio.toml was not found");
}

const config = loadStudioToml();
const policy = getPolicy();
const wallet = getWallet();

console.log({
  projectRoot,
  project: config.project,
  walletAddress: wallet.address,
  policy,
});

The root also exports Policy and the telemetry emit helper. Import focused APIs from subpaths so dependencies and security boundaries remain visible in your code.

Public subpaths

| Import | Main responsibilities | | --- | --- | | @bnbagent/studio-runtime | Project discovery plus config, policy, telemetry, and wallet conveniences. | | @bnbagent/studio-runtime/config | Find workspace and agent roots, load studio.toml, load local env values, and read the agent registry. | | @bnbagent/studio-runtime/policy | Construct the frozen runtime Policy used by generated code. | | @bnbagent/studio-runtime/secretWrite | Atomically create owner-only secret files. | | @bnbagent/studio-runtime/networks | BSC network and U-token registry, RPC selection, and decimal-string/bigint conversion. | | @bnbagent/studio-runtime/wallet | Build evm-local, twak, or altana wallet providers and apply signing policy. | | @bnbagent/studio-runtime/llm | Resolve Studio LLM configuration to a Vercel AI SDK language model. | | @bnbagent/studio-runtime/storage | Select local development storage or durable IPFS storage for deliverables. | | @bnbagent/studio-runtime/audit | Record, query, tail, and wrap operations in append-only redacted audit events. | | @bnbagent/studio-runtime/erc8004 | Register and resolve identities; update metadata and protocol-specific service endpoints. | | @bnbagent/studio-runtime/erc8183 | Negotiate, verify, buy, inspect, submit, fetch, and settle escrowed jobs. | | @bnbagent/studio-runtime/x402 | Guarded x402 buyer, budget ledger, payment signing, seller policy, B402 seller, and HTTP envelope middleware. | | @bnbagent/studio-runtime/mpp | Native MPP+B402 quote/buy client, merchant trust policy, payment-outcome errors, and EIP-3009-only dispatch. | | @bnbagent/studio-runtime/b402 | Protocol-neutral B402 seller, canonical policy, X402/MPP adapter selection, sell-path resolution, MPP replay-store injection, and HTTP envelope middleware. | | @bnbagent/studio-runtime/pieverse | SIWE/API-key lifecycle, model catalogue, usage, credit allocation, top-up, and auto-renew support. | | @bnbagent/studio-runtime/tools | Fifteen pure read-only wallet, chain, identity, commerce, transaction, block, contract-view, and network tools. |

The generated .d.ts files shipped with the package are the exact symbol and argument reference for every entry point.

Common integrations

Read-only chain tools

The tools module does not expose signing. You can call it directly or wrap selected functions for an LLM framework:

import {
  balanceNative,
  balanceU,
  networkInfo,
  walletAddress,
} from "@bnbagent/studio-runtime/tools";

const address = await walletAddress();
const [native, u, network] = await Promise.all([
  balanceNative(address, "bsc-testnet"),
  balanceU(address, "bsc-testnet"),
  networkInfo("bsc-testnet"),
]);

console.log({ native, u, network });

The complete read-only set is walletInfo, walletList, walletAddress, balanceNative, balanceU, pieverseUsage, agentInfo, agentByAddress, jobStatus, jobList, jobCount, txStatus, blockInfo, contractCallView, and networkInfo.

Guarded x402 buying

The buyer first probes a protected URL, validates the returned payment requirements against policy, signs the bounded payment, and retries the paid request. Configure or trust the merchant before using it; an allowed host is not permission to pay an arbitrary recipient.

The parallel MPP buyer lives at @bnbagent/studio-runtime/mpp. It accepts only native b402.charge challenges, validates a pinned realm and recipient plus Studio-owned B402 token facts, and permits one EIP-3009 paid dispatch. A missing success receipt or lost post-dispatch response is reported as unknown; callers must not retry automatically. P0 requires an evm-local-compatible sign.typed_data wallet.

import { loadStudioToml } from "@bnbagent/studio-runtime/config";
import { getWallet } from "@bnbagent/studio-runtime/wallet";
import {
  fetchWithPayment,
  X402BuyerPolicy,
} from "@bnbagent/studio-runtime/x402";

const policy = X402BuyerPolicy.fromToml(loadStudioToml());
const result = await fetchWithPayment("https://merchant.example/resource", {
  wallet: getWallet(),
  maxUsd: Math.min(0.25, policy.maxPerRequestUsd),
  allowedHosts: [...policy.effectiveAllowedHosts],
});

console.log({
  status: result.statusCode,
  paidUsd: result.paidUsd,
  body: result.json,
});

Use bag x402 trust to pin a merchant domain to its expected payout address and per-call cap. The runtime byte-compares the challenge recipient, constrains the network and asset, applies the tighter of caller and policy caps, and shares the configured daily ledger with other paid calls.

ERC-8183 workflows

The ERC-8183 subpath separates the critical stages rather than exposing a general transaction primitive:

• negotiateWithSeller obtains a seller's signed quote;
• verifySignedJob checks that an on-chain funded job still matches the signed terms and expected seller;
• buyWorkflow performs the buyer-side create, register, budget, and fund sequence;
• submitWorkflow submits the seller's deliverable reference;
• fetchWorkflow retrieves a submitted deliverable;
• settleWorkflow performs the authorized approve, reject, or dispute decision;
• getJobSummary reads the current on-chain state.

Generated seller code keeps quote creation and funded-job verification in src/signing.ts. The LLM implements only the work in src/sellerCore.ts; it does not choose prices, see raw signing methods, or decide whether a job is funded.

ERC-8004 identity

The identity subpath provides register, show, resolve, resolveService, setMetadata, updateEndpoint, and updateServiceEndpoint. The protocol-aware helpers normalize A2A agent-card and MCP streamable endpoints so updating one service does not erase another.

In a generated project, prefer bag deploy verify --provider <bnb|aws> after deployment. It checks provider state and reconciles the live endpoint with ERC-8004. Direct runtime functions are appropriate when you are integrating Studio into another application and own the lifecycle yourself.

Runtime conventions

Project discovery

Generated workspaces keep studio.toml in app/agent/ and sensitive local state in workspace-root .studio/. Discovery walks upward from the current process and understands both locations. Do not move the wallet directory under app/agent/; that directory is the deployable code root.

Configuration and amounts

• Configuration and CLI boundaries use decimal strings so token amounts do not lose precision.
• Payment code converts amounts to bigint internally.
• U used by ERC-8183 has 18 decimals; a B402/x402 test token may use different decimals and is not interchangeable.
• "0" is a deliberate FREE price, not a missing value. ERC-8183 skips token escrow at zero; x402 bypasses B402 entirely at zero.
• RPC overrides are per network. Signing domains, allowed hosts, recipients, assets, contract addresses, and budgets are security configuration, not cosmetic settings.

Wallet material

• evm-local reads an encrypted keystore from workspace-root .studio/wallets/ and unlocks it with WALLET_PASSWORD.
• twak uses a project-dedicated Trust Wallet Agent Kit home and its custody provider.
• altana keeps the admin keystore local and gives the runtime only a bounded session through ALTANA_SESSION.

Local secrets are not part of the deploy artifact. The CLI collects the minimum runtime material and sends it through the selected deployment secret channel. Do not manually bundle .studio/, echo secret values, or put passwords on command lines.

Storage and audit

Local deliverable storage is for development and deliberately fails deploy readiness because it will not survive a remote runtime. IPFS storage is durable and public; configure the pinning service upload endpoint and write key before a real delivery. Audit helpers redact sensitive fields and append operation records, but an audit log is not a substitute for on-chain state verification.

Security boundaries

• One signer: the generated agent is the only wallet holder for its seller runtime.
• No LLM signing: never wrap wallet signing, arbitrary transactions, quote signing, or settlement as an LLM tool.
• Deterministic money paths: price clamps, quote signing, funded-state verification, and x402 settlement belong in fixed code.
• Verify before work: positive-price ERC-8183 work begins only after the funded job matches the signed terms; positive-price x402 work begins only after settlement.
• Fail closed: recipient, host, asset, network, amount, contract, nonce, expiry, retry, and daily-budget checks are authorization boundaries.
• Manual buyer settlement: a submitted ERC-8183 job still requires an authorized approve, reject, or dispute action.
• No generic transaction toolkit: use the bounded workflow APIs and keep the LLM-facing tool surface read-only.

Runtime versus CLI

| Need | Use | | --- | --- | | Create, extend, run, diagnose, or deploy a seller | /bnbagent-studio skill installed by @bnbagent/studio-cli | | Automate a documented lifecycle step | bag CLI | | Implement the generated agent's runtime behavior | @bnbagent/studio-runtime | | Build a custom host or framework integration | Runtime subpath APIs plus @bnbagent/sdk | | Inspect exact command flags | bag --help or bag <command> --help | | Inspect exact TypeScript symbols | The package's shipped declaration files |

Disclaimer

This runtime handles wallet access, signing policy, blockchain transactions, paid requests, and deliverable storage. Its checks reduce specific risks, but they do not make an agent, integration, counterparty, smart contract, model output, storage provider, RPC service, payment facilitator, or deployment platform trustworthy.

If you integrate the runtime directly, you are responsible for preserving its fixed signing boundaries, validating configuration and counterparties, protecting keys and credentials, reviewing transaction and settlement authority, limiting spend, securing infrastructure, and paying any resulting network or cloud costs. Test custom code and contract deployments on BSC testnet before using real funds.

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.