@xona-labs/xpay 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,17 @@ versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.1] – 2026-06-24
+
+### Docs
+- **Documented the Bento intent firewall as an optional security layer.** README
+  gains a "Security" section (enable / status / disable, no API key, one-time
+  on-chain wallet registration, and the ALLOW / BLOCKED / ESCALATED verdicts),
+  the MCP tool list re-includes `xpay_bento_status` / `xpay_bento_enable` /
+  `xpay_bento_disable`, and SKILL.md re-adds the tools plus a safety note. No
+  code change — the firewall shipped in 0.1.28; this release publishes the docs
+  to npm.
+
 ## [0.2.0] – 2026-06-23
 
 Milestone release consolidating the 0.1.24–0.1.31 line into four themes.

package/README.md

@@ -1,5 +1,10 @@
 # @xona-labs/xpay
 
+[![npm](https://img.shields.io/npm/v/@xona-labs/xpay)](https://www.npmjs.com/package/@xona-labs/xpay)
+[![downloads](https://img.shields.io/npm/dm/@xona-labs/xpay)](https://www.npmjs.com/package/@xona-labs/xpay)
+[![license](https://img.shields.io/npm/l/@xona-labs/xpay)](https://github.com/xona-labs/xpay/blob/main/LICENSE)
+![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+
 > **Agentic-commerce wallet.** Multi-network USDC wallet, x402 payments, and discovery across 20,000+ services — as a CLI, an SDK, and an MCP server.
 
 ```bash
@@ -155,7 +160,7 @@ That's the whole setup. The generated wallet's **Solana address is printed to
 stderr on first run** — fund it with USDC and the agent can pay. It persists
 under `~/.xpay` and is reused on every later boot, so the address is stable.
 
-The host sees seven core tools: `xpay_discover`, `xpay_use`, `xpay_do`, `xpay_transfer`, `xpay_balance`, `xpay_report`, `xpay_guardrail`. If you've linked a Sana key (see below), eight additional `sana_*` tools are also registered automatically.
+The host sees the core tools: `xpay_discover`, `xpay_use`, `xpay_do`, `xpay_transfer`, `xpay_balance`, `xpay_report`, `xpay_guardrail`, plus `xpay_bento_status` / `xpay_bento_enable` / `xpay_bento_disable` to manage the [intent firewall](#security--bento-intent-firewall-optional). If you've linked a Sana key (see below), eight additional `sana_*` tools are also registered automatically.
 
 **Bring your own wallet instead** — the wallet source order is *existing profile → key env → auto-generate*, so any of these overrides the generated wallet:
 
@@ -221,6 +226,8 @@ xpay guardrail set \
   --allowed-hosts 'api.payai.network,*.xona-agent.com'
 ```
 
+- **`maxPerTx` / `maxPerDay`** — apply to every paid call *and* direct transfers.
+- **`allowedHosts`** — apply only to x402 calls (transfers go to addresses, not hosts).
 - **`maxPerTx` / `maxPerDay`** — apply to every paid call *and* direct transfers.
 - **`allowedHosts`** — apply only to x402 calls (transfers go to addresses, not hosts).
 - **`requireApprovalAbove`** — calls ≥ threshold need explicit approval. In the CLI this is a
@@ -229,6 +236,34 @@ xpay guardrail set \
   surfaces as a system dialog you physically approve. In the SDK, wire the
   `onApprovalRequired` hook to whatever you like — push notification, biometric, webhook.
 
+## Security — Bento intent firewall (optional)
+
+Spend caps stop an agent spending *too much* — they can't tell a legitimate payment from a
+prompt-injected one. The optional [Bento](https://app.bentoguard.xyz/) layer adds an **AI intent
+firewall**: every paid call and transfer is screened for malicious intent (prompt-injection,
+wallet-drain, intent-vs-execution mismatch) *before signing*. It runs inside the guardrail, right
+after the local caps pass.
+
+```bash
+xpay bento enable      # prints the agent wallet address to register
+xpay bento status      # whether screening is active
+xpay bento disable     # turn off — falls back to local caps only
+```
+
+There's **no API key** — Bento authenticates with the wallet's own key. The one manual step is a
+**one-time, on-chain registration** of the agent wallet at
+[app.bentoguard.xyz](https://app.bentoguard.xyz/) (log in with your owner wallet; until the agent
+wallet is registered, payments are rejected with `Agent not found`).
+
+Each screened call returns a verdict:
+
+- **`ALLOW`** — cleared; xPay signs as normal.
+- **`BLOCKED`** — flagged as a critical threat; xPay throws before signing, no funds move.
+- **`ESCALATED`** — ambiguous; xPay defers to your `onApprovalRequired` hook, or fails closed.
+
+Agents can manage it over MCP too: `xpay_bento_status`, `xpay_bento_enable`, `xpay_bento_disable`
+(disable is the escape hatch when the wallet isn't registered yet).
+
 ## Sana agent wallet card (optional)
 
 xPay supports an optional integration with [Sana](https://sana.bot) — an agent-native card that lets your AI spend at the point of sale, anywhere Visa is accepted.
@@ -314,7 +349,7 @@ Public RPCs work for development but rate-limit hard. Production deployments sho
 **v0.1 (current):**
 - ✅ CLI: init, accounts, balance, discover, pay, transfer, report, guardrail, mcp
 - ✅ SDK: full parity with CLI; tool exporters for Claude / OpenAI / Gemini
-- ✅ MCP server on stdio with 7 core tools
+- ✅ MCP server on stdio with 10 tools (incl. the Bento intent firewall)
 - ✅ Solana + Base mainnet with disk caching
 - ✅ Optional Sana agent card integration (`xpay sana link`) — 8 additional `sana_*` tools
 

package/SKILL.md

@@ -45,6 +45,9 @@ the MCP `env`. To require an explicit wallet (no auto-generation), set
 | `xpay_balance` | The wallet's balance per network, plus its addresses (use this to tell the user where to send funds). |
 | `xpay_report` | Spending/income report (daily / weekly / monthly). |
 | `xpay_guardrail` | Read the active spending caps (per-tx, per-day, allowed hosts, approval threshold). |
+| `xpay_bento_status` | Check whether the Bento intent firewall is on (read-only). |
+| `xpay_bento_enable` | Turn the Bento intent firewall on. Returns the agent wallet address to register at app.bentoguard.xyz. |
+| `xpay_bento_disable` | Turn the Bento firewall off — use if the wallet isn't registered and payments are rejected. |
 
 ## How payment works
 
@@ -71,6 +74,12 @@ fails for lack of funds, ask the user to send USDC to the address from
 - **Transfers need confirmation.** `xpay_transfer` only *stages* a transfer; it
   returns a code. Show the user the amount + destination and only call
   `xpay_transfer_confirm` after they approve. Never move funds unprompted.
+- **Bento intent firewall (optional security layer).** When enabled, every
+  payment is screened for malicious intent (prompt-injection, wallet-drain)
+  before signing. A `BLOCKED` result means stop. Toggle with
+  `xpay_bento_enable` / `xpay_bento_disable`; it needs a one-time wallet
+  registration at app.bentoguard.xyz, and until then payments are rejected —
+  disable it to fall back to local caps if you don't want to register.
 
 ## Recipes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xona-labs/xpay",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Discovery and usage layer for agentic commerce — multi-network wallet, x402 payments, 20k+ services via PayAI and other catalogs",
   "type": "module",
   "main": "dist/index.js",