@xona-labs/xpay 0.2.23 → 0.2.25

package/README.md

@@ -1,4 +1,6 @@
-# @xona-labs/xpay
+# Xona Wallet
+
+> Ships as the npm package `@xona-labs/xpay`, the `xpay` CLI, and the `xpay_*` MCP tools. The package and command names are unchanged.
 
 [![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)
@@ -6,7 +8,7 @@
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.xona--labs%2Fxpay-6e56cf)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.xona-labs/xpay)
 ![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
 
-> **Agentic-commerce wallet.** Multi-network USDC wallet, x402 payments, AgenC marketplace hires, and discovery across 20,000+ services — as a CLI, an SDK, and an MCP server.
+> **Agentic-commerce wallet.** Multi-network USDC wallet, x402 payments, AgenC marketplace hires, and discovery across 20,000+ services - as a CLI, an SDK, and an MCP server.
 
 ```bash
 npm install -g @xona-labs/xpay
@@ -22,13 +24,13 @@ xpay report                                # daily / weekly / monthly report via
 ```
 
 ```ts
-// SDK — same primitives, programmatic
+// SDK - same primitives, programmatic
 import { loadProfile, createXPay } from "@xona-labs/xpay";
 const xpay = createXPay({ profile: await loadProfile({ passphrase }) });
 const result = await xpay.do("translate this PDF to Japanese", { body: { file } });
 ```
 
-xPay is the **wallet** and **rail** layer for agentic commerce. It hides x402, USDC, RPC, and multi-network routing behind a flat surface so agent builders (Claude / Codex / OpenAI / Gemini / your own) can find and pay for services without writing payment plumbing.
+Xona Wallet is the **wallet** and **rail** layer for agentic commerce. It hides x402, USDC, RPC, and multi-network routing behind a flat surface so agent builders (Claude / Codex / OpenAI / Gemini / your own) can find and pay for services without writing payment plumbing.
 
 ---
 
@@ -46,7 +48,7 @@ xpay init
 # ✔ Profile "default" created at /Users/you/.xpay/default
 # Solana  7RB7frdxPc9vZtuyq6YfNoWTJcDZsE2AcXXV6qkpf5ph
 # EVM     0xA5D93CDB2bD16b2d1d3d19D45dad3FaBb1023dfa
-# ⚠ RECOVERY PHRASE — write this down NOW. We cannot recover it for you.
+# ⚠ RECOVERY PHRASE - write this down NOW. We cannot recover it for you.
 #   1. depend   2. guess    3. mercy    4. online
 #   ... (24 words)
 ```
@@ -65,23 +67,23 @@ xpay pay https://orbisapi.com/proxy/image-alt-text-generator-api-1c9472
 |---|---|
 | `xpay init [name]` | Create a profile (Solana + EVM keys from one BIP-39 seed). `--import` to restore from a phrase, `--no-encrypt` for dev wallets, `--workspace` to store locally. |
 | `xpay accounts list \| show \| use` | List profiles, inspect one, or set the active profile. |
-| `xpay balance` | USDC balance per network for the active profile. |
-| `xpay discover [query]` | Search 21k+ x402 services across chains — Solana, Base, **BNB Chain**, and other EVM networks — plus **AgenC marketplace** agent listings (cached on disk). `--network`, `--limit`, `--json`. |
+| `xpay balance` | Token balances per network for the active profile, plus a stablecoin total. Covers Solana, Base and other EVM chains, Robinhood Chain, and [Stable](#stable-chain). `--network`. |
+| `xpay discover [query]` | Search 21k+ x402 services across chains (Solana, Base, **BNB Chain**, and other EVM networks), plus **AgenC marketplace** agent listings (cached on disk). `--network`, `--limit`, `--json`. |
 | `xpay pay <url>` | Pay an x402 endpoint. Works on catalog URLs and any URL that returns 402. `--max-usd`, `--body`, `-y`. |
-| `xpay agenc hire <listingPda>` | Hire an [AgenC marketplace](#agenc-marketplace-hire-on-chain-agents) listing — escrows its SOL price on-chain; the provider works asynchronously. `--max-usd`, `--review-window`, `-y`. |
+| `xpay agenc hire <listingPda>` | Hire an [AgenC marketplace](#agenc-marketplace-hire-on-chain-agents) listing - escrows its SOL price on-chain; the provider works asynchronously. `--max-usd`, `--review-window`, `-y`. |
 | `xpay agenc status <taskPda>` | Check a hire's progress (read-only, no wallet). `--json`. |
-| `xpay token find <query>` | Find a Solana token by ticker, name, or mint address (Jupiter) — price, mcap, liquidity, verification. Read-only. `--limit`, `--json`. |
+| `xpay token find <query>` | Find a Solana token by ticker, name, or mint address (Jupiter) - price, mcap, liquidity, verification. Read-only. `--limit`, `--json`. |
 | `xpay token rwa [query]` | List tradable [RWA tokens](#rwa-discovery-solana) on Solana: tokenized stocks/ETFs (xStocks, Ondo, Remora) + USDY. Read-only. `--category`, `--limit`, `--json`. |
 | `xpay swap <amount> <from> <to>` | Swap tokens in your wallet via Jupiter (Solana only), subject to the guardrail. `--slippage-bps`, `-y`. |
 | `xpay trade <amount> <from> <to>` | Trade tokens on [Robinhood Chain](#robinhood-chain-trading) via Uniswap V3 / NOXA Fun (ETH↔token), subject to the guardrail. `--slippage-bps`, `--quote-only`, `-y`. |
 | `xpay trending` | List tokens trending on Robinhood Chain (read-only, no wallet). `--new`, `--limit`. |
-| `xpay x user \| posts <handle>` | Realtime X (Twitter) account data — profile (~$0.01) or recent posts (~$0.06), paid via x402 at cost. No X account needed. |
-| `xpay zauth reposcan <repoUrl>` | Repository security scan via partner [zauth](#zauth-repo-security-scans) — zauth score + provenance/vulnerability report (~$0.05 USDC via x402). `--json`, `-y`. |
+| `xpay x user \| posts <handle>` | Realtime X (Twitter) account data - profile (~$0.01) or recent posts (~$0.06), paid via x402 at cost. No X account needed. |
+| `xpay zauth reposcan <repoUrl>` | Repository security scan via partner [zauth](#zauth-repo-security-scans) - zauth score + provenance/vulnerability report (~$0.05 USDC via x402). `--json`, `-y`. |
 | `xpay zauth status <sessionToken>` | Check a running zauth scan (free, read-only, no wallet). `--json`. |
 | `xpay shop search "<query>"` | [Product discovery](#xona-shop-product-discovery) across Google Shopping, Amazon, and eBay from one query (~$0.02 USDC via x402, less for fewer marketplaces). `--marketplaces`, `--price-min/max`, `--condition`, `--sort`, `--json`, `-y`. |
 | `xpay shop quote "<query>"` | Free preflight: exact search price + how the query parses (no wallet). `--json`. |
-| `xpay transfer <amount> USDC <to>` | Direct USDC transfer, subject to the guardrail. `--network`, `-y`. |
-| `xpay report` | Comprehensive USDC activity report — totals, net flow, timeline, top counterparties, biggest txs. `--period daily\|weekly\|monthly`, `--network`, `--json`. |
+| `xpay transfer <amount> USDC <to>` | Direct stablecoin transfer (USDC, or USDT0 on [Stable](#stable-chain)), subject to the guardrail. `--network`, `-y`. |
+| `xpay report` | Comprehensive USDC activity report - totals, net flow, timeline, top counterparties, biggest txs. `--period daily\|weekly\|monthly`, `--network`, `--json`. |
 | `xpay guardrail show \| set \| clear` | Inspect or edit spending caps and allowed hosts. |
 | `xpay biometric status \| enable \| disable` | Touch ID unlock for the wallet passphrase (macOS). |
 | `xpay sana link \| unlink \| status` | Link a Sana API key to activate the agent card (optional). |
@@ -91,7 +93,7 @@ All commands run from a single profile. Switch with `xpay accounts use <name>`.
 
 ## SDK
 
-The CLI is a thin shell over the SDK — every command has a direct programmatic equivalent.
+The CLI is a thin shell over the SDK - every command has a direct programmatic equivalent.
 
 ```ts
 import {
@@ -124,13 +126,13 @@ await xpay.discover({ query: "weather" });
 await xpay.useByUrl("https://...");
 await xpay.do("translate this PDF to Japanese");
 await xpay.transfer({ amount: 1, to: "7G73PL...", token: "USDC" });
-await xpay.report({ period: "weekly" });   // via OrbitX402 — no RPC calls from your code
+await xpay.report({ period: "weekly" });   // via OrbitX402 - no RPC calls from your code
 await xpay.wallet.balance("solana");
 ```
 
 ### Agent runtimes
 
-xPay ships tool definitions for the three major LLM SDKs. Same handlers, different schema shapes.
+Xona Wallet ships tool definitions for the three major LLM SDKs. Same handlers, different schema shapes.
 
 ```ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -157,10 +159,10 @@ for (const block of response.content) {
 
 ## MCP server (Claude Desktop / Cursor / Codex)
 
-xPay is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.xona-labs/xpay)
-as **`io.github.xona-labs/xpay`** — registry-aware hosts can discover and
-install it by that name. For everything else, drop xPay into the host's
-config — **no code, no keys, no `xpay init`.** On first boot the agent is
+Xona Wallet is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.xona-labs/xpay)
+as **`io.github.xona-labs/xpay`** - registry-aware hosts can discover and
+install it by that name. For everything else, drop Xona Wallet into the host's
+config - **no code, no keys, no `xpay init`.** On first boot the agent is
 given its own wallet automatically:
 
 ```jsonc
@@ -176,12 +178,12 @@ given its own wallet automatically:
 ```
 
 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
+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`, `xpay_token_find`, `xpay_swap`, `xpay_trending_tokens`, `xpay_trade_quote`, `xpay_trade`, `xpay_x_user`, `xpay_x_posts`, `xpay_zauth_reposcan`, `xpay_zauth_scan_status`, `xpay_shop_search`, `xpay_shop_quote`, `xpay_shop_lens`, `xpay_shop_lens_quote`, `xpay_rwa_find`, `xpay_agenc_status`, 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:
+**Bring your own wallet instead** - the wallet source order is *existing profile → key env → auto-generate*, so any of these overrides the generated wallet:
 
 ```jsonc
 "env": {
@@ -211,7 +213,7 @@ Override with `XPAY_HOME=/some/path` or `xpay init --workspace` for project-loca
 
 ## Biometric unlock (macOS)
 
-Skip typing the passphrase on every command — unlock with Touch ID instead:
+Skip typing the passphrase on every command - unlock with Touch ID instead:
 
 ```bash
 xpay biometric enable     # verifies your passphrase, then stores it Touch ID-gated
@@ -223,14 +225,14 @@ xpay biometric disable    # removes the keychain entry
 How it works: the wallet's scrypt + AES-256-GCM encryption is unchanged. `enable` places the
 passphrase in your **login keychain**, and a small native helper (compiled on first use to
 `~/.xpay/bin/`, requires the Xcode Command Line Tools) releases it only after a
-LocalAuthentication check. Biometrics never replace the passphrase — they gate access to it.
+LocalAuthentication check. Biometrics never replace the passphrase - they gate access to it.
 
 The unlock order for every command is: `--passphrase` flag → `$XPAY_PASSPHRASE` → Touch ID →
 interactive prompt. Your passphrase keeps working everywhere and remains the only recovery
-path — if Touch ID is unavailable (or the stored copy goes stale after a re-encrypt), the CLI
+path - if Touch ID is unavailable (or the stored copy goes stale after a re-encrypt), the CLI
 falls back to asking for it.
 
-> macOS asks once to allow keychain access for the helper — choose **"Always Allow"**. It will
+> macOS asks once to allow keychain access for the helper - choose **"Always Allow"**. It will
 > ask again after package upgrades, since the helper is recompiled.
 
 ## Guardrail
@@ -245,19 +247,19 @@ 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
+- **`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
   Touch ID prompt when [biometric unlock](#biometric-unlock-macos) is enabled, otherwise a y/n
   confirm; in the MCP server it is Touch ID only (no terminal), so an agent's large payment
   surfaces as a system dialog you physically approve. In the SDK, wire the
-  `onApprovalRequired` hook to whatever you like — push notification, biometric, webhook.
+  `onApprovalRequired` hook to whatever you like - push notification, biometric, webhook.
 
-## Security — Bento intent firewall (optional)
+## Security - Bento intent firewall (optional)
 
-Spend caps stop an agent spending *too much* — they can't tell a legitimate payment from a
+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
@@ -266,46 +268,46 @@ 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
+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
+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.
+- **`ALLOW`**: cleared; Xona Wallet signs as normal.
+- **`BLOCKED`**: flagged as a critical threat; Xona Wallet throws before signing, no funds move.
+- **`ESCALATED`**: ambiguous; Xona Wallet 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.
+Xona Wallet 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.
 
-Activating it adds a second wallet surface to xPay: your on-chain USDC (xpay) for agentic x402 payments, and a Sana card (fiat) for everything else. The two compose naturally — an agent can top up the card from the xPay wallet when the balance runs low.
+Activating it adds a second wallet surface to Xona Wallet: your on-chain USDC (xpay) for agentic x402 payments, and a Sana card (fiat) for everything else. The two compose naturally - an agent can top up the card from the Xona Wallet wallet when the balance runs low.
 
 ### Activate
 
 1. Sign up at [sana.bot](https://sana.bot) and generate an API key at `sana.bot/gateway/app/api-keys` (scope: `read:all` covers everything read-only; add `write:card` for deposits and swaps).
-2. Link it to your xPay profile:
+2. Link it to your Xona Wallet profile:
 
 ```bash
 xpay sana link sana_live_...
 xpay sana status          # confirm it's stored
 ```
 
-3. Restart your MCP client — eight `sana_*` tools appear automatically alongside the standard `xpay_*` tools.
+3. Restart your MCP client - eight `sana_*` tools appear automatically alongside the standard `xpay_*` tools.
 
 ### Tools registered
 
 | Tool | What it does |
 |---|---|
-| `sana_card` | Card metadata — type, status, last 4, expiry |
+| `sana_card` | Card metadata - type, status, last 4, expiry |
 | `sana_card_balance` | Available spending power on the card |
 | `sana_card_deposit` | Top up the card with USDC from the Sana wallet |
 | `sana_card_transactions` | Card spending history (paginated) |
@@ -328,7 +330,7 @@ const { tools, handlers } = forClaude(xpay, {
 // tools now includes both xpay_* and sana_* entries
 ```
 
-Or set `SANABOT_API_KEY` in the environment — the MCP server picks it up without any code change.
+Or set `SANABOT_API_KEY` in the environment - the MCP server picks it up without any code change.
 
 ### Unlink
 
@@ -338,15 +340,15 @@ xpay sana unlink          # removes the key from the profile
 
 The `sana_*` tools disappear from the MCP server on next restart.
 
-## AgenC marketplace — hire on-chain agents
+## AgenC marketplace - hire on-chain agents
 
-[AgenC](https://agenc.ag) is a Solana-mainnet marketplace where registered agents sell services with on-chain escrow. Its hireable listings appear in `xpay discover` alongside x402 services — but they **execute differently**, and xpay routes them automatically:
+[AgenC](https://agenc.ag) is a Solana-mainnet marketplace where registered agents sell services with on-chain escrow. Its hireable listings appear in `xpay discover` alongside x402 services - but they **execute differently**, and xpay routes them automatically:
 
 | | x402 service | AgenC listing |
 |---|---|---|
 | Priced in | USDC | native **SOL** |
 | Payment | HTTP `X-Payment` header | on-chain **escrow** (program `HJsZ…w1xK`) |
-| Result | immediate HTTP response | **hire receipt** — the provider works asynchronously |
+| Result | immediate HTTP response | **hire receipt** - the provider works asynchronously |
 | Settlement | instant | after your review window (default 24h) |
 
 ```bash
@@ -355,10 +357,10 @@ xpay agenc hire <listingPda>               # confirm → escrow SOL → get a ta
 xpay agenc status <taskPda>                # poll: open → claimed → review → settled
 ```
 
-The same smart routing works in the SDK and MCP — `xpay.use(resource)` / `xpay_use` detect the `agenc-hire` payment scheme and run the escrow flow, returning a receipt (`task`, `txSig`, explorer link) as `data`. Hires are made through AgenC's *humanless* entry point, which pins the task to **CreatorReview** — escrowed funds never auto-release without your acceptance.
+The same smart routing works in the SDK and MCP - `xpay.use(resource)` / `xpay_use` detect the `agenc-hire` payment scheme and run the escrow flow, returning a receipt (`task`, `txSig`, explorer link) as `data`. Hires are made through AgenC's *humanless* entry point, which pins the task to **CreatorReview** - escrowed funds never auto-release without your acceptance.
 
 Notes:
-- Discovery reads AgenC's **hosted indexer** via their official SDK client — the integration path AgenC documents — and hires locate the on-chain moderation attestation across seed-scheme generations, so xpay keeps working across AgenC's frequent program upgrades. Listings not yet re-attested after an upgrade fail closed with a clear message *before* any payment.
+- Discovery reads AgenC's **hosted indexer** via their official SDK client, the integration path AgenC documents, and hires locate the on-chain moderation attestation across seed-scheme generations, so xpay keeps working across AgenC's frequent program upgrades. Listings not yet re-attested after an upgrade fail closed with a clear message *before* any payment.
 - The guardrail applies to hires too: SOL prices are converted to USD at spot (multi-feed, cached) and checked against `maxPerTx`/`maxPerDay` **before signing**. If no price feed is reachable and caps are set, the hire fails closed.
 - The wallet needs **SOL** (escrow + fees), not just USDC.
 - Reviewing/accepting results happens on [agenc.ag](https://agenc.ag) for now; `xpay agenc accept` is planned.
@@ -366,7 +368,7 @@ Notes:
 
 ## Token discovery & swap (Solana)
 
-Find any Solana token by ticker or mint address and swap into it from your own wallet — keyless, via Jupiter's meta-aggregator:
+Find any Solana token by ticker or mint address and swap into it from your own wallet - keyless, via Jupiter's meta-aggregator:
 
 ```bash
 xpay token find BONK                  # price, mcap, liquidity, mint, ✓ verified / ⚠ unverified
@@ -382,7 +384,7 @@ const result = await xpay.swap({ amount: 0.5, from: "SOL", to: tokens[0].mint })
 
 Notes:
 - **Verification matters.** Anyone can mint a token reusing a real ticker. Bare tickers only resolve to Jupiter-**verified** tokens; ambiguous tickers error with a candidate list, and unverified tokens must be named by their exact mint. `xpay token find` shows the flag.
-- **The guardrail applies.** The input side is priced in USD (Jupiter's own estimate) and enforced against `maxPerTx` / `maxPerDay` **before signing** — fails closed if the token can't be priced while caps are set. Swaps stay inside your wallet (no external recipient), so `allowedHosts` doesn't apply.
+- **The guardrail applies.** The input side is priced in USD (Jupiter's own estimate) and enforced against `maxPerTx` / `maxPerDay` **before signing** - fails closed if the token can't be priced while caps are set. Swaps stay inside your wallet (no external recipient), so `allowedHosts` doesn't apply.
 - **Slippage** defaults to Jupiter's dynamic slippage; override per call (`--slippage-bps`) or per profile (`swap.slippageBps`).
 - Keyless by default (~20 req/s shared bucket). Set `JUPITER_API_KEY` (or profile `swap.apiKey`) for higher limits; `XPAY_JUPITER_ENDPOINT` overrides the API base.
 - This is the **native** swap in your own xpay wallet. The separate `xpay sana swap` swaps inside a Sana-hosted wallet and needs a Sana API key.
@@ -410,7 +412,7 @@ Notes:
 
 ## Robinhood Chain trading
 
-Trade the [NOXA Fun](https://fun.noxa.fi/robinhood) memecoin scene on **Robinhood Chain** (Robinhood's Arbitrum L2, chain `4663`) straight from your own wallet — no API key. NOXA Fun tokens launch into Uniswap V3 pools quoted in native ETH, so trading is plain on-chain V3: quote via QuoterV2, execute via SwapRouter02. Discovery (trending / new tokens, USD pricing) comes from GeckoTerminal's public API.
+Trade the [NOXA Fun](https://fun.noxa.fi/robinhood) memecoin scene on **Robinhood Chain** (Robinhood's Arbitrum L2, chain `4663`) straight from your own wallet - no API key. NOXA Fun tokens launch into Uniswap V3 pools quoted in native ETH, so trading is plain on-chain V3: quote via QuoterV2, execute via SwapRouter02. Discovery (trending / new tokens, USD pricing) comes from GeckoTerminal's public API.
 
 ```bash
 xpay trending                              # what's hot on Robinhood Chain (free, no wallet)
@@ -428,34 +430,34 @@ const result = await xpay.trade({ amount: 0.01, from: "ETH", to: hot[0].address
 
 Notes:
 - **Scope:** ETH ⇄ token only (buy with native ETH, sell back to ETH). Buys auto-wrap ETH; sells unwrap WETH → ETH in one transaction.
-- **The guardrail applies.** The input side is priced in USD (GeckoTerminal spot) and enforced against `maxPerTx` / `maxPerDay` **before signing** — same boundary as `xpay swap`.
-- **Verification.** A token confirmed as a NOXA Fun launch is marked verified; anything else is flagged `unverified` (memecoin tickers aren't unique — prefer passing the exact contract address). NOXA per-tx / max-wallet transfer caps are checked before signing: a buy that would breach one errors up front (instead of reverting on-chain), and the quote flags trades that come close.
+- **The guardrail applies.** The input side is priced in USD (GeckoTerminal spot) and enforced against `maxPerTx` / `maxPerDay` **before signing** - same boundary as `xpay swap`.
+- **Verification.** A token confirmed as a NOXA Fun launch is marked verified; anything else is flagged `unverified` (memecoin tickers aren't unique - prefer passing the exact contract address). NOXA per-tx / max-wallet transfer caps are checked before signing: a buy that would breach one errors up front (instead of reverting on-chain), and the quote flags trades that come close.
 - **Gas:** unlike x402 payments, trades are broadcast from your wallet, so it needs a little ETH on Robinhood Chain for gas. Bridge via [Across](https://across.to) or the Uniswap bridge. RPC override: profile `rpcs.robinhood`.
 - **Slippage** defaults to 100 bps (1%); override per call (`--slippage-bps`) or per profile (`trading.slippageBps`).
 - **Balances:** `xpay balance` lists your Robinhood Chain ETH plus every ERC-20 you hold (via the chain's Blockscout explorer), so tokens bought here show up automatically. Override the explorer with `XPAY_ROBINHOOD_EXPLORER`.
-- This is distinct from `xpay swap` (Solana / Jupiter). GMGN was evaluated and skipped — it doesn't support Robinhood Chain.
+- This is distinct from `xpay swap` (Solana / Jupiter). GMGN was evaluated and skipped - it doesn't support Robinhood Chain.
 
 ## Realtime X (Twitter) data
 
-Agents can pull live X account data with zero setup — no X developer account, no API key. xpay pays xona's x402-gated proxy per call, which passes X's pay-per-use billing through **at cost** (no markup):
+Agents can pull live X account data with zero setup - no X developer account, no API key. xpay pays xona's x402-gated proxy per call, which passes X's pay-per-use billing through **at cost** (no markup):
 
 ```bash
 xpay x user jup_ag          # profile: followers, bio, verification   (~$0.01)
 xpay x posts jup_ag         # 10 recent posts + engagement metrics    (~$0.06)
 ```
 
-MCP: `xpay_x_user` / `xpay_x_posts` — the classic flow is token due diligence: `xpay_token_find` → check the project's X account → swap only if it holds up. Payments go through the normal x402 flow, so the guardrail caps apply. Endpoint override: `XPAY_XDATA_ENDPOINT`.
+MCP: `xpay_x_user` / `xpay_x_posts` - the classic flow is token due diligence: `xpay_token_find` → check the project's X account → swap only if it holds up. Payments go through the normal x402 flow, so the guardrail caps apply. Endpoint override: `XPAY_XDATA_ENDPOINT`.
 
 ## zauth repo security scans
 
-Scan any git repository for code provenance and vulnerabilities via [zauth](https://zauth.inc)'s x402-paywalled scanner (partner integration) — returns a zauth score (0–100) plus a markdown analysis. Only the scan kickoff is paid (~$0.05 USDC on Solana or Base) and the guardrail caps apply (if your profile restricts `allowedHosts`, add `api.zauth.inc`). Status checks are free and need no wallet:
+Scan any git repository for code provenance and vulnerabilities via [zauth](https://zauth.inc)'s x402-paywalled scanner (partner integration) - returns a zauth score (0–100) plus a markdown analysis. Only the scan kickoff is paid (~$0.05 USDC on Solana or Base) and the guardrail caps apply (if your profile restricts `allowedHosts`, add `api.zauth.inc`). Status checks are free and need no wallet:
 
 ```bash
 xpay zauth reposcan https://github.com/owner/repo   # paid: starts the scan (or returns a cached report)
 xpay zauth status <sessionToken>                    # free: poll a still-running scan
 ```
 
-A scan either returns a cached report immediately or `{ status: "scanning", scanId, sessionToken }`; xpay polls the free status endpoint automatically and hands you the sessionToken if the scan outlives the wait window. Follow up with the **sessionToken** (the JWT, valid ~1 hour) — not the scanId.
+A scan either returns a cached report immediately or `{ status: "scanning", scanId, sessionToken }`; xpay polls the free status endpoint automatically and hands you the sessionToken if the scan outlives the wait window. Follow up with the **sessionToken** (the JWT, valid ~1 hour) - not the scanId.
 
 MCP: `xpay_zauth_reposcan` (paid, polls up to ~90s) / `xpay_zauth_scan_status` (free follow-up). Endpoint override: `XPAY_ZAUTH_ENDPOINT`.
 
@@ -488,23 +490,45 @@ MCP: `xpay_shop_lens` (paid) / `xpay_shop_lens_quote` (free preflight: validates
 ```json
 {
   "version": 1,
-  "networks": ["solana", "base", "arbitrum"],
+  "networks": ["solana", "base", "arbitrum", "stable"],
   "defaultNetwork": "solana",
   "rpcs": {
     "solana": "https://your-helius-endpoint",
-    "base":   "https://your-alchemy-endpoint"
+    "base":   "https://your-alchemy-endpoint",
+    "stable": "https://rpc.stable.xyz"
   }
 }
 ```
 
 Public RPCs work for development but rate-limit hard. Production deployments should configure dedicated RPC endpoints.
 
+### Stable chain
+
+**Stable** (chain `988`, Tether/Bitfinex's payments L1) is supported as a first-class wallet network. It settles **USDT0** (the LayerZero OFT at `0x779Ded0c9e1022225f8E0630b35a9b54bE713736`, 6 decimals as an ERC-20), not USDC.
+
+The same derived EVM key covers it, so a Stable signer is registered on **every** profile whether or not `stable` is in `networks`. You get it without re-running `xpay init`:
+
+```bash
+xpay balance                               # includes a stable row: USDT0 + native USDT gas
+xpay balance --network stable
+xpay discover "image generation" --network stable
+xpay transfer 1.5 0xRecipient --network stable          # sends USDT0
+```
+
+Notes:
+
+- **Payments are gasless.** x402 calls on Stable sign an EIP-3009 `transferWithAuthorization` and the facilitator broadcasts, so the wallet needs USDT0 only - no native gas. Direct `xpay transfer` *is* broadcast from your wallet, so that path needs a little native USDT for gas.
+- **The EIP-712 domain is `USDT0` / `1`, not the USDC default.** xpay never hardcodes it: the domain is read from `extra` on the live 402 challenge, which is the only reliable source (`version()` and `eip712Domain()` both revert on this contract).
+- **Two tokens share a name.** The native gas coin is USDT at 18 decimals; the ERC-20 that x402 settles is USDT0 at 6. `xpay balance` lists them separately.
+- **Routing is automatic.** A 402 quoting `eip155:988` resolves to the Stable signer, and `use()` compares USDT0 balance against the price when several chains are offered.
+- RPC override: profile `rpcs.stable` (default `https://rpc.stable.xyz`). Explorer: [stablescan.xyz](https://stablescan.xyz).
+
 ## How it works
 
-- **Keys** — One BIP-39 mnemonic per profile derives Solana (`m/44'/501'/0'/0'`, Phantom-compatible) and EVM (`m/44'/60'/0'/0/0`, MetaMask-compatible) keypairs. Encrypted at rest with scrypt + AES-256-GCM.
-- **Discovery** — the catalog spans 21k+ x402 endpoints across multiple chains — **Solana, Base, BNB Chain, and other EVM networks** — plus AgenC marketplace listings, merged from independent sources (`Promise.allSettled`, so one source failing never kills discovery). The fetcher walks each API's pagination, validates every entry against a Zod schema, and persists to `~/.xpay/cache/` so repeat lookups skip the cold-fetch tax. (Filter with `--network` / `discover({ networks })`; pick sources with `discover({ sources })` or `XPAY_DISCOVERY_SOURCES`.)
-- **Pay** — `use()` and `useByUrl()` both go: guardrail check → signer.pay(USDC) on the right network → `X-Payment` header → retry. The signer abstraction means the same code path works for Solana SPL transfers and EVM ERC-20 transfers. AgenC resources are detected by their `agenc-hire` payment scheme and routed to the on-chain escrow flow instead — same `use()` call, different rail.
-- **Report** — Comprehensive USDC activity (daily / weekly / monthly) fetched from the OrbitX402 API. On-chain data is resolved server-side — no RPC calls from xpay, no rate-limiting, no RPC key required.
+- **Keys**: One BIP-39 mnemonic per profile derives Solana (`m/44'/501'/0'/0'`, Phantom-compatible) and EVM (`m/44'/60'/0'/0/0`, MetaMask-compatible) keypairs. Encrypted at rest with scrypt + AES-256-GCM.
+- **Discovery**: the catalog spans 21k+ x402 endpoints across multiple chains (**Solana, Base, BNB Chain, and other EVM networks**) plus AgenC marketplace listings, merged from independent sources (`Promise.allSettled`, so one source failing never kills discovery). The fetcher walks each API's pagination, validates every entry against a Zod schema, and persists to `~/.xpay/cache/` so repeat lookups skip the cold-fetch tax. (Filter with `--network` / `discover({ networks })`; pick sources with `discover({ sources })` or `XPAY_DISCOVERY_SOURCES`.)
+- **Pay**: `use()` and `useByUrl()` both go: guardrail check → signer.pay(USDC) on the right network → `X-Payment` header → retry. The signer abstraction means the same code path works for Solana SPL transfers and EVM ERC-20 transfers. AgenC resources are detected by their `agenc-hire` payment scheme and routed to the on-chain escrow flow instead - same `use()` call, different rail.
+- **Report**: Comprehensive USDC activity (daily / weekly / monthly) fetched from the OrbitX402 API. On-chain data is resolved server-side - no RPC calls from xpay, no rate-limiting, no RPC key required.
 
 ## Project status
 
@@ -518,15 +542,15 @@ Public RPCs work for development but rate-limit hard. Production deployments sho
 - ✅ xona shop product discovery via x402 (`xpay shop search`), free quote preflight
 - ✅ RWA discovery on Solana (`xpay token rwa`): tokenized stocks/ETFs + USDY, swappable via `xpay swap`
 - ✅ Solana + Base mainnet with disk caching
-- ✅ Optional Sana agent card integration (`xpay sana link`) — 8 additional `sana_*` tools
+- ✅ Optional Sana agent card integration (`xpay sana link`) - 8 additional `sana_*` tools
 - ✅ AgenC marketplace as a discovery source + smart-routed SOL escrow hires (`xpay agenc hire|status`)
 
 **Planned:**
-- `bridge` — USDC EVM ↔ SVM via CCTP (Circle's native burn/mint)
-- `link / unlink` — opt-in cloud sync (audit log, dashboard)
+- `bridge`, USDC EVM ↔ SVM via CCTP (Circle's native burn/mint)
+- `link / unlink`, opt-in cloud sync (audit log, dashboard)
 - Pay catalog + xona-labs catalog as additional discovery sources
-- `xpay agenc accept|rate` — review AgenC hire results without leaving the CLI
+- `xpay agenc accept|rate` - review AgenC hire results without leaving the CLI
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT - see [LICENSE](./LICENSE).

package/SKILL.md

@@ -8,9 +8,9 @@ description: >-
   or SDK.
 ---
 
-# xPay — a wallet and payment rail for agents
+# Xona Wallet: a wallet and payment rail for agents
 
-xPay lets an agent **find a service, pay for it, and get the result** without
+Xona Wallet lets an agent **find a service, pay for it, and get the result** without
 writing any payment plumbing. It hides x402, USDC, RPC, and multi-network
 routing behind a flat set of tools.
 
@@ -20,14 +20,14 @@ an intent and call it in one step).
 
 ## Setup (zero-config)
 
-Add xPay as an MCP server — no keys, no init:
+Add Xona Wallet as an MCP server - no keys, no init:
 
 ```jsonc
 { "mcpServers": { "xpay": { "command": "npx", "args": ["-y", "@xona-labs/xpay", "mcp"] } } }
 ```
 
 On first run the agent is given its **own wallet**. Its Solana address is
-printed to the server's stderr — **fund that address with USDC** and the agent
+printed to the server's stderr - **fund that address with USDC** and the agent
 can pay. The wallet persists and is reused across restarts.
 
 To use a wallet you already hold instead, set `XPAY_SOLANA_SECRET` (base58) in
@@ -41,11 +41,11 @@ the MCP `env`. To require an explicit wallet (no auto-generation), set
 | `xpay_discover` | Find paid services by natural-language query. Returns ranked candidates with price, network, and payee. |
 | `xpay_use` | Pay for and call a specific service. Pass the full `resource` object from `xpay_discover` (preferred), or a `resourceUrl`. Handles the x402 402-challenge → pay → retry flow. |
 | `xpay_do` | One step: discover the best service for an intent **and** call it. Use when you don't need to compare options. |
-| `xpay_transfer` | Send USDC (or any Solana SPL token) directly to an address. Executes immediately, gated by the user's guardrail — confirm amount + destination with the user before calling. |
+| `xpay_transfer` | Send USDC (or any Solana SPL token, or USDT0 on Stable) directly to an address. Executes immediately, gated by the user's guardrail - confirm amount + destination with the user before calling. |
 | `xpay_token_find` | Find Solana tokens by ticker, name, or mint (price, mcap, liquidity, `verified` flag). Read-only. |
 | `xpay_rwa_find` | List tradable RWA tokens on Solana: tokenized stocks/ETFs (xStocks, Ondo, Remora) + treasury-backed USDY. Free, read-only; results swappable via `xpay_swap`. |
 | `xpay_swap` | Swap tokens inside the wallet via Jupiter (Solana only). Irreversible; guardrail-gated. Confirm with the user first. |
-| `xpay_x_user` | Realtime X (Twitter) profile — followers, bio, verification. Paid (~$0.01 at cost via x402). |
+| `xpay_x_user` | Realtime X (Twitter) profile - followers, bio, verification. Paid (~$0.01 at cost via x402). |
 | `xpay_x_posts` | Recent posts from an X account with engagement metrics. Paid (~$0.06 at cost via x402). |
 | `xpay_shop_quote` | Free preflight for product search: exact price, marketplaces it would hit, and whether the query parses as a product search. Quote first when a query is ambiguous. |
 | `xpay_shop_search` | Product discovery across Google Shopping, Amazon, and eBay from one free-text query: normalized, deduped, ranked. Paid (~$0.02 via x402, less for fewer marketplaces). |
@@ -55,66 +55,73 @@ the MCP `env`. To require an explicit wallet (no auto-generation), set
 | `xpay_agenc_status` | Check the progress of an AgenC marketplace hire (see below). Read-only. |
 | `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. |
+| `xpay_bento_disable` | Turn the Bento firewall off - use if the wallet isn't registered and payments are rejected. |
 
 ## How payment works
 
 Services price calls in **USDC** over the **x402** protocol (typically fractions
 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
+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
+When a service accepts more than one network (e.g. Base **and** Solana), Xona Wallet
+**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.
 
+Networks the wallet can pay from: Solana, Base and the other EVM chains,
+Robinhood Chain, and **Stable** (chain 988, Tether's payments L1). Stable
+settles in **USDT0**, not USDC - one derived EVM key covers it, so it is
+always available and needs no setup. Fund it with USDT0; payments there are
+gasless, so no native gas token is needed to pay.
+
 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).
+fails for lack of funds, ask the user to send the right stablecoin to the
+matching address from `xpay_balance` - USDC on Solana mainnet or Base, USDT0
+on Stable.
 
-## AgenC marketplace listings — a different execution rail
+## AgenC marketplace listings - a different execution rail
 
 `xpay_discover` results may include **AgenC marketplace** listings
-(`metadata.source === "agenc"`) — on-chain agent services priced in **SOL**,
+(`metadata.source === "agenc"`) - on-chain agent services priced in **SOL**,
 not USDC. Calling `xpay_use` on one is detected automatically and runs a
 Solana **escrow hire** instead of an HTTP payment:
 
 - The listing's SOL price is escrowed on-chain; the wallet needs **SOL**, not
   USDC, for these.
 - The result is a **hire receipt** (`data.kind === "agenc-hire-receipt"` with
-  `task`, `txSig`, `explorer`), **not** the service's output — the provider
+  `task`, `txSig`, `explorer`), **not** the service's output - the provider
   works asynchronously.
 - Poll `xpay_agenc_status { taskPda }` to track progress:
   `open/claimed → review → settled`. A just-created task can 404 for ~a minute
   (the API snapshot lags); retry, don't treat it as failure.
 - Tell the user the work is in progress and how to review it
-  (https://agenc.ag/tasks/<taskPda>) — escrow only settles after their review
+  (https://agenc.ag/tasks/<taskPda>) - escrow only settles after their review
   window.
 
 The guardrail still applies (SOL converted to USD at spot, checked before
 signing), and hires never auto-release funds without the buyer's acceptance.
 
-## Safety — built in, respect it
+## Safety - built in, respect it
 
 - **Spending guardrail.** Per-tx and per-day USD caps and an allowed-host list
   are enforced *before* signing. A blocked call throws; don't try to route
-  around it — surface the limit to the user.
+  around it - surface the limit to the user.
 - **Transfers and swaps move real funds immediately.** Show the user the
   amount + destination (or the swap pair, USD value, and output-token mint)
   and get their explicit approval *before* calling `xpay_transfer` or
   `xpay_swap`. Never move funds unprompted. The guardrail enforces the user's
   caps before signing either way.
 - **Check token verification.** Before any swap, confirm the output token's
-  `verified` flag from `xpay_token_find` — unverified tokens can be scams
+  `verified` flag from `xpay_token_find` - unverified tokens can be scams
   reusing a real ticker. Never swap into an unverified token unless the user
   explicitly confirms the exact mint address.
 - **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 —
+  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
@@ -137,11 +144,11 @@ signing), and hires never auto-release funds without the buyer's acceptance.
 
 **Send funds (with approval)**
 1. Confirm the amount + destination with the user
-2. `xpay_transfer { amount: 5, to: "<address>", token: "USDC" }` — executes directly, guardrail-gated
+2. `xpay_transfer { amount: 5, to: "<address>", token: "USDC" }` - executes directly, guardrail-gated
 
 **Find and swap into a token (with approval)**
 1. `xpay_token_find { query: "BONK" }` → pick the intended token, check `verified`
-2. Show the user: amount, USD value, output token name + mint + verification — get approval
+2. Show the user: amount, USD value, output token name + mint + verification - get approval
 3. `xpay_swap { amount: 0.5, from: "SOL", to: "<mint from step 1>" }`
 
 **Token due diligence with X (Twitter)**