接入文档

POC 提供稳定币代收 API。商户完成实名认证后，使用 API Key 创建订单；客户按返回的应付金额完成链上转账后，系统确认到账并回调商户。

结算规则

结算依据是创建订单时提交的 amount（订单金额），不是链上实付金额。
客户必须按接口返回的 amount_due 原额支付；尾数在 0.000–0.099 之间，用于区分同金额订单。
尾数差额不计入商户余额；手续费 6.5% 从订单金额中扣除，可结算余额为扣除手续费后的净额。
未完成实名认证前，调用商户 API 将返回 403 need_realname。

鉴权

请求头使用以下任一方式：

Authorization: Bearer <api_key>
X-Api-Key: <api_key>

支持的链与代币

GET /api/v1/chains 返回完整列表。当前支持 Ethereum / BSC / Base / Polygon / Solana / Tron 上的 USDT、USDC、USD1（以接口返回为准；Base 与 Polygon 不提供 USD1，Tron 不提供 USDC）。调用时只传 chain 与 token 符号，不要传合约地址。

创建订单

POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: optional-unique-key

{
  "amount": "10.00",
  "chain": "ethereum",
  "token": "USDT",
  "external_id": "order-1001",
  "webhook_url": "https://example.com/hook",
  "memo": "optional"
}

amount 为字符串，最多两位小数，最小 0.01。可在创建时同时指定 chain 与 token 以立刻选出应付金额；也可稍后调用 POST /api/v1/orders/:id/select。

响应中的 amount_requested 为订单金额，amount_due 为客户应付金额，fee 与 net_amount 为手续费与入账净额。

查询与操作

GET /api/v1/orders/:id — 查询订单
POST /api/v1/orders/:id/select — 选择链与代币
POST /api/v1/orders/:id/cancel — 取消未付款订单
POST /api/v1/orders/:id/check — 触发一次扫描并返回最新状态

公开收银台：GET /api/pay/:id、POST /api/pay/:id/select，页面路径为 /pay/:id。

Webhook

订单首次变为 paid 时向商户回调，事件名为 order.paid。签名使用商户的 api_secret：

signed = HMAC-SHA256(api_secret, "{timestamp}.{rawBody}")
X-Pay-Timestamp: <unix seconds>
X-Pay-Signature: v1=<lowercase hex>
X-Pay-Event: order.paid
X-Pay-Delivery: <attempt number>

请先用原始 body 验签，再解析 JSON。回调体中同时包含 amount_requested（结算依据）、amount_due、amount_paid、fee、net_amount。Webhook URL 须为公网 HTTPS（443），不可指向内网或 localhost。

状态说明

状态	含义
awaiting_selection	待选择支付链与代币
pending	等待链上到账
confirming	已观察到匹配转账，确认数不足
paid	已确认支付（仅此状态入账并发 webhook）
expired / cancelled	过期或已取消

费率与实名

代收手续费 6.5%，按订单金额计算并四舍五入到毫单位。实名认证费用固定 0.2 USDT（另加唯一尾数），支付到平台收款地址并通过校验后，商户方可调用 API。