@xona-labs/xpay

Documentation

The agentic-commerce wallet — multi-network USDC, x402 payments, and discovery across 21,000+ services. Ships as a CLI, an SDK, and an MCP server.

Install

The CLI and MCP server install globally; the SDK installs into a project. They share the same core, so you can mix them.

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

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

Quickstart

Create a profile, fund the addresses with a little USDC on Solana or Base, then discover and pay.

bash

$ npm install -g @xona-labs/xpay
 
$ xpay init
✔ Solana  7RB7frd…6qkpf5ph
✔ EVM     0xA5D9…1023dfa
 
$ xpay discover "short video"
  $0.5000  solana  api.xona-agent.com
 
$ xpay pay api.xona-agent.com/video/…
✔ Paid $0.5000 on solana · 1.2s

bash@xona-labs/xpay

Back up your recovery phrase. init prints a 24-word seed once and encrypts your keys with a passphrase. There is no way to recover it if you lose it.

CLI commands

xpay init [name]Create a profile — Solana + EVM from one seed. --import, --no-encrypt, --workspace.

xpay accountslist · show · use — manage and switch profiles.

xpay balanceUSDC balance per network for the active profile.

xpay discover [query]Search 21k+ x402 services. --network, --limit, --json.

xpay pay <url>Pay an x402 endpoint (catalog or live 402). --max-usd, --body, -y.

xpay transfer <amt> USDC <to>Direct USDC transfer, subject to the guardrail. --network, -y.

xpay historyRecent on-chain USDC activity across networks.

xpay guardrailshow · set · clear — manage spending caps and allowed hosts.

xpay mcpStart the MCP server on stdio.

SDK

The CLI is a thin shell over the SDK — every command has a programmatic equivalent. One entry point, fully typed.

agent.ts

import { createXPay, loadProfile } from "@xona-labs/xpay"
 
const xpay = createXPay({
  profile: await loadProfile({ passphrase }),
});
 
// pay any x402 endpoint, get the result
const video = await xpay.useByUrl(
  "https://api.xona-agent.com/video/short-generation",
  { body: { prompt: "a cat astronaut" } }
);

typescript@xona-labs/xpay

Other surface you’ll use often:

await xpay.discover({ query: "weather" });
await xpay.do("translate this PDF to Japanese");
await xpay.transfer({ amount: 1, to, token: "USDC" });
await xpay.history({ limit: 10 });
await xpay.wallet.balance("solana");

Agent runtimes get first-class tool definitions: forClaude(xpay), forOpenAI(xpay), and forGemini(xpay) — same handlers, vendor-shaped schemas.

MCP server

Drop xPay into any MCP host — Claude Desktop, Cursor, Codex — with no code. The server reads the same profile you created with xpay init.

claude_desktop_config.json

// claude_desktop_config.json
{
  "mcpServers": {
    "xpay": {
      "command": "npx",
      "args": ["-y", "@xona-labs/xpay", "mcp"],
      "env": { "XPAY_PASSPHRASE": "•••" }
    }
  }
}
 
› "pay api.xona-agent.com to make a short video"

json@xona-labs/xpay

The host then exposes seven tools: xpay_discover, xpay_use, xpay_do, xpay_transfer, xpay_balance, xpay_history, xpay_guardrail.

Guardrails

Guardrails run before any signer is touched, so a misbehaving agent can’t bypass them. Amount caps apply to both paid calls and transfers; allowed hosts apply only to x402 calls.

xpay guardrail set \
  --max-per-tx 0.5 \
  --max-per-day 5 \
  --require-approval-above 1 \
  --allowed-hosts 'api.payai.network,*.xona.xyz'

In the SDK, requireApprovalAbove calls your onApprovalRequired hook — wire it to a push notification, biometric prompt, or webhook.

Profiles

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

~/.xpay/
└── default/
    ├── wallet.json    # BIP-39 seed, AES-256-GCM encrypted
    └── config.json    # networks, guardrail, RPC overrides

One mnemonic derives Solana (m/44'/501', Phantom-compatible) and EVM (m/44'/60', MetaMask-compatible). Override the root with XPAY_HOME, or use xpay init --workspace for project-local profiles.