Crypto Withdrawal Orders

Merchants can programmatically initiate on-chain cryptocurrency (USDT) withdrawals to external blockchain wallet addresses. Upon submission, the gateway verifies the available balance, conducts security risk checks, and broadcasts the signed transaction to the blockchain using platform hot wallets.

---

1. Sequence Flow

sequenceDiagram
    autonumber
    participant Merchant as Merchant System
    participant Gateway as SureLink Gateway
    participant Blockchain as Blockchain (TRON / ETH)

    Merchant->>Gateway: 1. POST /api/v1/crypto-withdrawal-orders (Submit withdrawal request)
    Gateway->>Gateway: 2. Validate & deduct available crypto balance
    Gateway->>Gateway: 3. Risk scoring & compliance check (PENDING_REVIEW)
    Gateway->>Gateway: 4. Secure hot wallet signs transaction (PENDING_SIGN)
    Gateway->>Blockchain: 5. Broadcast signed transaction (SIGNED)
    Gateway->>Merchant: 6. Complete withdrawal & return txHash

---

2. Submit Crypto Withdrawal Request

POST /api/v1/crypto-withdrawal-orders

Headers

Standard HMAC authentication headers and Idempotency-Key.

Body Parameters

Field	Type	Required	Description
chain	string	Yes	Target blockchain network code (e.g., "TRON", "ETH").
amount	string	Yes	Withdrawal quantity (USDT), with exactly 2 decimal places (e.g., "500.00").
recipientAddress	string	Yes	Destination on-chain recipient wallet address (8–128 characters).

Programmatic TOTP-Free Architecture

While web sessions on the Merchant Portal require 2FA TOTP verification, the server-to-server API (/api/v1/crypto-withdrawal-orders) does not require TOTP codes. Security is enforced via HMAC signatures, replay-protected nonces, and IP whitelisting.

Request Example

cURL

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"
  }'

Node.js

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

• Status Code: 201 Created

{
  "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. List Crypto Withdrawal Orders

GET /api/v1/crypto-withdrawal-orders

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	1	Page number
pageSize	number	No	20	Items per page (max 100)
chain	string	No	-	Filter by chain code
status	string	No	-	Filter by withdrawal status

---

4. Query Crypto Withdrawal Details

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

Retrieve details and the on-chain broadcast hash for a specific crypto withdrawal order.

Response

{
  "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. Status Matrix

Status	Description	Terminal?
PENDING_REVIEW	Submitted; undergoing automated or manual compliance review	No
PENDING_SIGN	Approved; queued for hot wallet signing	No
SIGNED	Transaction broadcast to the blockchain network; hash generated	Yes
REJECTED	Rejected by risk policy; reserved funds unlocked back to balance	Yes
CANCELLED	Order cancelled	Yes