@xona-labs/xpay 0.1.31 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,47 @@ 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.
+
+### Easiest onboarding
+- **Zero-config wallet provisioning.** Drop the MCP server into any agent host
+  with no env — the agent is given its own persistent wallet on first boot
+  (address printed to stderr to fund). Bring-your-own-key and existing profiles
+  still take precedence.
+- **`SKILL.md`** — a framework-agnostic guide so any agent (Claude, Codex,
+  OpenAI, Gemini, custom) can drive xPay's tools, kept current with this release.
+
+### Smart pay routing
+- **Balance-aware network selection.** When a service accepts multiple networks,
+  `use` / `do` pay from the first network whose balance covers the cost (a $0
+  Base wallet falls through to a funded Solana one). When none can cover it, the
+  call fails fast with a clear per-network balance error instead of a raw 402.
+- **Broader x402 compatibility.** The payment payload is sent under both
+  `X-PAYMENT` and `Payment-Signature`, so providers that read the latter
+  (e.g. Nansen) now settle.
+
+### Spending guardrail
+- Surfaced as a first-class feature: per-tx / per-day USD caps, allowed-host
+  list, and an approval threshold, all enforced **before signing**. Two-step
+  confirmation guards MCP transfers.
+
+### Reporting
+- Comprehensive on-chain USDC usage report (daily / weekly / monthly) via
+  OrbitX402 — summary, timeline, top counterparties, and biggest transactions.
+
 ## [0.1.31] – 2026-06-23
 
 ### Fixed

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 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 [Bento intent firewall](#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 10 core tools (incl. Bento firewall controls)
+- ✅ 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

@@ -56,6 +56,12 @@ of a cent to a few cents per call). `xpay_use` / `xpay_do` settle the payment
 and call the service in one round-trip — the agent just receives the result. A
 small platform fee ($0.01 USDC) applies per paid call.
 
+When a service accepts more than one network (e.g. Base **and** Solana), xPay
+**routes automatically to a funded network** — it pays from the first one whose
+balance covers the cost, so a $0 Base wallet falls through to a funded Solana
+one. If no network has the funds, the call fails fast with a clear
+"insufficient balance" message naming each network's balance.
+
 The agent pays from its own wallet, so **it must be funded first**. If a call
 fails for lack of funds, ask the user to send USDC to the address from
 `xpay_balance` (Solana mainnet or Base).
@@ -68,12 +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).** 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 requires 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.
+- **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.1.31",
+  "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",