开发文档

USDC 支付接入指南

核对五条网络的 USDC 版本、合约或 Mint 与链上精度，再从后端创建订单。支持范围与实时启用状态是两回事。

项目支持的主网代币身份

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

项目支持的主网代币身份
付款网络	币种	合约 / Mint	链上精度
ERC20	USDC	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48	6
BEP20	USDC	0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d	18
POLYGON	USDC	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359	6
SOLANA	USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6
BASE	USDC	0x833589fcd6edb6e08f4c7c32d4f71b54bda02913	6

商户接入准备

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

网络与币种注意事项

付款网络

Ethereum、Polygon、Solana、Base 使用原生 USDC；BNB Smart Chain 使用 Binance-Peg USDC（18 位精度）。TRC20 不支持 USDC。USDbC、USDC.e 和其他合约不能替代项目列出的身份。

本接口的 ERC20 指 Ethereum 主网，不表示所有使用 ERC20 标准的网络。
相同 0x 钱包地址可出现在不同 EVM 网络；客户必须选择订单指定网络与代币版本。
Ethereum USDC 使用 Circle 原生合约。其他桥接版本不能替代所列身份。

签名请求与响应示例

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

create / cURL

# 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":"USDC","network":"ERC20","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"

地址、交易哈希及订单均为示例。请替换为您自己的测试数据。

Base URL

PROD

https://api.boltutil.com

完整订单参数 →

付款确认与通知处理

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

接入前常见问题

支持某币种，是否意味着现在就能创建订单？

不一定。网络、币种需已启用，收款钱包与 Webhook 配置也必须有效。静态合约列表不反映实时状态。

客户可以把小数金额取整后付款吗？

请按 payment.amount 的完整金额付款。系统可能向上取整并增加小额偏移来区分同一钱包的订单，不能截断或自行四舍五入。

钱包显示到账后，可以直接发货吗？

先核对订单是否已确认以及通知真实性。错误网络、代币版本、金额或重复通知都需要正确处理；余额增加本身不能替代订单付款结果。