目录

Xcash 使用文档

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

Xcash 是开源、自部署、非托管的加密货币收款网关。收款经智能合约直达你自己的归集地址,Xcash 全程不托管资金。本文档涵盖项目介绍、技术原理、部署、运维与 API 对接,跟着读完即可上线一套属于你自己的收款基础设施。

项目介绍

什么是 Xcash

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

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

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

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

账单收款 vs 充值收款

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

  • 账单收款:账单式收款。每笔交易创建一张定额、限时的账单,买家付款后账单完成,适合电商下单、订阅计费等一次性收款场景。账单收款支持钱包直收与智能合约两种模式:既可直接收进项目钱包,也可使用合约收款地址并在确认后自动归集。
  • 充值收款:交易所式充值收款。为每个用户分配专属充值收款地址(EVM 各链共用同一地址),实时监控;用户可随时转入、区块确认后入账,无需逐笔创建订单,适合需要维护用户余额的钱包、交易类业务。
维度账单收款充值收款
形态定额、限时的一次性账单用户专属、长期有效的收款地址
典型场景电商下单、订阅计费钱包充值、交易所入金
是否需创建订单每笔都要创建账单仅首次获取地址,之后随时转入
金额账单指定金额任意金额
通知账单完成时一次 Webhook每笔到账确认后 Webhook

核心特性

特性说明
账单收款定额、定时的账单式收款,适合电商下单、订阅计费等场景
充值收款为每个用户分配专属充值收款地址,随时转入、即时入账,体验同交易所
资金非托管收款经智能合约直达你的钱包,Xcash 全程不托管资金
零平台手续费不按交易抽成,只承担链上微量 Gas
多链多币种覆盖主流 EVM 链,支持任意 ERC-20 代币;Tron 支持 USDT 与 TRX
多商户多项目单实例隔离管理多个商户与项目
智能合约账单可使用合约收款地址,付款确认后自动归集到你的归集地址
链上风控可选接入 MistTrack,对账单收款、充值收款的来源地址做风险评分
Webhook 回调实时推送账单收款、充值收款事件
兼容易支付支持标准易支付 V1 协议,便于平滑迁移
Docker 部署Docker Compose 一键部署生产服务

链与币种支持

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

功能ETHBNBArbitrumBaseTronPolygonOptimismAvalanche / Linea / Scroll
账单收款是是是是是是是是
充值收款是是是是是是是是

系统默认预置 Ethereum、BNB Smart Chain、Polygon、Arbitrum、Optimism、Base、Tron 以及测试网 Sepolia、Nile;Avalanche、Linea、Scroll 需在后台手动添加。以上之外的链需要改代码接入,无法仅靠后台配置启用。

代币方面:

链类型原生资产代币标准当前支持范围
EVMETH、BNB、POL 等(用于支付 Gas)ERC-20支持任意 ERC-20 代币,按业务需要接入 USDT、USDC 或其他链上资产;用于账单收款的代币需有行情价格源(USDT、USDC、DAI 以外的代币须配置 CoinGecko ID)
TronTRXTRC-20当前放行 USDT 与原生 TRX;其他 TRC-20 暂不作为收款资产

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

技术原理

资金非托管安全模型

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

即使部署 Xcash 的服务器被攻破、数据库被拖库、密钥泄露,只要你的归集地址不被篡改,资金都不会有任何安全风险。恢复服务后,用户完成账单收款或充值收款的款项仍会流入你的归集地址,攻击者无能为力。
买家发起付款
→
收款智能合约资金流向锁定
→
你的归集地址私钥只在你手中
Xcash 控制面 · API / Worker / 数据库 只负责匹配账单、流转状态、推送通知,不在资金路径上。
攻击者 即便完全控制 Xcash 系统,也改不动合约里锁定的资金流向。

之所以能做到,是因为:

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

系统架构

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

  • Xcash API:对外提供创建账单收款、查询状态、获取充值收款地址等接口,是商户与买家的统一入口。
  • Xcash Worker:负责链上交易监听、状态流转与资金归集调度,是连接区块链与业务状态的核心。
  • Xcash 钱包引擎:基于 BIP44 HD 钱包派生系统热钱包地址,为合约部署、归集等系统交易签名。助记词以 AES-256-GCM 加密存入数据库,密钥保存在 .env,二者须成对备份。
  • Xcash Webhook:在账单收款、充值收款进入关键状态时,向商户异步推送事件。

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

层技术
后端Django 5.2 + Django REST Framework
任务队列Celery + Redis
数据库PostgreSQL
区块链交互web3.py(EVM)、TronGrid HTTP API(Tron)
钱包派生BIP44 HD 钱包(bip-utils)
账单收款页React 19 + Vite + Tailwind CSS
部署Docker Compose

两种账单收款模式

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

  • 钱包直收(Differ):系统使用项目配置的钱包直收地址收款。买家应付金额(pay_amount)向上取整到 0.01;同一金额在所有钱包地址上都被待支付账单占用时,再加 0.01 的尾差(最多 +0.99)来区分账单,因此配置多个钱包地址可让更多买家按原价付款。资金直接进入你的钱包,无需归集。EVM 链的钱包直收不支持原生币(ETH、BNB 等),Tron 支持 TRX。
  • 智能合约(VaultSlot):系统从项目的合约地址池中为账单分配收款地址。不同金额的账单可共用同一地址,同一地址上的同一金额同时只分配给一张账单,因此无需微调金额。买家付款确认后,系统调度归集,把资金清扫进项目配置的对应链类型归集地址。

EVM 与 Tron 均可用于账单收款。收款模式在后台按链类型(EVM / Tron)分别配置,默认均为钱包直收;选择智能合约的链类型,必须配置对应的归集地址。充值收款不区分这两种模式,始终采用智能合约。

智能合约原理

智能合约(VaultSlot)是 Xcash 最具特色的机制,理解它有助于理解整套安全模型:

  • 地址可提前确定:每个合约收款地址由「工厂合约 + 实现合约 + 你的归集地址 + 一个 salt」确定性推导得出(CREATE2 式预测)。也就是说,在合约真正部署到链上之前,地址就已经算出来了,买家可以直接向这个「反事实地址」付款。
  • 资金流向锁定:部署时,你的归集地址被写进合约。合约的归集方法 collect() 只能把余额清扫到这个锁定的归集地址,没有任何权限可以改变流向。
  • 归集任何人可触发:因为 collect() 只会把钱送往锁定的归集地址,它不做调用者权限校验——触发者只承担 Gas。因此 Xcash 全局只需维护一个系统热钱包来支付部署与归集的 Gas。
  • 原生币与代币:归集原生币时合约用 address(0) 表示清扫当前原生币余额,归集 ERC-20 时传入对应代币合约地址。代币与 Tron 原生 TRX 可直接打到未部署的反事实地址;EVM 原生币要靠已部署合约的 receive() 事件识别,因此系统会在暴露这类地址时提前部署合约。
正因为归集地址被写进合约、且 collect() 无权重定向,连 Xcash 自己都无法把买家的付款转去别处。这就是「服务器被攻破也偷不走钱」的技术根源。

Gas 成本与资金归集

启用智能合约收款后,账单收款会使用合约地址池,每个充值收款用户也会拥有专属合约地址。地址很多并不意味着每笔收款都要立刻单独付一次 Gas 去归集。Xcash 内置两道归集闸门,把归集次数和 Gas 开销压到最低:

  • 归集延迟:收款确认后不会立即归集,而是等待可配置的延迟窗口再尝试。EVM 链默认 60 分钟,Tron 链默认 6 小时;同一地址在窗口内的多笔入账会合并成一次归集。
  • 归集金额门槛:到期尝试归集时,若该地址该币种余额价值低于门槛(默认 1 USD),系统会跳过本次并继续累积,避免为粉尘余额支付更高 Gas。

只有「延迟到达」和「金额达标」同时满足,系统才会自动发起归集交易。未达标的地址不会被丢弃,后续入账会重新评估,攒够门槛后再归集。归集延迟按链类型(EVM / Tron)分别设置,金额门槛全局统一,均在管理后台 系统 → 运行参数 中调整。

Xcash 的收款合约保持极简:每次归集的核心动作基本等同于对应代币的一次普通转账,所以单次归集 Gas 消耗接近普通转账本身,几乎没有额外合约开销。

归集本身也是无需许可、与安全无关的操作:collect() 没有调用者权限校验,任何账户都能触发并自付 Gas;资金流向早已被合约锁定为你的归集地址,谁来触发都无法改变结果。因此你只需为系统钱包保留少量原生资产用于支付归集 Gas,无需为每笔支付或充币单独操心 Gas。

充值收款机制

充值收款面向需要维护用户余额的业务。你通过 API 为某个终端用户(uid)在某条链上申请一个充值收款地址;同一项目、同一 uid、同一链会稳定返回同一个合约地址(同链各币种共用;EVM 各链地址相同,Tron 单独一个),便于展示给用户长期使用。

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

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

链上风控(AML)

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

  • 账单收款:账单确认完成后,对付款方地址做异步风险查询,把风险等级与分数同步到账单记录。
  • 充值收款:充值到账确认后,对转入资金的来源地址做异步风险查询,把风险等级与分数同步到充值记录。

风险结果会写入独立的风险评估记录(查询状态、目标类型、来源地址、交易哈希、风险等级、风险分数),管理后台可直接查看,便于人工复核与处置。账单查询接口会返回最新的 risk_level 与 risk_score。Webhook 也带这两个字段,但它是发送时的快照:筛查在确认之后才异步执行,所以通常为 null,筛查完成后也不会补发通知。

风控默认关闭。需在管理后台 系统 → 运行参数 中开启「AML 筛查」,并填写 MistTrack OpenAPI API Key(优先使用)或 QuickNode MistTrack Endpoint(未配置前者时回退使用);只有价值高于「AML 查询阈值」的账单与充值才会查询。

部署

部署前准备

开始部署前,请准备以下条件:

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

性能档位

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

性能模式硬件配置可承载链数量
low1 核 / 2 GB2 – 3 条 EVM 链
medium4 核 / 8 GB8 – 15 条 EVM 链
high8 核 / 16 GB15 – 30 条 EVM 链
env
PERFORMANCE=medium

快速开始

1. 克隆项目

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

2. 初始化环境变量

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

bash
./scripts/init_env.sh

3. 设置访问域名

编辑 .env 设置 SITE_DOMAIN:

env
SITE_DOMAIN=xcash.example.com

请确保该域名的 DNS 已解析到服务器 IP,并配置 Nginx 或 Caddy 等反向代理,将流量转发至 http://127.0.0.1:6688,同时由反向代理负责 TLS。

反向代理必须转发真实客户端 IP 与请求协议。商户 IP 白名单与全部限流都按真实 IP 判定,HSTS 与 Secure Cookie 依赖请求协议;缺少这两项时,配置了白名单的商户会被全部拒绝,所有限流也会退化为全站共用一个桶。

Caddy 会自动转发 X-Forwarded-For 与 X-Forwarded-Proto,无需额外设置:

Caddyfile
xcash.example.com {
    reverse_proxy 127.0.0.1:6688
}

Nginx 需显式设置 X-Real-IP 与 X-Forwarded-Proto。不要只用追加语义的 X-Forwarded-For,它最左侧的值可被客户端伪造:

nginx
location / {
    proxy_pass http://127.0.0.1:6688;
    proxy_set_header Host $host;
    # 真实客户端 IP,必须用 $remote_addr(覆写语义)
    proxy_set_header X-Real-IP $remote_addr;
    # 原始请求协议,HSTS 与 Secure Cookie 依赖它
    proxy_set_header X-Forwarded-Proto $scheme;
}

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

env
ADMIN_PATH=secure-admin

4. 启动服务

bash
docker compose up -d

应用镜像发布在 ghcr.io/xca-sh/xcash(公开镜像),首次启动时自动拉取,无需本地构建。启动脚本会先执行数据库迁移,并补齐默认链、币种等基础数据。

首次启动时,如果数据库内还没有任何管理员账号,系统会自动创建后台账号 admin,密码取自 .env 中的 DJANGO_DEFAULT_SUPERUSER_PASSWORD:它由 init_env.sh 随机生成,执行时会打印一次。

请把该密码存入密码管理器。生产环境下该口令若为空、短于 12 位或等于仓库内置的示例值,系统会拒绝创建管理员并中止启动。强烈建议同时设置 ADMIN_PATH 隐藏后台入口。

配置链 RPC

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

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

系统钱包充值 Gas

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

Tron 链的部署与归集只消耗系统钱包的储备能量:每次广播前会重新模拟,可用能量不足时等待补充,不会燃烧 TRX 换取能量。因此需要为系统钱包准备能量(如质押 TRX),并保留少量 TRX 支付带宽不足时的费用。

系统钱包只用于平台基础设施交易,例如合约部署、归集交易等需要由系统主动发起的链上操作;业务收款资金仍按合约规则流向你的归集地址。这里不需要存入业务资金,只需保留覆盖近期操作的小额 Gas,避免因 Gas 不足导致合约部署或归集任务无法广播。归集不会每笔收款各触发一次,系统会通过归集延迟与金额门槛批量归集,详见 Gas 成本与资金归集。
即便系统钱包 Gas 不足,也不会造成任何安全问题。归集交易无法广播时,这笔资金只是暂时沉淀在收款智能合约中——资金流向仍被合约锁定为你的归集地址,谁也改不动。补足 Gas 后,系统会自动恢复归集,把沉淀的资金清扫进你的归集地址。

配置项目

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

  • IP 白名单:限制允许调用网关 API 的商户服务器 IP;测试阶段可使用 *,生产环境建议收窄到固定出口 IP 或网段。
  • 通知地址:用于接收账单收款、充值收款等 Webhook 事件;如暂未配置,项目会显示为未就绪。
  • 收款归集地址:智能合约收款的资金最终流入的地址,按链类型分别配置。启用智能合约账单收款或充值收款前,必须配置对应链类型(EVM / Tron)的归集地址。该地址会写入智能合约,一旦设置不可修改,强烈建议使用多签钱包。EVM 归集地址须为 checksum 地址,Tron 归集地址须为 Base58 地址。
  • 钱包直收地址:使用钱包直收模式时,在项目页「钱包直收地址」中按链类型添加你自己的收款钱包。

项目至少要有一个启用的钱包直收地址或归集地址,且已配置 IP 白名单与通知地址,才算就绪;未就绪时 API 返回 1004。

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

运维

常用命令

停止服务(会停止并移除生产容器,不会删除数据库数据卷):

bash
docker compose down

启动 / 重新拉起服务:

bash
docker compose up -d

升级到最新版

确认位于 main 分支后,先 git pull 更新 compose 文件与脚本,再执行升级脚本:

bash
git pull
./scripts/upgrade.sh

脚本会拉取最新镜像、按需执行迁移演练、平滑停止旧服务、执行生产迁移并启动新版,全部就绪检查通过才报告成功。镜像拉取在停止任何服务之前进行,失败不影响线上服务,重跑即可。脚本要求工作区干净,不会自动切换分支或更新代码。

Gas 维护

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

风控复核

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

风控在确认之后异步执行。Webhook 发送时风险字段通常为 null,筛查完成后也不会补发通知;账单请以查询接口为准,充值请以后台风险评估记录为准。

API 对接

网关地址与链码

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

自部署

API 网关地址即为 .env 中配置的 SITE_DOMAIN,例如 https://{你的域名}/v1/invoice;管理后台同域名访问,设置了 ADMIN_PATH 时位于 /{ADMIN_PATH}。

Xcash 官方服务

用途URL
API 网关https://pay.xca.sh(如 /v1/invoice)
EPay 网关https://pay.xca.sh/epay/submit.php
SaaS 控制台https://dash.xca.sh

公链 - chain

名称API 参数类型Gas 代币Chain ID
EthereumethereumEVMETH1
BNB Smart ChainbscEVMBNB56
Polygon PoSpolygonEVMPOL137
Arbitrum Onearbitrum-oneEVMETH42161
OptimismoptimismEVMETH10
BasebaseEVMETH8453
Avalanche C-ChainavalancheEVMAVAX43114
LinealineaEVMETH59144
ScrollscrollEVMETH534352
TrontronTronTRX-
SepoliasepoliaEVM 测试网ETH11155111
NilenileTron 测试网TRX-
Anvil LocalanvilEVM 本地链ETH31337

代币 - crypto

crypto 使用币种 symbol,一律大写。常见 symbol 如下:

名称API 参数类型说明
Tether USDUSDT稳定币ERC-20 / TRC-20,最常用收款币种
USD CoinUSDC稳定币ERC-20,多条 EVM 链可用
DaiDAI稳定币ERC-20
EtherETH原生币Ethereum 及 Arbitrum / Optimism / Base 的原生 Gas 币
BNBBNB原生币BNB Smart Chain 的原生 Gas 币
PolygonPOL原生币Polygon PoS 的原生 Gas 币
TRONTRX原生币Tron 的原生 Gas 币

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

法币 - currency

账单的计价法币,系统内置 USD、CNY、EUR、JPY、HKD,区分大小写。

认证与签名

除公开端点 GET /v1/invoice/{sys_no} 与 GET /v1/metadata 外,/v1/* 接口都需要 HMAC-SHA256 签名。在管理后台创建项目后,系统生成 appid(如 XC-A3BK7NMG)与 32 位 hmac_key。

请求头

http
XC-Appid: {appid}
XC-Timestamp: {unix_timestamp}
XC-Nonce: {unique_nonce}
XC-Signature: {hmac_signature}
Content-Type: application/json
Header说明
XC-Appid项目 AppID
XC-Timestamp当前 Unix 时间戳(秒),与服务器时间相差不得超过 300 秒
XC-Nonce随机串,必填;同一 AppID 下 300 秒内不可重复
XC-SignatureHMAC-SHA256 签名,小写十六进制

签名计算

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

request_body 必须是实际发送的原始请求体字符串,签名后不得再重新序列化。GET 请求使用空字符串 "",查询参数不参与签名。

签名接口按以下顺序校验,命中即返回:1001 AppID 无效 → 1005 项目已停用 → 1008 时间戳缺失或超窗 → 1004 项目未就绪 → 1002 IP 不在白名单 → 1003 签名错误 → 1000 缺少 Nonce → 1009 Nonce 重复。

Python 示例

python
import hashlib
import hmac
import json
import time
import uuid

import requests

url = "https://pay.xca.sh/v1/invoice"
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",
}

# 发送的必须是上面签名用的同一个 body(encode 只是转为 UTF-8 字节);
# 不要用 json=payload,requests 会重新序列化导致验签失败
requests.post(url, data=body.encode("utf-8"), headers=headers)

Node.js 示例

javascript
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;金额一律为字符串,时间为 ISO 8601 UTC。业务错误响应:

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

请以 code 判断错误类型:message 会随 Accept-Language 本地化,detail 可能是字符串或对象(参数错误时为各字段的错误详情)。框架级错误(如资源不存在 404、方法错误 405、限流 429)返回 { "detail": "..." }。

接口列表

方法路径说明签名限流
POST/v1/invoice创建账单收款需要256/分钟,按 IP
GET/v1/invoice/{sys_no}查询账单收款不需要120/分钟,按 sys_no + IP
GET/v1/deposit/address获取充值收款地址需要60/分钟,按 appid + IP
GET/v1/metadata链与币种元数据不需要256/分钟,按 IP
GET/POST/epay/submit.php易支付 V1 创建订单EPay MD560/分钟,按 IP

错误码

错误码说明HTTP
1000参数错误400
1001AppID 无效400
1002IP 不在白名单403
1003签名错误403
1004项目未就绪(detail 列出缺失配置)400
1005项目已停用403
1007out_no 已存在且参数不一致400
1008时间戳缺失或超出 300 秒400
1009Nonce 重复400
2000 / 2001 / 2002无效链 / 无效币种 / 该链不支持此币种400
4000 / 4001无效 uid / 项目未配置该链类型的归集地址400
4002充值用户数达到账户上限(仅官方云服务)403
5000 / 5008 / 5009不支持的计价法币 / 无可用支付方式 / 待支付账单过多400
6004账户已冻结(仅官方云服务)403

创建账单收款

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

请求参数

字段类型必填说明
out_nostring是商户订单号,最长 32 位,项目内唯一(与易支付的 out_trade_no 共用编号空间)
titlestring是账单标题,最长 32 位
currencystring是计价法币代码(如 USD、CNY),收款加密货币由 methods 指定
amountstring是计价金额,0.01 – 1000000,最多 2 位小数("10.000" 视为 3 位,会被拒绝)
durationinteger否有效期分钟数,5 – 30,默认 10
methodsobject否限定收款方式,格式 {"币种": ["链码"]}
notify_urlstring否账单级 Webhook 地址,优先于项目默认通知地址
return_urlstring否账单完成后的同步跳转地址

规则

  • methods:不传时使用项目当前全部可用的链币组合;传入时必须是其子集,否则返回 5008(未知币种 2001,未知链 2000)。响应中的 methods 是最终生效的组合。
  • 计价与支付解耦:currency 只决定 amount 的法币计价单位,买家实际支付的加密货币由 methods 限定。
  • 付款金额:买家应付以 pay_amount 为准,它由汇率换算得出,并可能带有区分账单的尾差,不要自行按 amount 推算;链上到账金额须与 pay_amount 完全相等才会入账。
  • 幂等:out_no 已存在时,若 title、currency、amount、notify_url、return_url 与原账单完全一致,返回原账单(HTTP 200);否则返回 1007。
  • 待支付上限:项目 waiting 状态账单达到 100 笔时,拒绝新建(5009)。

请求示例

json
{
  "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):

json
{
  "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"
}

响应示例(HTTP 201)

json
{
  "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://pay.xca.sh/pay/INV2606028X7K2P9Q",
  "started_at": "2026-06-02T12:00:00.123456Z",
  "created_at": "2026-06-02T12:00:00.123456Z",
  "expires_at": "2026-06-02T12:15:00.123456Z",
  "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
}

未传的 notify_url / return_url 返回空字符串 ""。如果最终只剩一个收款组合,系统会在创建时自动选择,此时 chain、crypto、pay_address、pay_amount 已有值。

查询账单收款

GET /v1/invoice/{sys_no}(公开接口,无需签名)。用于账单收款页或买家侧轮询状态,不返回 appid、out_no、notify_url;账单不存在时返回 404。

关键响应字段

字段说明
sys_no系统单号;INV + 6 位日期(YYMMDD) + 8 位大写字母数字
chain已选链,未选时为 null
crypto已选币种,未选时为 null
pay_address收款地址
pay_amount买家应付加密货币数量
payment_uriEVM 链可用的 EIP-681 支付 URI;非 EVM 或无法精确编码金额时为 null
statuswaiting / completed / expired
payment匹配到的链上转账对象,含 hash、block、from/to、amount、status(confirming / confirmed)、confirm_progress 等
risk_levelAML 风险等级:Low / Moderate / High / Severe
risk_scoreAML 风险分数

状态说明

  • waiting:待支付。链上已出现匹配转账但未确认时,payment 有值、status 仍为 waiting。
  • completed:已确认,终态。
  • expired:已过期,但不是终态:过期前已上链的付款在过期后确认,账单仍会转为 completed 并发送 Webhook。
  • 账单美元价值低于项目「快速确认阈值」(默认 10 USD)时,观察到付款即确认,不等待区块确认数。

获取充值收款地址

GET /v1/deposit/address(需要签名)。为项目下的终端客户获取充值收款地址,同一项目、同一 uid、同一链稳定返回同一地址,与 crypto 无关。

虽然 EVM 各链对同一 uid 会返回相同地址,仍请按每个 chain + crypto 组合调用本接口获取地址,不要把某个链或币种下取到的地址直接复用于其他组合:EVM 原生币(ETH、BNB、POL 等)必须以 crypto=原生币 调用过本接口,系统才会部署该地址的合约,部署前到账的原生币要等部署完成后才入账。

字段类型必填说明
uidstring是终端客户标识,1 – 128 位,仅字母、数字、下划线、中划线
chainstring是链 code,如 ethereum、base、tron
cryptostring是币种 symbol,如 USDT

请求示例

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

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

json
{
  "deposit_address": "0xAbCd1234..."
}
  • 请求的链、币种与链上币种关系必须均已启用,且项目的测试/主网属性必须与链匹配;Tron 仅支持 USDT 与 TRX;须已配置对应链类型的归集地址(否则返回 4001)。
  • EVM 原生币充值地址是合约,付款方转账的 gas limit 必须高于 21000(由钱包自动估算即可),写死 21000 的转账会失败。
  • 常见错误:4000 uid 非法;2000 链不存在、未启用、与项目测试属性不符或不支持该币种充值;2001 币种不存在或未启用;2002 该币未在此链启用。

Webhook 回调

Xcash 在账单收款完成或充值收款到账时向商户投递 Webhook。账单事件优先投递到创建账单时传入的 notify_url,为空时使用项目通知地址;充值事件使用项目通知地址。默认只允许投递到 HTTPS 公网地址,http、localhost 与内网地址直接判定失败(自部署可用 WEBHOOK_ALLOW_INTERNAL_TARGETS=true 放开)。

签名头

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

http
XC-Appid: {appid}
XC-Nonce: {event_nonce}
XC-Timestamp: {unix_timestamp}
XC-Signature: {hmac_signature}
Content-Type: application/json
  • 验签必须使用收到的原始请求体,不要解析后再序列化(JSON 字段顺序与空格都不保证)。
  • XC-Nonce 在同一事件的多次重试中保持不变,请用它做幂等去重;XC-Timestamp 为每次投递的发送时间。

响应与重试

  • 成功响应:HTTP 200,响应体去除首尾空白后等于 ok(区分大小写;EPay V1 通知为 success)。单次请求超时 5 秒。
  • 可重试:网络错误或超时、5xx、408、425、429。其余情况直接判定失败、不再重试,包括返回 200 但响应体不符、非 200 的 2xx、3xx 与其他 4xx。
  • 默认最多投递 5 次(含首次),指数退避约 4 / 8 / 16 / 32 秒(单次上限 120 秒),可在后台「系统 → 运行参数」调整;失败事件可在后台「通知 → 通知事件」中重新投递。
  • 项目通知开关关闭或投递地址为空时,事件挂起,每 10 分钟重试一次,同样计入投递次数。
  • 重试窗口很短,账单状态请以查询接口兜底对账。

账单收款 Webhook

账单进入 completed 后发送一次通知(confirmed=true):

json
{
  "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);后台已停用的币种到账只入账、不发送 Webhook:

json
{
  "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
  }
}

risk_level / risk_score 是发送时的快照。AML 筛查在确认后异步执行,因此 Webhook 中通常为 null,筛查完成后也不会补发通知。

易支付 V1 兼容

Xcash 提供易支付 V1 兼容入口,适配常见 Typecho、WordPress、Discuz 等易支付插件。EPay 入口不使用 Xcash HMAC 头,使用 EPay 自有 MD5 签名。WooCommerce 商城请直接使用官方 WooCommerce 插件。

创建订单

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。

  • money 范围 0.01 – 1000000,最多 2 位小数;out_trade_no 最长 64 位,项目内唯一,与 /v1/invoice 的 out_no 共用编号空间。
  • type 不限定链或币种,买家可在支付页选择项目全部可用的支付方式;账单有效期固定 15 分钟。
  • 相同 out_trade_no 重复提交且订单参数完全一致时,返回同一账单;参数不一致则失败。
  • pid 与 secret_key:官方云服务在控制台查看;自部署在后台项目页的「EPay 配置」中添加。

EPay 签名

  1. 去掉 sign、sign_type;
  2. 去掉值为 null 或空字符串的字段;
  3. 按字段名 ASCII 升序排序;
  4. 拼接 key=value,字段间用 & 连接;
  5. 末尾直接追加 secret_key;
  6. 对整体取 MD5,输出小写十六进制。
python
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(不返回具体原因);限流:HTTP 429。
  • 账单完成后,Xcash 向 notify_url 发送 GET 通知,参数为 pid、trade_no(即 sys_no)、out_trade_no、type、name、money、trade_status=TRADE_SUCCESS、param(有值才返回)、sign_type、sign,签名算法同上。商户响应 HTTP 200 且响应体为 success 视为成功,重试规则同 Webhook。
  • 核心发货逻辑应以异步通知为准,同步跳转只表示账单收款页流程结束。

插件

WooCommerce 插件

官方 Xcash for WooCommerce 插件已上架 WordPress.org 插件目录。WooCommerce 商城无需编写代码即可接入账单收款:插件为每笔订单创建 Xcash 账单,把买家引导到账单收款页完成付款,再通过签名 Webhook 自动把订单标记为已付款。

环境要求

依赖最低版本
WordPress5.8
WooCommerce5.0
PHP7.4

同时兼容 WooCommerce 区块结账(Checkout Blocks)、经典短代码结账,以及 HPOS 高性能订单存储。

安装

  1. 登录 WordPress 后台,进入 插件 → 安装插件。
  2. 搜索 Xcash for WooCommerce,点击「立即安装」,完成后点击「启用」。
请优先从 WordPress 后台或 WordPress.org 插件页 安装官方插件:新版本会直接出现在后台的更新列表里,一键即可升级。

配置

进入 WooCommerce → 设置 → 付款,启用 Xcash 并点击「管理」:

设置项说明
App ID / HMAC 密钥在 控制台 的项目设置中复制
网关地址默认 https://pay.xca.sh,使用官方服务时保持默认即可
计价法币自动跟随 WooCommerce 商店货币,须为 USD、CNY、EUR、JPY、HKD 之一
允许的收款方式可选,JSON 格式限定链币组合,如 {"USDT": ["ethereum", "tron"]};留空则使用项目全部可用组合
支付时长账单有效期,5 – 30 分钟,默认 20
标题与描述结账页向买家展示的支付方式名称与说明

保存后点击 「测试配置」,无需真实下单即可校验凭证、商店货币与收款方式是否可用。项目本身也需处于就绪状态(见 配置项目),IP 白名单需包含 WordPress 服务器的出口 IP。

Webhook

插件在创建账单时会自动把 https://你的站点/?wc-api=xcash_webhook 作为账单级 notify_url 传给 Xcash,无需手动填写。收到通知后插件按 HMAC 签名验签、按 Nonce 与账单号幂等去重,处理成功返回 ok,并在订单详情页展示链、币种、金额、交易哈希等支付信息。

  • 请保持控制台中项目的通知开关处于开启状态;站点须能通过 HTTPS 公网地址访问。
  • 投递失败的通知可在控制台重新发送。

排查

  • 「测试配置」失败时,依次检查凭证是否填写、商店货币是否受支持、收款方式 JSON 是否合法且在项目中已启用。
  • 开启调试日志后,可在 WooCommerce → 状态 → 日志 查看插件日志。
  • 站点语言为简体中文时,插件界面自动显示中文,其他语言默认英文。

更多

常见问题与支持

账单收款完整流程

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

充值收款完整流程

text
商户服务器 -> 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。