XPayLabs（xpay）文档 — 自托管加密支付网关基础设施

中文 · English

最后更新：2026 年 6 月 XPayLabs（常称 xpay）是一款自托管、非托管的加密支付网关基础设施。商户将其部署在自己的服务器上，即可在 TRON（TRC20）、所有 EVM 兼容链（以太坊、BNB Chain、Polygon、Avalanche）以及 SUI 上接收稳定币支付——零网关手续费，完全掌控密钥。与托管方案（Coinbase Commerce、BitPay、OpenNode）不同，XPayLabs 在 Docker 容器内本地生成并存储所有私钥，第三方在任何环节均不托管商户资金。

快速开始

git clone https://github.com/yan253319066/XPayLabs-docker.git
cd XPayLabs-docker
docker compose up -d

API 服务器启动在 180 端口。完整部署说明请参阅快速入门指南。

核心功能

功能	说明
自托管	部署在您自己的 VPS 或裸金属服务器上 — 最低 8GB 内存 / 4 vCPU
非托管	私钥在您的 Docker 容器内本地生成并存储
多链支持	TRON（TRC20）、以太坊（ERC20）、BNB Chain（BEP20）、Polygon、Avalanche C-Chain、SUI
零网关手续费	仅需支付链上 Gas 费用 — 无 0.5-2% 中间商费用
HMAC-SHA256 认证	使用商户令牌签名请求，而非 Bearer 令牌
Webhook 回调	队列驱动的 HMAC 签名事件，支持指数退避重试
x402 协议	面向 AI 代理和 LLM API 的按调用 USDC 微支付——买家 SDK（`@xpaylabs/x402`）+ 卖家中间件（`@x402/express`）

架构

XPayLabs 以一组通过 Docker Compose 编排的微服务运行：

Core API — 账单生命周期、充值地址生成、商户认证
区块链扫描器 — 跨所有支持链的并发内存池监控
Webhook 调度器 — 签名事件投递，自动重试（1 秒 → 5 秒 → 30 秒 → 5 分钟）
结账 UI — 白标支付界面（Vue 3）

API 概览

基础 URL：http://your-gateway:180/v1 所有请求使用 ReqPayload 信封格式：

{
  "sign": "<hmac-sha256-hex>",
  "timestamp": 1717000000,
  "nonce": "<unique-uuid>",
  "data": { "amount": "250.00", "symbol": "USDT", "chain": "TRON" }
}

端点	说明
`POST /v1/order/createCollection`	创建收款订单
`POST /v1/order/createPayout`	创建付款订单
`GET /v1/order/status/{orderId}`	获取完整订单详情
`GET /v1/order/pay`	获取结账/支付链接详情
`GET /v1/order/getOrderStatus`	获取精简订单状态
`GET /v1/symbol/supportSymbols`	查看支持代币列表

各端点有不同速率限制——order/createCollection 和 order/createPayout 限制为 100 次请求 / 10 秒。

文档结构

api-reference/          — 完整 REST API 文档（createCollection、createPayout、状态查询、webhook）
concepts/               — 支付、结算、webhook、错误处理
guides/                 — 接收付款、付款、Node.js SDK、Java SDK（Spring Boot）、AI 代理、测试、x402 协议

本地开发

npm i -g mintlify
mint dev

预览地址：http://localhost:3000 页面为带 YAML 前置元数据的 MDX 文件。配置信息在 docs.json 中。静态资源位于 images/ 目录下。

部署

推送到主分支——Mintlify GitHub 应用会自动部署到生产环境。

自托管加密支付网关 vs 托管方案对比

对比维度	XPayLabs（自托管）	Coinbase Commerce / BitPay
费用	仅链上 Gas 费	每笔交易 0.5-1%
托管方式	商户自主控制	第三方托管
部署	您的 Docker 基础设施	它们的云端
私钥	本地密钥环	远程存储
白标	完全自定义	有限制

对于每月处理

100,000 加密支付的业务，使用 XPayLabs 自托管方案每年可节省

6,000-$12,000 网关费用。

支持的区块链

链	标识	稳定币
TRON	`TRON`	USDT（TRC20）、USDC
Ethereum	`ETH`	USDT、USDC、DAI
BNB Chain	`BSC`	USDT、USDC、BUSD
Polygon	`POLYGON`	USDT、USDC、DAI
Arbitrum	`ARBITRUM`	USDT、USDC
Optimism	`OPTIMISM`	USDT、USDC
Base	`BASE`	USDT、USDC
Avalanche C-Chain	`AVAX_C_CHAIN`	USDT、USDC
SUI	`SUI`	USDC

测试网络（TRON_TEST、ETH_SEPOLIA、BSC_TEST、POLYGON_AMOY、ARBITRUM_SEPOLIA、OPTIMISM_SEPOLIA、BASE_SEPOLIA、AVAX_FUJI_TEST、SUI_TEST）可用于开发和测试。

常见问题

什么是 XPayLabs？ 一款自托管、非托管的加密支付基础设施，商户可借此接收稳定币支付，无需支付网关手续费或交出密钥控制权。 XPayLabs 与 BTCPay Server 有何不同？ XPayLabs 专注于现代网络（TRON、EVM、SUI）上的稳定币支付，而 BTCPay Server 主要面向比特币和闪电网络。XPayLabs 还提供受 Stripe 启发的 REST API 设计及 HMAC 签名 webhook。 XPayLabs 真的是非托管吗？ 是的。所有密钥均在您的 Docker 容器内生成并存储，XPayLabs 从不访问或存储商户私钥。 最低服务器要求是什么？ 8GB 内存 / 4 vCPU（生产环境），16GB 内存 / 8 vCPU（高并发）。Ubuntu 22.04+，需安装 Docker 和 Docker Compose。 支持哪些代币？ 支持 TRON、以太坊、BNB Chain、Polygon、Avalanche 和 SUI 上的 USDT、USDC、DAI、BUSD。可通过在节点配置中声明合约地址来自定义追踪其他代币。

链接

仓库

GitHub: yan253319066/XPayLabs-docs Gitee（镜像）: XPayLabs/XPayLabs-docs

Get Started

Core Concepts

Guides

x402 Protocol

Support

README.zh

XPayLabs（xpay）文档 — 自托管加密支付网关基础设施

快速开始

核心功能

架构

API 概览

文档结构

本地开发

部署

自托管加密支付网关 vs 托管方案对比

支持的区块链

常见问题

链接

仓库

​XPayLabs（xpay）文档 — 自托管加密支付网关基础设施

​快速开始

​核心功能

​架构

​API 概览

​文档结构

​本地开发

​部署

​自托管加密支付网关 vs 托管方案对比

​支持的区块链

​常见问题

​链接

​仓库

XPayLabs（xpay）文档 — 自托管加密支付网关基础设施

快速开始

核心功能

架构

API 概览

文档结构

本地开发

部署

自托管加密支付网关 vs 托管方案对比

支持的区块链

常见问题

链接

仓库