从零部署你自己的加密货币收款网关

项目介绍

什么是 Xcash

Xcash 是开源、自部署、非托管的加密货币收款网关，面向商家、SaaS 产品、交易所和钱包平台，提供账单收款、USDT 收款和充值收款能力。

不同于 CoinGate、OpenNode 这类托管式收款处理商，Xcash 强调非托管：收款经智能合约直达你的归集地址，Xcash 全程不托管资金，也不抽取平台手续费——你只承担链上微量 Gas。它适合需要多链资产收款、充值收款和 Webhook 通知能力的业务系统。

适用场景：电商加密货币账单收款、USDT 充值收款系统、跨境稳定币结算、SaaS 加密货币订阅计费、链上收款基础设施，以及企业内部数字资产入账管理。

Xcash 以 MIT 协议开源，代码完全公开可审计。如果你不想自行部署，也可使用官方云服务 xca.sh，开箱即用、免维护。

账单收款 vs 充值收款

Xcash 提供两种入账方式，对接前请先区分清楚：

• 账单收款：账单式收款。每笔交易创建一张定额、限时的账单，买家付款后账单完成，适合电商下单、订阅计费等一次性收款场景。账单收款支持钱包直收与智能合约两种模式：既可直接收进项目钱包，也可为每张账单分配独立合约地址并自动归集。
• 充值收款：交易所式充值收款。为每个用户分配专属充值收款地址，且多链共享，实时监控；用户可随时转入、区块确认后入账，无需逐笔创建订单，适合需要维护用户余额的钱包、交易类业务。

核心特性

链与币种支持

Xcash 覆盖主流 EVM 链与 Tron，账单收款与充值收款均可使用：

代币方面：

具体可用的链币组合还取决于后台启用状态、链上币种部署关系，以及项目的收款模式与归集地址配置。各链的接口 code 见 网关地址与链码。

技术原理

非托管安全模型

Xcash 最核心的设计是把资金路径和控制面彻底分离。一切收款都走智能合约，而合约里把资金流向写死为你的归集地址。这带来一个很强的安全保证：

即使部署 Xcash 的服务器被攻破、数据库被拖库、密钥泄露，只要你的归集地址不被篡改，资金都不会有任何安全风险。恢复服务后，用户完成账单收款或充值收款的款项仍会流入你的归集地址，攻击者无能为力。

之所以能做到，是因为：

• Xcash 永不托管你的收款资金；
• 一切收款走智能合约，智能合约写死资金流向为你的归集地址；
• 收款合约极简，攻击面趋近于 0。

系统架构

Xcash 由几个职责清晰的组件构成，买家与商户系统通过 API 和 Webhook 与之交互：

• Xcash API：对外提供创建账单收款、查询状态、获取充值收款地址等接口，是商户与买家的统一入口。
• Xcash Worker：负责链上交易监听、状态流转与资金归集调度，是连接区块链与业务状态的核心。
• Xcash 钱包引擎：基于 BIP44 HD 钱包派生地址并对系统交易签名，助记词由你自己托管。
• Xcash Webhook：在账单收款、充值收款进入关键状态时，向商户异步推送事件。

资金路径只在「买家 → 收款合约 → 你的归集地址」之间流动；上述组件全程作为控制面，不经手资金。技术栈如下：

两种账单收款模式

只有账单收款才区分收款模式，按链类型支持以下两种，二者的资金安全性一致，区别在于地址形态与归集方式：

• 钱包直收（Differ）：系统使用项目配置的钱包直收地址收款，并可能通过微调买家应付金额（pay_amount）来区分落在同一地址上的不同账单。资金直接进入你的钱包，无需归集。
• 智能合约（VaultSlot）：系统为每张账单分配一个独立合约地址；买家付款确认后，系统调度归集，把资金清扫进项目配置的对应链类型归集地址。地址天然隔离、互不冲突，适合高并发。

EVM 与 Tron 均可用于账单收款。实际采用哪种模式由后台按链类型配置；选择智能合约的链，必须配置对应链类型的归集地址。充值收款不区分这两种模式，始终采用智能合约。

智能合约原理

智能合约（VaultSlot）是 Xcash 最具特色的机制，理解它有助于理解整套安全模型：

• 地址可提前确定：每张账单的收款地址由「工厂合约 + 实现合约 + 你的归集地址 + 一个 salt」确定性推导得出（CREATE2 式预测）。也就是说，在合约真正部署到链上之前，地址就已经算出来了，买家可以直接向这个「反事实地址」付款。
• 资金流向写死：部署时，你的归集地址被写进合约。合约的归集方法 collect() 只能把余额清扫到这个写死的归集地址，没有任何权限可以改变流向。
• 归集任何人可触发：因为 collect() 只会把钱送往写死的归集地址，它不做调用者权限校验——触发者只承担 Gas。因此 Xcash 全局只需维护一个系统热钱包来支付部署与归集的 Gas。
• 原生币与代币：归集原生币时合约用 address(0) 表示清扫当前原生币余额，归集 ERC-20 时传入对应代币合约地址。

正因为归集地址被写进合约、且 collect() 无权重定向，连 Xcash 自己都无法把买家的付款转去别处。这就是「服务器被攻破也偷不走钱」的技术根源。

充值收款机制

充值收款面向需要维护用户余额的业务。你通过 API 为某个终端用户（uid）在某条链上申请一个充值收款地址；同一项目、同一 uid、同一链会稳定返回同一个合约地址，并且多链共享，便于展示给用户长期使用。

用户向该地址转账后，Worker 监听到链上转账并达到确认要求即视为到账，随后调度归集，把资金清扫进项目的对应链类型归集地址，并向你的通知地址推送充值 Webhook。整个过程无需为每次充值创建订单。

充值收款地址同样是智能合约地址，归集需要系统热钱包在对应链上保留少量 Gas / Energy。当前充值收款支持 EVM 与 Tron，Tron 开放 USDT 与原生 TRX。

链上风控（AML）

Xcash 内置风控查询、缓存、记录与展示能力；当前的风险地址识别依赖外部 MistTrack（慢雾）服务，并非项目自研黑名单或链上风控模型。风控覆盖两类核心资金入口：

• 账单收款：账单匹配到链上付款后，对付款方地址做异步风险查询，把风险等级与分数同步到账单记录。
• 充值收款：充值记录创建后，对转入资金的来源地址做异步风险查询，把风险等级与分数同步到充值记录。

风险结果会写入独立的风险评估记录（查询状态、目标类型、来源地址、交易哈希、风险等级、风险分数），管理后台可直接查看，便于人工复核与处置。账单收款、充值收款的 API 与 Webhook 输出也会携带 risk_level 与 risk_score。

Xcash 优先使用 MistTrack OpenAPI V3；未配置其 API Key 时自动回退到 QuickNode 的 MistTrack add-on；两者都未配置则不启用风控功能。

部署

部署前准备

开始部署前，请准备以下条件：

• Linux 服务器，推荐 Ubuntu 22.04+ 或 Debian 12+；
• Docker 和 Docker Compose；
• 已解析到服务器 IP 的域名；
• 需要启用的公链 RPC 节点；
• 如需启用 Tron 收款，准备 TronGrid API Key。

性能档位

EVM 账单收款与充值收款都通过链上事件扫描感知和确认状态，且二者均默认启用、需要同时监听。实际可承载的链数量取决于 RPC 节点吞吐、出块速度和事件量，建议保守配置。性能档位由 .env 中的 PERFORMANCE 控制，可选 low / medium / high，不设置默认 low。

PERFORMANCE=medium

快速开始

1. 克隆项目

git clone https://github.com/xca-sh/xcash.git
cd xcash

2. 初始化环境变量

该命令会生成 .env 并自动填充运行所需的随机密钥和数据库口令。如果 .env 已存在，脚本会拒绝覆盖并退出；如需重新生成，请先手动备份并删除旧文件。

./scripts/init_env.sh

3. 设置访问域名

编辑 .env 设置 SITE_DOMAIN：

SITE_DOMAIN=xcash.example.com

请确保该域名的 DNS 已解析到服务器 IP，并配置 Nginx 或 Caddy 等反向代理，将流量转发至 http://localhost:6688。以 Caddy 为例：

your-domain.com {
    reverse_proxy localhost:6688
}

可选：设置 ADMIN_PATH 将后台入口移动到自定义路径，未设置时后台仍挂在站点根路径，并会在后台右上角显示安全提醒。

ADMIN_PATH=secure-admin

4. 启动服务

docker compose up -d

首次启动时，如果数据库内还没有任何管理员账号，系统会自动创建默认后台账号：

username: admin
password: Admin@123456

默认密码仅用于首次登录，登录后请立即修改。生产环境强烈建议同时设置 ADMIN_PATH 隐藏后台入口。

配置链 RPC

系统已预置主流链的基础信息，但 RPC 节点地址需要自行填写，网关才能与区块链通信。登录管理后台，进入 区块链 → 公链 页面，为需要使用的链填写 RPC 地址。

推荐使用 QuickNode、Alchemy 或 Infura 等节点服务商。Tron 收款需要在 TronGrid 注册并获取 API Key。

系统钱包充值 Gas

登录管理后台，进入 系统 → 系统钱包 页面，复制系统钱包地址，并在每条启用的 EVM 链上向该地址充值少量原生资产用于支付 Gas（例如 ETH、BNB、POL 等）。

系统钱包只用于平台基础设施交易，例如合约部署、归集交易等需要由系统主动发起的链上操作；业务收款资金仍按合约规则流向你的归集地址。这里不需要存入业务资金，只需保留覆盖近期操作的小额 Gas，避免因 Gas 不足导致合约部署或归集任务无法广播。

即便系统钱包 Gas 不足，也不会造成任何安全问题。归集交易无法广播时，这笔资金只是暂时沉淀在收款智能合约中——资金流向仍被合约写死为你的归集地址，谁也改不动。补足 Gas 后，系统会自动恢复归集，把沉淀的资金清扫进你的归集地址。

配置项目

登录管理后台，进入 项目 → 项目列表，创建或编辑项目。项目是 API 对接的基本隔离单元，每个项目都有独立的 Appid 和 HMAC 密钥，用于接口鉴权与签名。请至少确认以下配置：

• IP 白名单：限制允许调用网关 API 的商户服务器 IP；测试阶段可使用 *，生产环境建议收窄到固定出口 IP 或网段。
• 通知地址：用于接收账单收款、充值收款等 Webhook 事件；如暂未配置，项目会显示为未就绪。
• 收款归集地址：业务资金最终流入的地址。启用智能合约或充值收款前必须配置 EVM 多签地址；该地址会写入智能合约规则，一旦设置不可修改。EVM 归集地址须为 checksum 地址，Tron 归集地址须为 Base58 地址。

配置完成后，即可参考 API 对接 接入账单收款、充值收款与 Webhook 回调。

运维

常用命令

停止服务（会停止并移除生产容器，不会删除数据库数据卷）：

docker compose down

启动 / 重新拉起服务：

docker compose up -d

升级到最新版

以下命令会拉取 main 分支最新版并执行完整生产升级流程：

./scripts/upgrade.sh

Gas 维护

智能合约模式与充值收款依赖系统热钱包在对应链上发起合约部署与归集交易。请定期检查各启用链上系统钱包的原生资产余额，保持小额 Gas 储备。一旦 Gas 不足，合约部署或归集任务将无法广播——但这不影响资金安全，资金只是暂时沉淀在收款合约中，待补足 Gas 后系统会自动恢复归集。

风控复核

管理后台可直接查看账单收款、充值收款记录及独立的风险评估记录中的风险信息，便于运营人员进行人工复核、业务放行或进一步处置。账单收款、充值收款的 API 与 Webhook 输出也会携带 risk_level 与 risk_score，方便你的系统同步展示或接入自己的处置流程。

风控为异步执行。Webhook 首次投递时风险字段可能暂时为 null，不要把首次通知当作最终风控报告，必要时以后台风险评估记录或后续查询为准。

API 对接

网关地址与链码

所有 Django/DRF API 路由均不带尾部 /，示例中的路径请按原样请求。

自部署

API 网关地址即为 .env 中配置的 SITE_DOMAIN，例如 https://{你的域名}/v1/invoice；管理后台同域名访问。

Xcash 官方服务

公链 - chain

代币 - crypto

crypto 使用币种 symbol，一律大写。常见 symbol 如下：

上表仅为常见示例：EVM 链支持任意 ERC-20 代币，在后台添加代币合约地址并启用即可收款，可用 symbol 不止于此；Tron 当前仅放行 USDT 与原生 TRX。实际可用的链币组合取决于后台启用的链、币种与链上部署关系。测试项目只能使用测试网或本地链，非测试项目只能使用主网链。

认证与签名

除明确标注为公开的端点外，/v1/* 接口都需要 HMAC-SHA256 签名。在管理后台创建项目后，系统生成 appid（如 XC-A3BK7NMG）与 hmac_key。

请求头

XC-Appid: {appid}
XC-Timestamp: {unix_timestamp}
XC-Nonce: {unique_nonce}
XC-Signature: {hmac_signature}
Content-Type: application/json

签名计算

message   = XC-Nonce + XC-Timestamp + request_body
signature = HMAC-SHA256(message, hmac_key).hexdigest()

request_body 必须是实际发送的原始请求体字符串。GET 请求没有 body 时使用空字符串 ""。

Python 示例

import hashlib
import hmac
import json
import time
import uuid

appid = "XC-A3BK7NMG"
hmac_key = "your_hmac_key"

payload = {
    "out_no": "order-001",
    "title": "Premium Plan",
    "currency": "USD",
    "amount": "29.99",
}
body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
timestamp = str(int(time.time()))
nonce = str(uuid.uuid4())
signature = hmac.new(
    hmac_key.encode(),
    f"{nonce}{timestamp}{body}".encode(),
    hashlib.sha256,
).hexdigest()

headers = {
    "XC-Appid": appid,
    "XC-Timestamp": timestamp,
    "XC-Nonce": nonce,
    "XC-Signature": signature,
    "Content-Type": "application/json",
}

Node.js 示例

const crypto = require("crypto");

const appid = "XC-A3BK7NMG";
const hmacKey = "your_hmac_key";
const body = JSON.stringify({
  out_no: "order-001",
  title: "Premium Plan",
  currency: "USD",
  amount: "29.99",
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const signature = crypto
  .createHmac("sha256", hmacKey)
  .update(`${nonce}${timestamp}${body}`)
  .digest("hex");

响应与错误码

成功时直接返回业务 JSON。创建类接口通常返回 HTTP 201，查询类接口返回 HTTP 200。业务错误响应：

{
  "code": "1001",
  "message": "AppID无效",
  "detail": ""
}

框架级错误（如资源不存在 404、方法错误 405、限流 429）可能返回 DRF 默认格式 { "detail": "Not found." }。

接口列表

错误码

创建账单收款

POST /v1/invoice（需要签名）。创建一笔账单收款，成功后返回 pay_url，买家打开账单收款页完成选币、选链和付款。

请求参数

methods 规则

• 不传 methods：系统按项目配置生成当前可用的链币组合。
• 传入 methods：必须是系统生成组合的子集，否则返回无可用收款方式。
• currency 只决定 amount 的计价单位（法币），与买家实际支付的加密货币解耦——后者由 methods 限定。
• 买家最终应支付的链、币、地址与数量以账单页/查询接口返回的 chain、crypto、pay_address、pay_amount 为准，不要自行按 amount 推导链上付款数量。

请求示例

{
  "out_no": "order-20260602-001",
  "title": "Premium Plan",
  "currency": "USD",
  "amount": "29.99",
  "duration": 15,
  "methods": {
    "USDT": ["ethereum"],
    "USDC": ["base"]
  },
  "notify_url": "https://merchant.example.com/xcash/webhook",
  "return_url": "https://merchant.example.com/payment/success"
}

限定只允许买家使用某种稳定币（USD 计价 + methods 限定 USDT）：

{
  "out_no": "order-20260602-002",
  "title": "Contract Invoice",
  "currency": "USD",
  "amount": "100",
  "duration": 15,
  "methods": {
    "USDT": ["ethereum", "base"]
  },
  "notify_url": "https://merchant.example.com/xcash/webhook"
}

响应示例

{
  "appid": "XC-A3BK7NMG",
  "sys_no": "INV2606028X7K2P9Q",
  "out_no": "order-20260602-001",
  "title": "Premium Plan",
  "currency": "USD",
  "amount": "29.99",
  "methods": { "USDT": ["ethereum"], "USDC": ["base"] },
  "chain": null,
  "crypto": null,
  "crypto_address": null,
  "pay_address": null,
  "pay_amount": null,
  "pay_url": "https://app.xca.sh/pay/INV2606028X7K2P9Q",
  "started_at": "2026-06-02T12:00:00Z",
  "created_at": "2026-06-02T12:00:00Z",
  "expires_at": "2026-06-02T12:15:00Z",
  "notify_url": "https://merchant.example.com/xcash/webhook",
  "return_url": "https://merchant.example.com/payment/success",
  "payment": null,
  "status": "waiting",
  "risk_level": null,
  "risk_score": null
}

如果最终只剩一个收款组合，系统会在创建时自动选择，此时 chain、crypto、pay_address、pay_amount 可能已返回具体值。默认匿名限流 256/分钟。

查询账单收款

GET /v1/invoice/{sys_no}（公开接口，无需签名）。用于账单收款页或买家侧轮询状态，不返回 appid、out_no、notify_url。

关键响应字段

限流 60/分钟，按 sys_no + IP 维度。

获取充值收款地址

GET /v1/deposit/address（需要签名）。为项目下的终端客户获取充值收款地址，同一项目、同一 uid、同一链稳定返回同一地址。

虽然从实现上看，同一项目、单个 uid 的充值收款地址理论上可以在所有链之间共享；但为了语义清晰，建议按每个 chain + crypto 组合重新调用本接口获取地址，不要只把某个链或币种下取到的地址直接复用于其他组合。

请求示例

GET /v1/deposit/address?uid=user-10001&chain=base&crypto=USDC

GET 请求签名时 request_body 为空字符串。响应：

{
  "deposit_address": "0xAbCd1234..."
}

请求的链、币种与链上币种关系必须均已启用，且项目的测试/主网属性必须与链匹配。限流 60/分钟，按 appid + IP 维度。

Webhook 回调

Xcash 在账单收款或充值收款进入关键状态时向商户投递 Webhook。生产环境默认只允许投递到 HTTPS 公网地址，拒绝 http、localhost 和私有网段。

签名头

Xcash 原生协议事件使用 POST application/json，带 HMAC 头，签名算法与 API 请求一致：

XC-Appid: {appid}
XC-Nonce: {event_nonce}
XC-Timestamp: {unix_timestamp}
XC-Signature: {hmac_signature}
Content-Type: application/json

响应与重试

• 成功响应：HTTP 200，响应体去除首尾空白后等于 ok（EPay V1 通知为 success）。
• 单次请求超时 5 秒；只有网络错误或 5xx 会按指数退避重试，2xx 非 200、3xx、4xx 不重试。
• 商户应验证签名，并对同一 XC-Nonce 做幂等处理。项目通知开关必须开启，否则即使传入独立 notify_url 也不投递。

账单收款 Webhook

账单进入 completed 后发送一次通知（confirmed=true）：

{
  "type": "invoice",
  "data": {
    "sys_no": "INV2606028X7K2P9Q",
    "out_no": "order-20260602-001",
    "crypto": "USDT",
    "chain": "ethereum",
    "pay_address": "0xAbCd1234...",
    "pay_amount": "29.870001",
    "hash": "0xabc123...",
    "block": 12345678,
    "confirmed": true,
    "risk_level": null,
    "risk_score": null
  }
}

充值收款 Webhook

充值对应链上转账达到确认要求后发送一次通知（confirmed=true）：

{
  "type": "deposit",
  "data": {
    "sys_no": "DXC2606026K9P2QWX",
    "uid": "user-10001",
    "chain": "base",
    "block": 12345678,
    "hash": "0xabc123...",
    "crypto": "USDC",
    "amount": "500",
    "confirmed": true,
    "risk_level": null,
    "risk_score": null
  }
}

易支付 V1 兼容

Xcash 提供易支付 V1 兼容入口，适配常见 Typecho、WordPress、Discuz 等易支付插件。EPay 入口不使用 Xcash HMAC 头，使用 EPay 自有 MD5 签名。

创建订单

GET /epay/submit.php 或 POST /epay/submit.php。POST 请使用 application/x-www-form-urlencoded 或 multipart/form-data 表单编码，不要发送 JSON。核心参数：pid、out_trade_no、notify_url、name、money、sign、sign_type=MD5，可选 currency（默认 CNY）、param、return_url、type。

EPay 签名

1. 去掉 sign、sign_type；
2. 去掉值为 null 或空字符串的字段；
3. 按字段名 ASCII 升序排序；
4. 拼接 key=value，字段间用 & 连接；
5. 末尾直接追加 secret_key；
6. 对整体取 MD5，输出小写十六进制。

import hashlib

params = {
    "pid": "1001",
    "out_trade_no": "order-001",
    "notify_url": "https://merchant.example.com/epay/notify",
    "return_url": "https://merchant.example.com/epay/return",
    "name": "Premium Plan",
    "money": "29.99",
    "sign_type": "MD5",
}

filtered = {
    k: str(v)
    for k, v in params.items()
    if k not in {"sign", "sign_type"} and v not in (None, "")
}
sign_string = "&".join(f"{k}={v}" for k, v in sorted(filtered.items()))
secret_key = "your_epay_secret_key"
params["sign"] = hashlib.md5(
    f"{sign_string}{secret_key}".encode("utf-8"),
    usedforsecurity=False,
).hexdigest()

响应与通知

• 成功：HTTP 302，重定向到账单收款页 /pay/{sys_no}；失败：HTTP 400，纯文本 fail。
• 账单完成后，Xcash 向 notify_url 发送 GET 通知，trade_status=TRADE_SUCCESS；商户响应 HTTP 200 且响应体为 success 视为成功。
• 核心发货逻辑应以异步通知为准，同步跳转只表示账单收款页流程结束。

更多

常见问题与支持

账单收款完整流程

商户服务器 -> Xcash:  POST /v1/invoice
Xcash -> 商户服务器:  返回 sys_no / pay_url
买家 -> Xcash:        打开 pay_url，选币、选链
买家 -> 区块链:        转账
Xcash -> 商户服务器:  Webhook invoice
商户服务器 -> Xcash:  ok

充值收款完整流程

商户服务器 -> Xcash:  GET /v1/deposit/address
Xcash -> 商户服务器:  返回 deposit_address
商户系统 -> 用户:      展示 deposit_address
用户 -> 区块链:        转账
Xcash -> 商户服务器:  Webhook deposit
商户服务器 -> Xcash:  ok

Xcash 收费吗？

开源版完全免费（MIT 协议），零平台手续费，你只承担链上 Gas。如不想自行部署，可使用官方云服务（按套餐订阅），详见 定价。无论哪种方式，收款都经智能合约直达你的归集地址。

资金会经过 Xcash 吗？

不会。资金流向在智能合约里写死为你的归集地址，Xcash 全程不持有、不经手、也无法动用你收取的加密货币。详见 非托管安全模型。

获取支持

遇到部署或对接问题，欢迎在 GitHub 提交 Issue，或邮件联系 [email protected] 获取商业技术支持。也可以参考仓库内的 README 与 API.md。