SureLink 开放平台

链上提币订单 (Crypto Withdrawal) ​

商户可通过接口发起链上数字资产（USDT）提现申请，将资金提取至指定的外部区块链钱包地址。网关接收到提币申请后，扣除商户账户代币余额，经安全风控审核后由出金热钱包自动或人工签名广播上链。

1. 业务交互时序 ​

mermaid
sequenceDiagram
    autonumber
    participant Merchant as 商户系统
    participant Gateway as SureLink 网关
    participant Blockchain as 区块链网络 (TRON / ETH)

    Merchant->>Gateway: 1. POST /api/v1/crypto-withdrawal-orders (提交提币申请)
    Gateway->>Gateway: 2. 校验商户可用余额并实时扣减/冻结
    Gateway->>Gateway: 3. 自动化风控与合规审查 (PENDING_REVIEW)
    Gateway->>Gateway: 4. 网关安全热钱包构建交易并私钥签名 (PENDING_SIGN)
    Gateway->>Blockchain: 5. 广播交易至区块链网络 (SIGNED)
    Gateway->>Merchant: 6. 提币完成，返回广播哈希 txHash

2. 提交链上提币申请 ​

POST /api/v1/crypto-withdrawal-orders

请求头 (Headers) ​

携带标准 HMAC 签名头及 Idempotency-Key。

请求体 (Body) ​

字段类型是否必填说明
chainstring必填提币目标公链代码（如 "TRON", "ETH"）。
amountstring必填提币数量（USDT），必须保留 2 位小数（如 "500.00"）。
recipientAddressstring必填接收提币的链上钱包公钥地址（长度 8 ~ 128 字符）。

免 TOTP 接口设计

商户 Web 后台提交提币时受 TOTP 二次验证保护；而服务端开放接口（/api/v1/crypto-withdrawal-orders）专门面向自动化系统，无需传入 TOTP 动态码，完全由 HMAC 强签名、Nonce 防重放及 IP 白名单提供最高安全防护。

请求示例 ​

bash
curl -X POST "https://api-sandbox.surelink.io/api/v1/crypto-withdrawal-orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: mch_key_your_api_key" \
  -H "X-Timestamp: 1715000000000" \
  -H "X-Nonce: 9f8e7d6c5b4a392817263544a1b2c3d4" \
  -H "X-Signature: c8b9...f01" \
  -H "Idempotency-Key: CRYPTO_WD_001" \
  -d '{
    "chain": "TRON",
    "amount": "500.00",
    "recipientAddress": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7"
  }'
typescript
import { sendSignedRequest } from './signer';

const result = await sendSignedRequest({
  apiKey: 'mch_key_...',
  apiSecret: 'sec_...',
  method: 'POST',
  url: 'https://api-sandbox.surelink.io/api/v1/crypto-withdrawal-orders',
  body: {
    chain: 'TRON',
    amount: '500.00',
    recipientAddress: 'TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7'
  }
});

响应说明 (Response) ​

  • HTTP 状态码：201 Created
json
{
  "id": "e4f5a6b7-c8d9-0123-4567-89abcdef0123",
  "orderNo": "CW202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "amount": "500.00",
  "recipientAddress": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
  "status": "PENDING_REVIEW",
  "txHash": null,
  "createdAt": "2026-10-11T09:30:00.000Z",
  "updatedAt": "2026-10-11T09:30:00.000Z"
}

3. 分页查询提币订单列表 ​

GET /api/v1/crypto-withdrawal-orders

Query 参数 ​

参数名类型是否必填默认值说明
pagenumber否1当前页码
pageSizenumber否20每页数量（最大 100）
chainstring否-按链代码过滤
statusstring否-按提币状态过滤

4. 查询单笔提币订单详情 ​

GET /api/v1/crypto-withdrawal-orders/:id

通过内部 ID 或订单号查询指定提币单详情及广播哈希。

响应说明 (Response) ​

json
{
  "id": "e4f5a6b7-c8d9-0123-4567-89abcdef0123",
  "orderNo": "CW202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "amount": "500.00",
  "recipientAddress": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
  "status": "SIGNED",
  "txHash": "0x3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b",
  "createdAt": "2026-10-11T09:30:00.000Z",
  "updatedAt": "2026-10-11T09:32:15.000Z"
}

5. 链上提币状态机 ​

状态代码状态说明是否终态
PENDING_REVIEW提币申请已受理，风控审查中否
PENDING_SIGN审核已通过，等待热钱包签名广播否
SIGNED交易已在区块链广播上链并生成哈希，终态是
REJECTED风控未通过或地址黑名单驳回，资金已解冻归还，终态是
CANCELLED订单已取消，终态是