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.

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.

npm install -g @xona-labs/xpay

xpay init # creates Solana + EVM keys, encrypted xpay discover "research API" # 21k x402 catalog + AgenC agent listings, ranked xpay pay https://api.example.com/x402 # x402 one-liner xpay agenc hire # hire an on-chain agent (SOL escrow) xpay token find BONK # find any Solana token by ticker or mint xpay swap 0.5 SOL BONK # swap in your own wallet via Jupiter xpay transfer 5 USDC 7G73PL...gC # direct USDC transfer xpay balance # unified across networks xpay report # daily / weekly / monthly report via OrbitX402

// 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 } });

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.

Install

npm install -g @xona-labs/xpay      # CLI + MCP server, system-wide

npm install @xona-labs/xpay # programmatic SDK in a project

Quickstart

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.

1. depend 2. guess 3. mercy 4. online

... (24 words)

Fund the addresses with a few dollars of USDC on Solana mainnet, Base, or both. Then:

xpay balance

xpay discover "image generation" xpay pay https://orbisapi.com/proxy/image-alt-text-generator-api-1c9472

CLI commands

All commands run from a single profile. Switch with xpay accounts use .

SDK

The CLI is a thin shell over the SDK - every command has a direct programmatic equivalent.

import {

createXPay, initProfile, loadProfile, setProfileGuardrail, } from "@xona-labs/xpay";

// One-time setup const created = await initProfile({ name: "default", passphrase: process.env.XPAY_PASSPHRASE!, }); console.log(created.addresses); // { solana, evm } console.log(created.mnemonic); // back this up; not persisted in plaintext

// Configure spending caps setProfileGuardrail("default", { maxPerTx: 0.5, maxPerDay: 5, allowedHosts: ["api.payai.network", "*.xona-agent.com"], });

// Use const profile = await loadProfile({ name: "default", passphrase: process.env.XPAY_PASSPHRASE }); const xpay = createXPay({ profile });

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.wallet.balance("solana");

Agent runtimes

Xona Wallet ships tool definitions for the three major LLM SDKs. Same handlers, different schema shapes.

import Anthropic from "@anthropic-ai/sdk";

import { createXPay, forClaude, loadProfile } from "@xona-labs/xpay";

const xpay = createXPay({ profile: await loadProfile({ passphrase }) }); const { tools, handlers } = forClaude(xpay);

const response = await new Anthropic().messages.create({ model: "claude-sonnet-4-5", tools, messages: [{ role: "user", content: "find a cheap weather API and call it" }], });

for (const block of response.content) { if (block.type === "tool_use") { const result = await handlers[block.name]!(block.input as Record ); // ... feed result back to Claude } }

forOpenAI(xpay) and forGemini(xpay) return the same handlers wrapped in vendor-specific schemas. See examples/claude-agent.ts for the full tool-use loop.

MCP server (Claude Desktop / Cursor / Codex)

Xona Wallet is listed in the official MCP Registry 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:

// ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "xpay": { "command": "npx", "args": ["-y", "@xona-labs/xpay", "mcp"] } } }

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, 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_trust_check, xpay_order_create, xpay_orders_list, xpay_order_cancel, xpay_orders_run, xpay_agenc_status, plus xpay_bento_status / xpay_bento_enable / xpay_bento_disable to manage the intent firewall. 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:

"env": {

"XPAY_SOLANA_SECRET": " ", // use a wallet you already hold "XPAY_PASSPHRASE": " ", // or unlock/encrypt a profile "XPAY_NO_AUTO_WALLET": "1" // or disable auto-generation entirely }

On macOS, with biometric unlock enabled on a profile, the server shows one Touch ID dialog at startup instead of keeping the passphrase in host config.

See [SKILL.md](SKILL.md) for a framework-agnostic guide to driving these tools from any agent.

Profiles

Each profile is a directory under ~/.xpay/ with:

~/.xpay/

├── default/ (or any name) │ ├── wallet.json BIP-39 seed, AES-256-GCM encrypted by default │ └── config.json networks, guardrail, RPC overrides, link └── cache/ disk cache of catalogs (auto-managed)

Override with XPAY_HOME=/some/path or xpay init --workspace for project-local profiles.

Biometric unlock (macOS)