开发文档

USDT 支付接入指南

在六条网络接收 USDT。核对支持的代币版本、合约或 Mint 与链上精度，了解签名下单、付款确认和回调处理。

项目支持的主网代币身份

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

项目支持的主网代币身份
付款网络币种合约 / Mint链上精度
TRC20 network logoTRC20USDTTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t6
ERC20 network logoERC20USDT0xdAC17F958D2ee523a2206206994597C13D831ec76
BEP20 network logoBEP20USDT0x55d398326f99059fF775485246999027B319795518
POLYGON network logoPOLYGONUSDT0xc2132D05D31c914a87C6611C10748AEb04B58e8F6
SOLANA network logoSOLANAUSDTEs9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB6
BASE network logoBASEUSDT0xfde4c96c8593536e31f229ea8f37b2ada2699bb26

商户接入准备

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

网络与币种注意事项

USDT 支持六条网络。项目配置的 BNB Smart Chain 代币使用 18 位链上精度，其余五条为 6 位；这与订单金额识别精度不同。Base 使用项目配置的桥接 USDT，BoltUtil 不提供跨链转账。付款时须选择订单指定网络与所列代币版本；币种名称或钱包地址相同，不代表网络与代币可以互相替代。

  • TRC20 是本接口的 TRON 网络代码，当前只支持 USDT；不能传 currency=USDC。
  • USDT 链上精度为 6 位，不代表订单必须展示 6 位小数。请原样使用接口返回的应付金额。
  • 确认规则以系统配置和扫描结果为准，不承诺固定到账秒数。

签名请求与响应示例

示例默认金额为 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":"USDT","network":"TRC20","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 的完整金额付款。系统可能向上取整并增加小额偏移来区分同一钱包的订单，不能截断或自行四舍五入。

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

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