Documentation Index
Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
Use this file to discover all available pages before exploring further.
AI 代理可以使用 XPayLabs 自主发送和接收稳定币支付。代理调用 REST API 创建收款订单和发起付款，监听 Webhook 事件，并管理余额——零网关费用，资金完全自托管。
为什么 AI 代理需要加密货币？
| 挑战 | XPayLabs 解决方案 |
|---|
| 代理需要可编程货币 | REST API 支持 createCollection/createPayout——代理直接调用端点 |
| 无需人工参与审批 | 使用环境变量中存储的密钥自动签名 |
| 跨境代理间支付 | TRON、EVM 和 SUI 上的稳定币数秒内完成结算 |
| 微交易 | 零网关费用——仅区块链 gas 费用（0.01–0.50） |
| 需自托管 | 非托管——密钥保留在您的 Docker 容器中 |
代理支付流程
收款（代理获得支付）
代理通过创建收款订单来接收加密支付。这是最常见的流程——用户或其他代理将资金发送到代理生成的充值地址。
async function requestPayment(userId: string, amount: number, orderId: string) {
const collection = await xpay.createCollection({
amount,
symbol: 'USDT',
chain: 'TRON',
orderId,
uid: userId,
});
return {
depositAddress: collection.data.address,
expiresAt: collection.data.expiredTime,
checkoutUrl: collection.data.paymentUrl,
};
}
ORDER_SUCCESS Webhook 以释放服务：
app.post('/webhook', (req, res) => {
const event = xpay.parseWebhook(JSON.stringify(req.body), req.body.sign, req.body.timestamp.toString());
if (event?.notifyType === 'ORDER_SUCCESS') {
const data = event.data as any;
await unlockService(data.orderId, data.actualAmount);
}
res.status(200).send('ok');
});
付款（代理支付）
代理向外部地址发起付款——支付计算费用、质押或与其他代理结算：
async function payComputeProvider(providerAddress: string, amount: number, jobId: string) {
const payout = await xpay.createPayout({
amount,
symbol: 'USDT',
chain: 'ETH',
orderId: `compute-${jobId}`,
receiveAddress: providerAddress,
uid: 'ai-agent-01',
});
return payout.data.orderId;
}
代理间支付
两个自主代理可以直接交易：
Agent A ──POST /v1/order/createCollection──▶ 网关 ──返回充值地址──▶ Agent A
│
│ 将充值地址发送给 Agent B
▼
Agent B ──发送 USDT 到地址──────────────▶ 区块链 ──扫描器检测──▶ 网关
│
│ ORDER_SUCCESS Webhook
▼
Agent A ──接收 Webhook──▶ 履行协议
自主代理架构
┌─────────────────────────────────────────────────┐
│ 您的服务器 │
│ │
│ ┌──────────┐ ┌─────────────┐ │
│ │ Agent A │────▶│ XPayLabs │ │
│ │ (买方) │◀───│ SDK / API │ │
│ └──────────┘ └──────┬──────┘ │
│ │ │
│ ┌──────────┐ │ ┌───────────────┐ │
│ │ Agent B │───────────┘ │ Webhook │ │
│ │ (卖方) │───────────────│ 端点 │ │
│ └──────────┘ └───────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ 区块链 │ │
│ │ 扫描器 │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────┘
关键设计考量
密钥管理
商家令牌和 API 密钥必须在运行时对代理可用，且不能硬编码：
# 环境变量——切勿提交到 git
XPAYLABS_MERCHANT_TOKEN=your-merchant-token
XPAYLABS_API_SECRET=your-api-secret
XPAYLABS_GATEWAY_URL=http://gateway:3010
幂等性
代理可能会重试失败的请求。使用 orderId 字段作为幂等键——在 createCollection 或 createPayout 调用中使用相同的 orderId 会返回现有订单，而不会创建重复订单。
Webhook 可靠性
如果 Webhook 丢失，代理应使用轮询回退（getOrderStatus）。每 3 秒轮询一次直到 SUCCESS、EXPIRED 或 FAILED：
async function waitForConfirmation(orderId: string, maxWaitMs = 120000): Promise<boolean> {
const start = Date.now();
while (Date.now() - start < maxWaitMs) {
const status = await xpay.getOrderStatus(orderId);
const s = status.data?.status;
if (s === 'SUCCESS') return true;
if (s === 'EXPIRED' || s === 'FAILED') return false;
await new Promise(r => setTimeout(r, 3000));
}
return false;
}
余额管理
在创建付款前，检查网关热钱包余额：
const balance = await xpay.getMerchantBalance('USDT');
console.log(`可用：${balance.data?.balance}，冻结：${balance.data?.frozenBalance}`);
应用场景
| 场景 | 流程 | 示例 |
|---|
| API 按次付费访问 | 代理创建收款→用户支付→Webhook 解锁端点 | LLM 推理 API |
| 计算资源市场 | Agent A 通过付款向 Agent B 支付 GPU 时间 | 分布式 ML 训练 |
| 自主联盟营销 | 联盟代理接收收款 Webhook，向推荐人分配付款 | 推荐计划 |
| 代理间结算 | 代理钱包之间的定期批量付款 | 跨代理记账 |
| 微支付流 | 频繁的小额收款 | 实时数据流 |
开始使用
- 通过 Docker Compose 部署 XPayLabs
- 安装 Node.js SDK 或直接调用 REST API
- 使用商家令牌和 API 密钥配置代理的环境
- 为
ORDER_SUCCESS 事件创建 Webhook 端点
- 开始通过编程方式创建收款和付款订单
对于代理间支付，两个代理可以共享同一个 XPayLabs 网关实例——或者运行各自的独立实例以实现完全隔离。
