Base 稳定币收款接入

项目支持的主网代币身份

以下列出项目预置的合约或 Mint，并非实时渠道状态。实际可下单还需网络与币种已启用，且商户已配置有效收款钱包。付款始终发送到 API 返回的 payment.address，不要向代币合约或 Mint 转账。

项目支持的主网代币身份

付款网络	币种	合约 / Mint	链上精度
BASE	USDT	0xfde4c96c8593536e31f229ea8f37b2ada2699bb2复制	6
BASE	USDC	0x833589fcd6edb6e08f4c7c32d4f71b54bda02913复制	6

商户接入准备

1. 配置对应网络的收款钱包，以及已启用的 Webhook 地址和签名密钥。API Key 与 HMAC 密钥只保存在服务端。
2. 确认所选 network / currency 组合可用。平台管理员维护 RPC、网络与资产启用配置；普通商户无需自行部署扫描节点。
3. 创建订单后展示 payment.amount、payment.address、currency、network 和有效期；QR 数据不是二维码图片。
4. 接收端验签、去重并可靠保存事件后返回 HTTP 2xx；再按业务规则幂等交付。

网络与币种注意事项

• Base 主网链 ID 为 8453；本接入不使用 Base Sepolia。商户配置收款钱包，平台管理员维护 RPC 与网络启用。
• USDC 为 Circle 原生版本；USDT 为项目预置的桥接版本。USDbC 或其他合约不在此列表中。
• BoltUtil 使用 L1-finalized 安全高度处理 Base 付款。请在订单倒计时结束前付款，确认可能随后到达；不保证固定分钟数。
• WooCommerce 使用前请核对实际安装版本与发布说明，确认已包含目标网络与币种。

签名请求与响应示例

示例默认金额为 25.00，只用于说明格式。实际金额来自您的业务订单，且须满足所选资产的最低金额。示例地址、订单与交易哈希不是实际付款记录。复制的 cURL / Java 程序会发送请求，运行前配置自己的 API Key 和 Webhook 密钥。

# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"BASE","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

付款确认与通知处理

检测到转账与付款确认是不同环节。以系统状态和已验证回调判断结果：PAID 仍待确认；CONFIRMED / COMPLETED 也可能来自人工接受付款，请结合 paidAmount、shortfallAmount 和 settlementType。COMPLETED 不证明您的业务已经交付。

接入前常见问题