Documentation

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

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

$ 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

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

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

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.report({ period: "weekly" }); // daily | weekly | monthly
await xpay.wallet.balance("solana");

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

xpay report replaces the old direct-RPC history command. On-chain data is fetched server-side by OrbitX402 — no RPC URL, no rate-limiting, no 429 errors on your end.

# CLI
xpay report                      # weekly (default)
xpay report --period daily
xpay report --period monthly --json

# SDK
const report = await xpay.report({ period: "weekly" });
// report.summary   → { totalSent, totalReceived, netFlow, txCount }
// report.timeline  → daily buckets with sent / received / txCount
// report.topCounterparties → sorted by volume
// report.topTransactions   → biggest individual payments

The MCP tool is xpay_report — agents can ask for a spending summary without any additional setup.

Drop xPay into any MCP host — Claude Desktop, Cursor, Codex — with no code and no keys. On first run the agent is given its own wallet; the address is printed to the server log, so fund it with USDC and the agent can pay. The wallet persists, so the address stays stable across restarts.

// claude_desktop_config.json — no keys, no setup
{
  "mcpServers": {
    "xpay": {
      "command": "npx",
      "args": ["-y", "@xona-labs/xpay", "mcp"]
    }
  }
}
 
// first run → the agent gets its own wallet; fund the printed address
› "pay api.xona-agent.com to make a short video"

Already have a wallet? Set XPAY_SOLANA_SECRET in the config’s env, or point at an xpay init profile with XPAY_PROFILE + XPAY_PASSPHRASE — either takes precedence over the generated wallet.

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

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'

Calls at or above requireApprovalAbove need explicit approval: a Touch ID prompt when biometric unlock is enabled, otherwise a y/n confirm in the terminal. In the MCP server it is Touch ID only — 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 prompt, or webhook.

Caps stop overspending, but they can't tell a legitimate payment from a prompt-injected one. For that, enable the optional Bento intent firewall — every payment is screened for malicious intent (prompt-injection, wallet-drain) before signing. Turn it on with xpay bento enable.

Skip typing the passphrase on every command — unlock with Touch ID instead.

xpay biometric enable     # verifies your passphrase, then stores it Touch ID-gated
xpay balance              # → Touch ID prompt instead of a passphrase prompt
xpay biometric status     # availability + current state
xpay biometric disable    # removes the keychain entry

The wallet's scrypt + AES-256-GCM encryption is unchanged. enable places the passphrase in your login keychain, and a small native helper releases it only after a LocalAuthentication check (compiled on first use; requires the Xcode Command Line Tools). Unlock order: --passphrase → $XPAY_PASSPHRASE → Touch ID → interactive prompt.

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.