@bnbagent/studio-cli 0.0.6-alpha.1

package/recipes/runtimes/azure-foundry/code/{{PKG}}/tools.ts.tmpl

@@ -0,0 +1,157 @@
+/**
+ * Read-only chain tools exposed to this agent's LLM (AI SDK `tool` wrap).
+ *
+ * Each entry in `LLM_READ_TOOLS` is a function from
+ * `@bnbagent/studio-runtime/tools` wrapped as a Vercel AI SDK tool. The LLM
+ * may call any tool in this set while producing the deliverable (the
+ * `notify_funded` work step); the `description` is what the LLM sees.
+ *
+ * You own this file — edit `LLM_READ_TOOLS` to control exactly what your
+ * agent can read on-chain. Entries for features your project doesn't use are
+ * commented out by default; uncomment after you've added the dependency to
+ * `studio.toml`.
+ *
+ * **All tools are read-only** by the studio definition: no on-chain state
+ * change, no transferable authority, no transaction signing, no EIP-712
+ * typed-data signing. The agent IS the sole on-chain signer, but ALL of its
+ * signing — quote-sign, submitResult, settle, plus the automatic
+ * budget-gated Pieverse LLM-credit auto-renew inside `buildModel()` — lives
+ * in `signing.ts` / `model.ts` as FIXED entrypoint code and is NEVER a tool
+ * the LLM can invoke. The LLM only produces work text after a job is
+ * verified funded; it can never price, sign, spend, or mutate chain state.
+ * Keep this set read-only.
+ *
+ * (`pieverseUsage` is the one exception in the underlying module: it does a
+ * SIWE EIP-191 personal_sign, domain-locked to llm.pieverse.io, no on-chain
+ * effect. It is commented out below.)
+ */
+
+import * as cr from "@bnbagent/studio-runtime/tools";
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+import { tool, type ToolSet } from "ai";
+import { z } from "zod";
+
+/**
+ * The project-wide default network (`[network].default`) — tool calls that
+ * omit `network` fall back to it, never to a hardcoded name.
+ */
+function defaultNetwork(): string {
+  try {
+    const cfg = loadStudioToml();
+    return String(
+      ((cfg.network ?? {}) as Record<string, unknown>).default ?? "bsc-testnet",
+    );
+  } catch {
+    return "bsc-testnet";
+  }
+}
+
+const networkArg = z
+  .string()
+  .optional()
+  .describe("studio network name (defaults to the project's [network].default)");
+
+export const LLM_READ_TOOLS: ToolSet = {
+  // --- Wallet & chain basics ---
+  wallet_info: tool({
+    description:
+      "Describe the agent's active wallet (address, kind, key location).",
+    inputSchema: z.object({}),
+    execute: async () => cr.walletInfo(),
+  }),
+  balance_native: tool({
+    description:
+      "Native BNB balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional().describe("0x address; omit for own wallet"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceNative(address ?? null, network ?? defaultNetwork()),
+  }),
+  balance_u: tool({
+    // requires [u_token] in studio.toml
+    description:
+      "$U (payment token) balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional().describe("0x address; omit for own wallet"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceU(address ?? null, network ?? defaultNetwork()),
+  }),
+  network_info: tool({
+    description: "Chain id / RPC / token info for a studio network.",
+    inputSchema: z.object({ network: networkArg }),
+    execute: async ({ network }) => cr.networkInfo(network ?? defaultNetwork()),
+  }),
+  tx_status: tool({
+    description: "Status + receipt summary of a transaction hash.",
+    inputSchema: z.object({
+      tx_hash: z.string().describe("0x transaction hash"),
+      network: networkArg,
+    }),
+    execute: async ({ tx_hash, network }) =>
+      cr.txStatus(tx_hash, network ?? defaultNetwork()),
+  }),
+
+  // --- LLM provider ---
+  // pieverse_usage: tool({
+  //   // SIWE personal_sign; requires [llm.provider=pieverse-llm]
+  //   description: "Pieverse LLM usage/credit summary for the last N days.",
+  //   inputSchema: z.object({ days: z.number().int().optional() }),
+  //   execute: async ({ days }) => cr.pieverseUsage(days ?? 7),
+  // }),
+
+  // --- ERC-8004 identity (read-only lookups the LLM may want for context) ---
+  agent_info: tool({
+    // requires [erc8004] in studio.toml
+    description: "ERC-8004 identity record for an agent id.",
+    inputSchema: z.object({
+      agent_id: z.number().int().describe("ERC-8004 agent id"),
+      network: networkArg,
+    }),
+    execute: async ({ agent_id, network }) =>
+      cr.agentInfo(agent_id, network ?? defaultNetwork()),
+  }),
+  agent_by_address: tool({
+    // requires [erc8004] in studio.toml
+    description: "Look up an ERC-8004 agent registration by wallet address.",
+    inputSchema: z.object({
+      address: z.string().describe("0x wallet address"),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.agentByAddress(address, network ?? defaultNetwork()),
+  }),
+
+  // --- ERC-8183 jobs (READ-ONLY status/list — writes live in signing.ts) ---
+  job_status: tool({
+    // requires [erc8183] in studio.toml
+    description: "Read-only ERC-8183 job summary (status, budget, deliverable URL).",
+    inputSchema: z.object({
+      job_id: z.number().int().describe("on-chain job id"),
+      network: networkArg,
+    }),
+    execute: async ({ job_id, network }) =>
+      cr.jobStatus(job_id, network ?? defaultNetwork()),
+  }),
+  job_list: tool({
+    // requires [erc8183] in studio.toml
+    description: "List recent ERC-8183 jobs (optionally only this agent's).",
+    inputSchema: z.object({
+      limit: z.number().int().optional(),
+      mine: z.boolean().optional().describe("only jobs assigned to this agent"),
+      network: networkArg,
+    }),
+    execute: async ({ limit, mine, network }) =>
+      cr.jobList({ limit, mine, network: network ?? defaultNetwork() }),
+  }),
+  // job_count: ...        // network-wide stat — usually noise
+
+  // --- Advanced / footguns (commented by default) ---
+  // contract_call_view: ...  // accepts any ABI — LLM-callable footgun
+  // block_info: ...
+  // wallet_list: ...          // multi-wallet management — dev concern
+  // wallet_address: ...       // alias of wallet_info
+};

package/recipes/runtimes/azure-foundry/recipe.toml

@@ -0,0 +1,88 @@
+[recipe]
+name = "runtimes/azure-foundry"
+description = "Runtime adapter recipe for Azure AI Foundry Hosted Agents — the second deploy target. Selected via `bag init --runtime azure-foundry`. Declares the runtime's required node deps and contributes the cloud-neutral @a2a-js/sdk server for local/dev plus the Foundry deploy host: a pass-through Invocations skill router over the SHARED SellerAgentExecutor.dispatch, serving the documented :8088 + /readiness + /invocations contract. Azure deployment currently supports A2A scaffolds only; the MCP entrypoint remains local/AgentCore-oriented and is rejected before Foundry deploy. The chain tools (tools.ts) + model factory (model.ts) are shared by both protocols (decision D9). Deploys are container-only and fully delegated to the pinned @bnbagent/deploy-cli (SDK/REST + browser login; CustomKeys secret injection; no azd/az CLIs, no azure.yaml/infra in the scaffold)."
+status = "v1"
+
+# The recipe contributes the entrypoints plus the deps below; the deploy
+# spec is generated per-invocation by `bag deploy --provider azure` and handed to the
+# pinned bnbagent-deploy (all cloud execution is delegated — there is no
+# azd bootstrap and no azure.yaml / infra/ in the scaffold).
+#
+# foundryMain.ts implements the documented framework-neutral container
+# contract directly: plain HTTP on :8088, GET /readiness, and the declared
+# POST /invocations pass-through route. This path was live E2E verified on
+# 2026-07-20 through deploy, cold-start smoke, invoke, logs, and destroy.
+
+# Base deps are shared by every mode. bnbagent-deploy injects provider/storage
+# keys and wallet material through a Foundry CustomKeys connection before the
+# process starts, so the agent needs no Azure credential or Key Vault SDK.
+[dependencies]
+node = [
+    "@bnbagent/studio-runtime",
+    "@bnbagent/sdk@0.5.0-alpha.1",
+    # The LLM work hook (generateText + tools) and the model factory; the
+    # Foundry host's OpenAI-compatible client comes from @ai-sdk/openai
+    # (built from the BNBAGENT_LLM_* env the deploy injects).
+    "ai@^7.0.29",
+    "@ai-sdk/openai@^4.0.15",
+    # Tool input schemas (AI SDK tools + MCP registerTool).
+    "zod@^3.25.0",
+    # Every entrypoint serves over express (the @a2a-js/sdk server
+    # integration, the MCP streamable-HTTP wiring, and the Invocations host).
+    "express@^5.1.0",
+]
+
+# A2A protocol surface (main.ts): the CLOUD-NEUTRAL serving stack — the
+# official @a2a-js/sdk express app, NOT AWS's wrapper, so an azure-foundry
+# seller carries no AWS serving dependency (commitments #4/#5). MUST be <1.0:
+# 1.0.0-beta reshapes the server surface; 0.3.14 is the spike-verified line
+# (EX-3).
+[dependencies.a2a]
+node = [
+    "@a2a-js/sdk@>=0.3.14 <1.0",
+]
+
+# MCP protocol surface (mcpMain.ts): the official MCP TS SDK.
+[dependencies.mcp]
+node = [
+    "@modelcontextprotocol/sdk@^1.29.0",
+]
+
+# Modes are the protocol × deploy cross-product `bag init` selects (mode=
+# "{a2a|mcp}-{codezip|container}"), mirroring runtimes/agentcore:
+#   protocol — a2a: main.ts (neutral @a2a-js serving) + executor.ts +
+#              agentCard.ts + foundryMain.ts (the Foundry deploy host — it
+#              imports executor.ts, so it rides the a2a modes. Azure deploy
+#              rejects MCP because Foundry's declared invocations endpoint is
+#              not the native streamable-HTTP /mcp transport.)
+#              mcp: mcpMain.ts (streamable-HTTP /mcp; negotiate +
+#              notify_funded sync-delivery)
+#   deploy   — container (the azure-foundry deploy shape): bnbagent-deploy's
+#                         azure provider rejects Node zip, so every
+#                         azure-foundry deploy builds this Dockerfile
+#                         LOCALLY with Docker (linux/amd64) and pushes it to
+#                         the auto-provisioned ACR (a twak wallet
+#                         additionally needs the twak CLI inside the image).
+#                         The container modes add {{PKG}}/Dockerfile +
+#                         {{PKG}}/.dockerignore.
+#              codezip   (historical): Foundry CodeZip source modes — never
+#                         selected by `bag init` for azure-foundry today
+#                         (kept for mode-shape parity with
+#                         runtimes/agentcore); they ship no Dockerfile.
+# tools.ts + model.ts are unlisted → SHARED, always emitted. signing.ts +
+# the read-only tools live in the `agent` / tools recipes (emitted in all
+# modes).
+[modes]
+default = "a2a-codezip"
+
+[modes.a2a-codezip]
+files = ["{{PKG}}/main.ts", "{{PKG}}/executor.ts", "{{PKG}}/agentCard.ts", "{{PKG}}/foundryMain.ts"]
+
+[modes.a2a-container]
+files = ["{{PKG}}/main.ts", "{{PKG}}/executor.ts", "{{PKG}}/agentCard.ts", "{{PKG}}/foundryMain.ts", "{{PKG}}/Dockerfile", "{{PKG}}/.dockerignore"]
+
+[modes.mcp-codezip]
+files = ["{{PKG}}/mcpMain.ts"]
+
+[modes.mcp-container]
+files = ["{{PKG}}/mcpMain.ts", "{{PKG}}/Dockerfile", "{{PKG}}/.dockerignore"]

package/recipes/tools-chain/code/{{PKG}}/chainTools.ts.tmpl

@@ -0,0 +1,166 @@
+/**
+ * Chain read-only tools exposed to this agent's LLM (AI SDK `tool` wrap).
+ *
+ * The full 15-tool read-only inventory from
+ * `@bnbagent/studio-runtime/tools`, re-exported as plain functions (for
+ * fixed-code use) AND wrapped as AI SDK tools in `CHAIN_READ_TOOLS` (for the
+ * LLM). Each tool's `description` is what the LLM sees. The curated set in
+ * `LLM_READ_TOOLS` (runtime recipe `tools.ts`) is the recommended default —
+ * this file is for agents that want the whole inventory or a custom cut.
+ *
+ * You own this file — edit `CHAIN_READ_TOOLS` to control exactly what your
+ * agent can read on-chain. Footgun entries are commented out by default;
+ * uncomment deliberately.
+ *
+ * All tools are **read-only** by the studio definition: no on-chain state
+ * change, no transferable authority. The only signing that happens is
+ * `pieverse_usage`'s SIWE personal_sign (domain-locked to llm.pieverse.io,
+ * no on-chain effect). See the `@bnbagent/studio-runtime/tools` module
+ * docstring for the full chain read-only LLM-tools decision.
+ */
+
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+import * as cr from "@bnbagent/studio-runtime/tools";
+import { tool, type ToolSet } from "ai";
+import { z } from "zod";
+
+// Plain functions — call these from fixed code (no LLM in the loop).
+export const {
+  agentByAddress,
+  agentInfo,
+  balanceNative,
+  balanceU,
+  blockInfo,
+  contractCallView,
+  jobCount,
+  jobList,
+  jobStatus,
+  networkInfo,
+  pieverseUsage,
+  txStatus,
+  walletAddress,
+  walletInfo,
+  walletList,
+} = cr;
+
+/**
+ * The project-wide default network (`[network].default`) — tool calls that
+ * omit `network` fall back to it, never to a hardcoded name.
+ */
+function defaultNetwork(): string {
+  try {
+    const cfg = loadStudioToml();
+    return String(
+      ((cfg.network ?? {}) as Record<string, unknown>).default ?? "bsc-testnet",
+    );
+  } catch {
+    return "bsc-testnet";
+  }
+}
+
+const networkArg = z
+  .string()
+  .optional()
+  .describe("studio network name (defaults to the project's [network].default)");
+
+export const CHAIN_READ_TOOLS: ToolSet = {
+  // --- Wallet & chain basics ---
+  wallet_info: tool({
+    description:
+      "Describe the agent's active wallet (address, kind, key location).",
+    inputSchema: z.object({}),
+    execute: async () => cr.walletInfo(),
+  }),
+  wallet_list: tool({
+    description: "List all local wallet addresses.",
+    inputSchema: z.object({}),
+    execute: async () => cr.walletList(),
+  }),
+  wallet_address: tool({
+    description: "The active wallet address.",
+    inputSchema: z.object({}),
+    execute: async () => ({ address: await cr.walletAddress() }),
+  }),
+  balance_native: tool({
+    description:
+      "Native BNB balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional(),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceNative(address ?? null, network ?? defaultNetwork()),
+  }),
+  balance_u: tool({
+    // requires [u_token] in studio.toml
+    description:
+      "$U (payment token) balance of an address (defaults to the agent's own wallet).",
+    inputSchema: z.object({
+      address: z.string().optional(),
+      network: networkArg,
+    }),
+    execute: async ({ address, network }) =>
+      cr.balanceU(address ?? null, network ?? defaultNetwork()),
+  }),
+  network_info: tool({
+    description: "Chain id / RPC / token info for a studio network.",
+    inputSchema: z.object({ network: networkArg }),
+    execute: async ({ network }) => cr.networkInfo(network ?? defaultNetwork()),
+  }),
+  tx_status: tool({
+    description: "Status + receipt summary of a transaction hash.",
+    inputSchema: z.object({ tx_hash: z.string(), network: networkArg }),
+    execute: async ({ tx_hash, network }) =>
+      cr.txStatus(tx_hash, network ?? defaultNetwork()),
+  }),
+
+  // --- LLM provider ---
+  // pieverse_usage: tool({
+  //   // SIWE personal_sign; requires [llm.provider=pieverse-llm]
+  //   description: "Pieverse LLM usage/credit summary for the last N days.",
+  //   inputSchema: z.object({ days: z.number().int().optional() }),
+  //   execute: async ({ days }) => cr.pieverseUsage(days ?? 7),
+  // }),
+
+  // --- ERC-8004 identity ---
+  agent_info: tool({
+    // requires [erc8004] in studio.toml
+    description: "ERC-8004 identity record for an agent id.",
+    inputSchema: z.object({ agent_id: z.number().int(), network: networkArg }),
+    execute: async ({ agent_id, network }) =>
+      cr.agentInfo(agent_id, network ?? defaultNetwork()),
+  }),
+  agent_by_address: tool({
+    // requires [erc8004] in studio.toml
+    description: "Look up an ERC-8004 agent registration by wallet address.",
+    inputSchema: z.object({ address: z.string(), network: networkArg }),
+    execute: async ({ address, network }) =>
+      cr.agentByAddress(address, network ?? defaultNetwork()),
+  }),
+
+  // --- ERC-8183 jobs ---
+  job_status: tool({
+    // requires [erc8183] in studio.toml
+    description:
+      "Read-only ERC-8183 job summary (status, budget, deliverable URL).",
+    inputSchema: z.object({ job_id: z.number().int(), network: networkArg }),
+    execute: async ({ job_id, network }) =>
+      cr.jobStatus(job_id, network ?? defaultNetwork()),
+  }),
+  job_list: tool({
+    // requires [erc8183] in studio.toml
+    description: "List recent ERC-8183 jobs (optionally only this agent's).",
+    inputSchema: z.object({
+      limit: z.number().int().optional(),
+      mine: z.boolean().optional(),
+      network: networkArg,
+    }),
+    execute: async ({ limit, mine, network }) =>
+      cr.jobList({ limit, mine, network: network ?? defaultNetwork() }),
+  }),
+  // job_count: ...        // network-wide stat — usually noise
+
+  // --- Advanced / footguns (commented by default) ---
+  // contract_call_view: ...  // accepts any ABI — LLM-callable footgun
+  // block_info: ...
+};

package/recipes/tools-chain/recipe.toml

@@ -0,0 +1,11 @@
+[recipe]
+name = "tools-chain"
+description = "Read-only chain tools from @bnbagent/studio-runtime/tools, exposed as plain functions plus AI SDK tool definitions the LLM can call (framework-neutral by decision D9)."
+status = "v0.0.1"
+
+[dependencies]
+node = [
+    "@bnbagent/studio-runtime",
+    "ai@^7.0.29",   # AI SDK `tool` wrappers
+    "zod@^3.25.0",  # tool input schemas
+]

package/recipes/wallet/recipe.toml

@@ -0,0 +1,20 @@
+[recipe]
+name = "wallet"
+description = "Configures the agent's wallet: 'evm-local' (default encrypted keystore), 'twak' (Trust Wallet Agent Kit CLI), or 'altana' (encrypted admin keystore plus one bounded runtime session)."
+
+[dependencies]
+node = ["@bnbagent/studio-runtime"]
+
+[dependencies.altana]
+node = ["@altananetwork/sdk@0.5.1"]
+
+[env]
+# kind='twak': the twak CLI reads the unlock password from the environment —
+# it never goes on a command line.
+TWAK_WALLET_PASSWORD = "unlocks ~/.twak/wallet.json (twak kind); set in .studio/.env.local"
+# kind='evm-local' (the `bag init` default) or kind='altana' admin operations:
+WALLET_PASSWORD = "set to a strong password (>= 12 chars); encrypts .studio/wallets/<addr>.json (runtime never receives it for altana)"
+
+[install]
+# Secrets (keystore + .env.local) all live under the workspace-root .studio/.
+gitignore = [".studio/"]

package/recipes/x402-buyer/code/{{PKG}}/x402Buyer.ts.tmpl

@@ -0,0 +1,175 @@
+/**
+ * x402 micropay buyer tools — emitted by `bag recipe code x402-buyer`.
+ *
+ * The agent's LLM can buy from any x402-protected URL whose host is on the
+ * effective allowlist: `[payments.x402].allowed_hosts` plus every merchant
+ * trusted via `bag x402 trust` (`[payments.x402.merchants.*]` — e.g. the
+ * Binance Bazaar shelf: CMC market data).
+ *
+ * Wire into the agent (main.ts / mcpMain.ts) — signing stays fixed code,
+ * these tools only *fetch with payment* inside the config fences:
+ *
+ *     import { X402_BUYER_TOOLS } from "./x402Buyer.js";
+ *     ...
+ *     tools: { ...LLM_READ_TOOLS, ...X402_BUYER_TOOLS },
+ *
+ * (This file sits NEXT TO tools.ts on purpose so the emitted agent package
+ * stays a flat module set.)
+ *
+ * Security spine (all enforced in @bnbagent/studio-runtime, not here):
+ *   - recipient: the pinned merchant `pay_to` (or `expected_recipient`) is
+ *     byte-compared against the 402's payTo — a tampered 402 can never
+ *     redirect funds;
+ *   - per-call cap: `merchants.<name>.per_call_cap_usd` clamps every payment
+ *     regardless of the `max_usd` argument below (the LLM can tighten it,
+ *     never widen);
+ *   - daily cap: `[budget].max_per_day_usd` across all paid calls.
+ *
+ * You own this file; edit freely.
+ */
+
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+import { getWallet } from "@bnbagent/studio-runtime/wallet";
+import {
+  fetchWithPayment,
+  quoteUrl,
+  X402BuyerPolicy,
+  X402Error,
+} from "@bnbagent/studio-runtime/x402";
+import { tool, type ToolSet } from "ai";
+import { z } from "zod";
+
+function policy(): X402BuyerPolicy {
+  return X402BuyerPolicy.fromToml(loadStudioToml());
+}
+
+/**
+ * Pay an x402-protected endpoint and return its response.
+ *
+ * NO API KEY IS REQUIRED. x402 merchants (CoinMarketCap x402 endpoints,
+ * Binance Bazaar merchants, etc.) authenticate the caller by the on-chain
+ * EIP-3009 payment signed with the agent's own wallet — there is NO
+ * `Authorization` / `X-API-KEY` header. If a task needs data from a URL on
+ * the allowlist (CMC prices, etc.), ALWAYS use this tool; never ask the user
+ * for an API key and never answer that the task can't be done for lack of
+ * one. Payment is fenced by studio.toml (merchant.per_call_cap_usd +
+ * [budget].max_per_day_usd), so calling it is always safe.
+ *
+ * URL host must be on the effective allowlist (allowed_hosts + trusted
+ * merchants). `maxUsd` is only a refusal threshold — the actual price comes
+ * from the endpoint's 402 challenge, and the config's per-call / daily caps
+ * still apply on top. Query-style endpoints (e.g. CMC) take GET with params
+ * in the URL; RPC-style ones take POST.
+ */
+export async function buyWithX402(
+  url: string,
+  maxUsd: number,
+  method = "GET",
+): Promise<Record<string, unknown>> {
+  const pol = policy();
+  try {
+    const result = await fetchWithPayment(url, {
+      maxUsd: Math.min(maxUsd, pol.maxPerRequestUsd),
+      wallet: getWallet(),
+      method,
+      allowedHosts: [...pol.effectiveAllowedHosts],
+    });
+    return {
+      ok: true,
+      status: result.statusCode,
+      json: result.json,
+      paid_usd: result.paidUsd,
+    };
+  } catch (exc) {
+    if (exc instanceof X402Error) {
+      return { ok: false, error: exc.constructor.name, message: exc.message };
+    }
+    throw exc;
+  }
+}
+
+/** Probe an x402 endpoint without paying — returns its 402 body for inspection. */
+export async function quoteX402(
+  url: string,
+  method = "GET",
+): Promise<Record<string, unknown>> {
+  try {
+    return {
+      ok: true,
+      accepts: await quoteUrl(url, {
+        method,
+        allowedHosts: [...policy().effectiveAllowedHosts],
+      }),
+    };
+  } catch (exc) {
+    if (exc instanceof X402Error) {
+      return { ok: false, error: exc.constructor.name, message: exc.message };
+    }
+    throw exc;
+  }
+}
+
+/** The AI SDK tool set — spread into the agent's `tools:` map. */
+export const X402_BUYER_TOOLS: ToolSet = {
+  buy_with_x402: tool({
+    description:
+      "Pay an x402-protected endpoint with the agent's own wallet (EIP-3009; " +
+      "NO API key) and return its JSON response. Use it whenever a task needs " +
+      "data from an allowlisted paid endpoint (e.g. CoinMarketCap market " +
+      "data). max_usd is a refusal threshold; studio.toml per-call/daily caps " +
+      "always apply on top.",
+    inputSchema: z.object({
+      url: z.string().describe("the full x402-protected URL (query params inline)"),
+      max_usd: z.number().describe("refuse if the 402 price exceeds this (USD)"),
+      method: z.string().optional().describe("HTTP verb; default GET"),
+    }),
+    execute: async ({ url, max_usd, method }) =>
+      buyWithX402(url, max_usd, method ?? "GET"),
+  }),
+  quote_x402: tool({
+    description:
+      "Probe an x402 endpoint WITHOUT paying — returns the 402 challenge body " +
+      "(price, payTo, asset) for inspection.",
+    inputSchema: z.object({
+      url: z.string(),
+      method: z.string().optional().describe("HTTP verb; default GET"),
+    }),
+    execute: async ({ url, method }) => quoteX402(url, method ?? "GET"),
+  }),
+};
+
+// ── Deterministic pre-fetch (recommended for a purpose-built seller) ──────────
+// The tools above let the LLM *decide* to buy — fine for an agent that buys
+// ad hoc from many sources. But if your seller ALWAYS needs the same paid
+// data (e.g. it exists to report CMC prices), do NOT lean on the LLM to
+// choose to call `buy_with_x402`: small models (gpt-4o-mini, haiku)
+// routinely skip it and either excuse themselves ("missing API key") or
+// answer from stale training priors — no amount of prompt wording reliably
+// fixes this. Fetch in FIXED code, then hand the LLM the data to write up.
+// This mirrors commitment #3: the money action is deterministic; the LLM
+// only produces text.
+//
+// In `sellerCore.ts` `doWorkAndSubmit` (you own that file) — or the
+// azure-foundry `executor.ts` equivalent — replace the generic prompt with a
+// pre-fetch:
+//
+//     import { buyWithX402 } from "./x402Buyer.js";
+//
+//     const paid = await buyWithX402(
+//       "https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest" +
+//         "?symbol=BNB&convert=USD",
+//       0.02,
+//     );
+//     if (!paid.ok) {
+//       throw new Error(`x402 fetch failed: ${paid.message}`);
+//     }
+//     const prompt =
+//       "You accepted and were paid for this job. The live data below was " +
+//       "already fetched and paid for on your behalf — use it verbatim; do " +
+//       "NOT claim you need an API key.\n\n" +
+//       `JOB CONTEXT:\n${task}\n\nFETCHED DATA (x402, paid $${paid.paid_usd}):\n` +
+//       JSON.stringify(paid.json);
+//     const work = await this.runWork(prompt, { sessionId: String(jobId) });
+//
+// Keep `buy_with_x402` in the LLM toolset too if some jobs need ad-hoc buys
+// the LLM must decide — the deterministic pre-fetch and the tool compose.

package/recipes/x402-buyer/recipe.toml

@@ -0,0 +1,15 @@
+[recipe]
+name = "x402-buyer"
+description = "x402 micropay buyer tool set for the agent's LLM (allowed_hosts + merchants trusted via `bag x402 trust`, e.g. CMC market data from the Binance Bazaar)."
+status = "v0.0.x"
+
+[dependencies]
+node = [
+    "@bnbagent/studio-runtime",
+    "@bnbagent/sdk@0.5.0-alpha.1",
+    "ai@^7.0.29",   # AI SDK `tool` wrappers around the buyer functions
+    "zod@^3.25.0",  # tool input schemas
+]
+
+[env]
+WALLET_PASSWORD = "wallet keystore password (used to sign EIP-3009 transfers)"