WebSocket 實時推送

連接信息

連接端點: wss://{host}/ws/taker/v1?types=order_status_change,cancellation_request

描述: 為 Taker 提供實時的訂單狀態變更和取消請求推送功能。當訂單狀態發生變化或收到取消請求時，系統會自動向相關的 Taker 推送通知。

鑑權: API Key憑據認證

查詢參數

參數	類型	必填	說明
types	string	是	URL查詢參數，用於訂閱指定的消息類型，多個使用英文逗號拼接。詳見WebSocketDataType枚舉類型說明

訂單狀態變更通知

當訂單狀態發生變更時，會收到以下格式的消息：

{
  "type": "order_status_change",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "order_hash": "0x1234567890abcdef...",
    "maker": "0x1111111111111111111111111111111111111111",
    "taker": "0xabcdef1234567890...",
    "from_status": "pending",
    "to_status": "locked",
    "metadata": {
      "expires_at": "2024-01-01T13:00:00Z",
      "lock_id": "uuid-string",
      "blockchain_tx_hash": "0x..."
    }
  }
}

消息字段說明

字段	類型	說明
type	string	消息類型
timestamp	string	時間戳
data	object	訂單狀態變更數據
data.order_hash	string	訂單哈希值
data.maker	string	Maker 地址
data.taker	string	Taker 地址
data.from_status	enum	原狀態（見OrderStatus枚舉項說明，可能為 null）
data.to_status	enum	新狀態（見OrderStatus枚舉項說明）
data.metadata	object	附加信息（可選）

訂單取消請求通知

當收到訂單取消請求時，會收到以下格式的消息：

{
  "type": "cancellation_request",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "order_hash": "0x1234567890abcdef...",
    "maker": "0x1111111111111111111111111111111111111111",
    "reason": "user_requested",
    "metadata": {
      "request_id": "uuid-string",
      "expires_at": "2024-01-01T13:00:00Z"
    }
  }
}

消息字段說明

字段	類型	說明
type	string	消息類型
timestamp	string	時間戳
data	object	取消請求數據
data.order_hash	string	訂單哈希值
data.maker	string	Maker 地址
data.reason	string	取消原因
data.metadata	object	附加元數據

狀態變更觸發場景

1. 訂單創建

• null → pending: 訂單創建成功
• null → rejected: 訂單驗證失敗

2. Taker 操作

• pending → locked: Taker 鎖定訂單
• locked → pending: Taker 解鎖訂單
• locked → rejected: Taker 拒絕訂單
• pending/locked → partially_filled: 訂單部分成交
• partially_filled → filled: 訂單完全成交

3. Maker 操作

• pending → cancelled: Maker 取消訂單

4. 系統操作

• pending → expired: 訂單自動過期
• 任何狀態 → suspended: 系統異常，需要人工干預

鑑權方式

Taker WebSocket 連接使用 API Key 認證，需要在請求頭中包含有效的 API Key：

Authorization: Bearer <your-api-key>

對於瀏覽器環境，由於 WebSocket 不支持自定義請求頭，可以將 API Key 作為查詢參數傳遞：

const ws = new WebSocket(
  `wss://${host}/ws/taker/v1?types=order_status_change,cancellation_request&api_key=<your-api-key>`
);

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'order_status_change') {
    console.log('Order status changed:', message.data);
  } else if (message.type === 'cancellation_request') {
    console.log('Cancellation request received:', message.data);
  } else if (message.type === 'heartbeat') {
    console.log('Heartbeat:', message.timestamp);
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket connection closed');
};

服務端心跳

服務端會在一定間隔時間對鏈接發送心跳消息，格式如下：

{
  "type": "heartbeat",
  "timestamp": 1763722070521
}

枚舉類型

WebSocketDataType - WebSocket消息類型

枚舉項	說明
heartbeat	服務端側心跳通知。無需在參數上指定
order_status_change	訂單狀態變更
cancellation_request	訂單取消請求

注意事項

• 建議實現自動重連機制
• 處理心跳消息以保持連接活躍
• 妥善處理取消請求，及時響應
• 注意消息的時序性，按timestamp排序處理