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訂單已取消，終態是