Goncafer47/Stablecoin-Payment-Gateway · 上手攻略

仓库：Goncafer47/Stablecoin-Payment-Gateway
链接：https://github.com/Goncafer47/Stablecoin-Payment-Gateway
分类：支付基础设施 · x402 协议
作者：Tom
更新：2026-09-27

是什么

Self-hosted（自托管）、非托管（non-custodial）的稳定币支付网关，支持 x402 协议，让任何 HTTP 端点摇身一变成为「付费 API」，开发者收款不再依赖 Stripe/PayPal 等中心化平台。用户付的是 USDC/USDT/PYUSD/DAI，资金直接进你自己的链上钱包，平台抽成 0%、无需 KYC。

技术核心是 HTTP 402 状态码的复兴——x402 将「付款验证」嵌入标准 HTTP 请求链，任何语言、任何框架都能通过添加一个 402 响应和 X-PAYMENT 头部来实现付费。

解决什么问题

开发者收款难：想做付费 API 或 SaaS，没有合适渠道；信用卡通道费率 0.5–1%、有 KYC、资金由平台保管
跨境支付摩擦：传统跨境汇款慢、费用高、审核严；稳定币转账 3–5 分钟到账、费用极低
微支付空白：Stripe 等不适合小额支付（最低 $0.50–1.00）；x402 支持按请求计费，适合 AI API、文件下载、内容访问等场景
支付数据不透明：传统平台扣点不透明；自托管网关所有交易数据在自己手里，可导出 CSV/JSON

快速安装

环境要求

Python 3.10+
pip（建议最新）
EVM 钱包地址（或 xpub）用于接收结算
可选：自己的 x402 facilitator 用于生产环境主网结算

Windows

git clone https://github.com/Goncafer47/Stablecoin-Payment-Gateway.git
cd Stablecoin-Payment-Gateway
run.bat

Linux / macOS

git clone https://github.com/Goncafer47/Stablecoin-Payment-Gateway.git
cd Stablecoin-Payment-Gateway
chmod +x run.sh
./run.sh

手动安装

pip install -r requirements.txt
python main.py

核心依赖（requirements.txt 关键包）

包	版本	用途
rich	≥13.7.0	终端 UI、表格、进度条
cryptography	≥43.0.1	Webhook 签名与密钥处理
requests	≥2.32.3	Facilitator 和 RPC 调用
aiohttp	≥3.10.11	异步链上观察器（mempool watcher）
qrcode	≥8.0	结算 QR 码生成
web3	≥7.0.0	链上结算验证

核心用法

配置 config.json

{
  "merchant": {
    "name": "Demo Store",
    "pay_to_address": "0xYourWalletAddress",
    "xpub": "",
    "callback_url": "https://merchant.example.com/hooks/invoices"
  },
  "invoice": {
    "ttl_minutes": 30,
    "underpayment_tolerance_pct": 0.5,
    "overpayment_action": "credit",
    "confirmations": {
      "ethereum": 12, "base": 12, "polygon": 64, "tron": 19
    }
  },
  "chains": {
    "base": {"enabled": true, "rpc": "https://mainnet.base.org"},
    "ethereum": {"enabled": true, "rpc": "https://eth.llamarpc.com"},
    "tron": {"enabled": true, "rpc": "https://api.trongrid.io"}
  },
  "tokens": {
    "USDC": {"enabled": true, "decimals": 6},
    "USDT": {"enabled": true, "decimals": 6}
  },
  "x402": {
    "enabled": true,
    "facilitator_url": "https://x402.org/facilitator",
    "scheme": "exact",
    "paywall_routes": ["/api/premium", "/api/download"]
  },
  "webhooks": {
    "enabled": true,
    "retry_backoff_sec": [5, 30, 120],
    "signing_header": "X-Signature-256"
  }
}

创建固定金额发票（TUI 菜单操作）

启动后是交互式 TUI 菜单：

╔══════════════════════════════════════════════════════════╗
║ STABLECOION PAYMENT GATEWAY v2.6.0                    ║
╠══════════════════════════════════════════════════════════╣
║ [1] 🧾 Create Invoice    固定金额发票+地址              ║
║ [2] 🔗 Payment Links    分享式结算 URL                 ║
║ [3] 📬 Webhooks         HMAC 签名通知                  ║
║ [4] 🧱 x402 Paywall      HTTP 402 按次付费             ║
║ [5] 💸 Settlement        确认数监控&结算状态            ║
║ [6] 🔑 Merchant API Keys REST 凭证管理                  ║
║ [7] ⛓️ Chains & Tokens  8 条链 USDC/USDT              ║
║ [8] ⚙️ Settings        服务器、TTL、偏好               ║
╚══════════════════════════════════════════════════════════╝

选 [1] 创建发票示例输出：

[10:14:52] Deriving deposit address... xpub path m/44'/60'/0'/1042
[10:14:52] Invoice inv_3f9a2c81d4e5b607 registered (live mode)
[10:14:53] Amount: 249.00 USDC | Chain: Base
[10:14:53] Deposit To: 0x4b21...9F02
[10:14:53] Confirmations: 0/12
[10:14:53] Expires: 30 minutes
[10:14:53] Checkout: https://pay.example.com/i/inv_3f9a
[10:15:41] Mempool hit: 249.00 USDC from 0x88c1...A2d4
[10:16:07] Confirmations 12/12 → invoice.settled
[10:16:07] Webhook invoice.settled → 200 OK (138 ms)

x402 付费路由集成（REST API 方式）

启用 x402 后，给 /api/premium 等路由添加付费墙：

# 客户端侧：发起付费请求
import requests

# 1. 访问付费端点，收到 402 Challenge
resp = requests.get("https://yourgateway.com/api/premium")
# resp.status_code == 402
# resp.headers["X-Accepted-Payment"] 包含接受的链和资产

# 2. 构造 X-PAYMENT 签名载荷（由钱包签名的稳定币转账授权）
payment_header = sign_stablecoin_transfer(
    amount=10_000_000,  # 10 USDC (6 decimals)
    chain="base",
    asset="USDC",
    recipient="0xYourMerchantAddress"
)

# 3. 带 X-PAYMENT 重试请求
resp = requests.get(
    "https://yourgateway.com/api/premium",
    headers={"X-PAYMENT": payment_header}
)
# resp.status_code == 200
# resp.headers["PAYMENT-RESPONSE"] 包含结算 tx hash

Webhook 事件序列

invoice.created → invoice.paid → invoice.settled

每个事件通过 HMAC-SHA256 签名，Webhook POST 到 callback_url，重试策略：5s → 30s → 120s 指数退避。

典型适用场景

场景	用法
AI API 付费	每个 GPT/Claude 调用扣一次 USDC，x402 自动验证支付
SaaS 分级订阅	Free/Pro/Premium 三档，对应不同链上金额
数字内容/文件付费	一次性下载付费，invoice TTL = 30 分钟
开源打赏/捐赠	Payment Link 分享给用户，链上直接到账
开发者工具付费	按 API 调用次数计费，无需 Stripe

坑与注意

⚠️ 私钥安全：config.json 中 pay_to_address 对应的私钥必须离线保管或放在硬件钱包；服务器被入侵则资金可被转走。

⚠️ x402 facilitator：演示/测试网阶段可用官方 https://x402.org/facilitator，但生产环境建议自托管 facilitator 或使用可信第三方，否则 facilitator 是整个支付链的单点。

⚠️ Mempool 监控延迟：mempool watcher 实时检测，但不同链 TPS 不同，Base/Ethereum 约 12 个确认（~3–5 分钟），Polygon 需 64 个确认（更长）。

⚠️ Invoice TTL：默认 30 分钟，过期后地址退回地址池，重复付款可能造成资金「悬空」；如需更长 TTL 建议在 config.json 调整 invoice.ttl_minutes。

⚠️ 多链支持：v2.6.0 支持 8 条链（Base/Ethereum/Polygon/Tron 等），但 config.json 中需要填入各链的 RPC 地址；公共 RPC 有速率限制，生产环境建议用付费 RPC 提供商（如 Alchemy/Infura）。

⚠️ 版本号：README 显示 v2.6.0，但 GitHub 最新 release 请自行核实，Python 版本兼容性以 requirements.txt 为准。

⚠️ QR 码钓鱼：支付链接通过 QR 展示时，确保用户核实链和金额；攻击者可替换 QR 内容。

与同类对比

维度	Stripe/PayPal	稳定币直转	本项目
平台费率	0.5–3.5%	0%（链上 Gas）	0%
KYC	必须	无	无
资金托管	平台持有	自己钱包	自己钱包
接入复杂度	SDK/API 成熟	手动转帐+对账	TUI + REST
微支付	不友好（最低 $0.50）	友好（几分钱可转）	友好
退款	平台处理	需要自己写逻辑	需要自己写逻辑
合规	PCI DSS	无	无
适用规模	所有规模	中等规模	开发者/极客

相比链上直接转账，本项目的优势在于自动化对账 + Webhook 通知 + TUI 管理界面，不需要手动盯着区块链浏览器。

一句话推荐

如果你做的是面向全球用户的付费 API 或数字内容平台，想要「资金直接到账、零平台抽成、代码可控」，Goncafer47/Stablecoin-Payment-Gateway 是一个开箱即用的自托管方案，x402 协议让支付逻辑天然融入 HTTP 请求，非常适合开发者生态。