x402 支付

Xona 资源如何付费，即 402 → 付款 → 重试的流程，附客户端、服务端和手动示例。

所有 Xona 资源都通过 x402 协议按次付费。无需 API key 或订阅，每个请求以 USDC（默认在 Solana 上）付费。

运作方式

发送请求到任意资源端点（例如 POST /image/designer）。
服务器返回 402 Payment Required，并附带付款详情：金额、资产（USDC）以及收款地址。
根据提供的付款要求，用你的钱包签署付款。
携带已签名的 X-PAYMENT 头重新发送请求。
付款以原子方式结算，你将在响应体中收到结果。

Xona Wallet SDK 和 CLI 会为你实现整个循环：xpay pay <url> 或 xpay.useByUrl(...) 会处理发现、签名和重试。下面的示例展示了你想自行集成时的手动流程。

客户端（浏览器 / 前端）

使用 @dexterai/x402，在浏览器中配合已连接的钱包自动处理 402 流程。

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();

服务端（Node.js / 后端）

同样的方法也适用于服务端。安全地存储你的钱包私钥，并封装你的 fetch 调用。

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();

手动流程（cURL）

你也可以自行处理 x402。先请求端点以获取付款要求，然后签名并重新发送。

# 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 }

发现

以编程方式列出所有可用资源及其定价和 schema，无需付款。

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

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

运作方式

客户端（浏览器 / 前端）

服务端（Node.js / 后端）

手动流程（cURL）

发现

本页目录