x402 Payment

How Xona resources are paid for — the 402 → pay → retry flow, with client, server, and manual examples.

All Xona resources are pay-per-use via the x402 protocol. No API keys or subscriptions — you pay in USDC (on Solana by default) for each request.

How it works

Send a request to any resource endpoint (e.g. POST /image/designer).
The server responds with 402 Payment Required and includes the payment details — amount, asset (USDC), and the pay-to address.
Sign the payment with your wallet using the provided payment requirements.
Resend the request with the signed X-PAYMENT header.
The payment settles atomically and you receive the result in the response body.

The xPay SDK and CLI implement this entire loop for you — xpay pay <url> or xpay.useByUrl(...) handles discovery, signing, and retry. The examples below show the manual flow for when you want to integrate it yourself.

Client-side (browser / frontend)

Use @dexterai/x402 to handle the 402 flow automatically from the browser with a connected wallet.

npm install @dexterai/x402

import { wrapFetch } from "@dexterai/x402/client";

const x402Fetch = wrapFetch(fetch, {
  walletPrivateKey: "<solana-wallet-private-key>",
});

// Hit any Xona resource — payment is handled automatically
const response = await x402Fetch("https://api.xona-agent.com/image/designer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "A cyberpunk cityscape at sunset",
    aspect_ratio: "16:9",
  }),
});

const { image_url, image_description, metadata } = await response.json();

Server-side (Node.js / backend)

Same approach works server-side. Store your wallet key securely and wrap your fetch calls.

import { wrapFetch } from "@dexterai/x402/client";

const x402Fetch = wrapFetch(fetch, {
  walletPrivateKey: process.env.SOLANA_PRIVATE_KEY,
});

// Get trending tokens
const res = await x402Fetch("https://api.xona-agent.com/token/pumpfun-trending");
const { summary, trending_tokens } = await res.json();

Manual flow (cURL)

You can also handle x402 yourself. First hit the endpoint to get the payment requirements, then sign and resend.

# Step 1: Get payment requirements
curl -s -X POST "https://api.xona-agent.com/image/designer" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "sunset over mountains"}'
# → Returns 402 with payment requirements in the response body

# Step 2: Sign the payment with your wallet (using your x402 SDK)

# Step 3: Resend with the signed payment header
curl -X POST "https://api.xona-agent.com/image/designer" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-payload>" \
  -d '{"prompt": "sunset over mountains"}'
# → Returns 200 with { image_url, image_description, metadata }

Discovery

List all available resources with pricing and schemas programmatically — no payment required.

# List all x402 resources
curl https://api.xona-agent.com/x402-resources

# x402 discovery document
curl https://api.xona-agent.com/.well-known/x402

How it works

Client-side (browser / frontend)

Server-side (Node.js / backend)

Manual flow (cURL)

Discovery

On this page