SureLink 开放平台

链上充币订单 (Crypto Deposit) ​

SureLink 网关支持商户为自有系统或用户创建专属的链上数字资产（USDT）充币地址，实时监听区块链节点交易并自动确认入账。

1. 业务交互时序 ​

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

    Merchant->>Gateway: 1. POST /api/v1/crypto-deposit-orders (创建充币订单)
    Gateway-->>Merchant: 2. 返回充币钱包地址 walletAddress 与有效截止期
    Merchant-->>Merchant: 3. 展示充币二维码与地址给用户
    Blockchain->>Gateway: 4. 用户链上转账，网关扫块监听到交易 (DETECTED)
    Blockchain->>Gateway: 5. 区块确认数达到安全阈值
    Gateway->>Gateway: 6. 记账至商户可用资产 (COMPLETED)
    Gateway->>Merchant: 7. Webhook 异步推送链上入账通知

2. 创建链上充币订单 ​

POST /api/v1/crypto-deposit-orders

为本次充币申请分配专属的区块链钱包收款地址。

请求头 (Headers) ​

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

请求体 (Body) ​

字段类型是否必填说明
chainstring必填目标区块链网络代码（如 "TRON", "ETH", "BSC"），需从 GET /api/v1/chains 中获取。
amountstring必填预期充币数量（USDT），保留 2 ~ 6 位小数（如 "100.00", "50.123456"）。

请求示例 ​

bash
curl -X POST "https://api-sandbox.surelink.io/api/v1/crypto-deposit-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_DEP_001" \
  -d '{
    "chain": "TRON",
    "amount": "100.00"
  }'
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-deposit-orders',
  body: {
    chain: 'TRON',
    amount: '100.00'
  }
});

响应说明 (Response) ​

  • HTTP 状态码：201 Created
json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "orderNo": "CD202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "assetSymbol": "USDT",
  "expectedAmount": "100.000000",
  "creditedAmount": null,
  "status": "PENDING_DEPOSIT",
  "walletAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "txHash": null,
  "expiresAt": "2026-10-11T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-10-11T09:00:00.000Z",
  "updatedAt": "2026-10-11T09:00:00.000Z"
}

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

GET /api/v1/crypto-deposit-orders

Query 参数 ​

参数名类型是否必填默认值说明
pagenumber否1当前页码，从 1 开始
pageSizenumber否20每页数量（最大 100）
chainstring否-按链代码筛选（如 TRON）
statusstring否-按状态筛选（如 COMPLETED）

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

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

通过内部 ID 或订单号查询指定充币单详情。

响应说明 (Response) ​

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "orderNo": "CD202610110001",
  "ownerType": "MERCHANT",
  "ownerId": "mch_12345",
  "chain": "TRON",
  "assetSymbol": "USDT",
  "expectedAmount": "100.000000",
  "creditedAmount": "100.000000",
  "status": "COMPLETED",
  "walletAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "txHash": "0x5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "expiresAt": "2026-10-11T10:00:00.000Z",
  "completedAt": "2026-10-11T09:05:32.000Z",
  "createdAt": "2026-10-11T09:00:00.000Z",
  "updatedAt": "2026-10-11T09:05:32.000Z"
}

5. 链上充币状态机 ​

状态代码说明是否终态
PENDING_DEPOSIT待充币入账，等待链上检测到转账交易否
DETECTED链上已监听到入账交易，正在等待安全区块确认数否
MANUAL_REVIEW充值金额与预期偏差较大或风险预警，人工审核中否
COMPLETED充币已成功入账，终态是
EXPIRED在有效期截止前未检测到交易，地址已失效，终态是
CANCELLED订单已取消，终态是