WebSocket 實時推送

連接信息

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

描述: 為 Maker 提供實時的訂單狀態變更推送功能。當訂單狀態發生變化時，系統會自動向相關的 Maker 推送通知。

鑑權: Authorization請求頭附加JWT令牌

查詢參數

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

訂單狀態變更通知

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

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

消息字段說明

字段	類型	說明
type	string	消息類型
timestamp	string	時間戳
data	object	訂單狀態變更數據
data.order_hash	string	訂單哈希值
data.maker	string	Maker 地址
data.from_status	enum	原狀態（可能為 null）
data.to_status	enum	新狀態
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: 系統異常，需要人工干預

瀏覽器支持

由於瀏覽器對於WebSocket安全策略，不支持Authorization請求頭，但可以通過子協議（subprotocols）傳遞：

const ws = new WebSocket(
  `wss://${host}/ws/maker/v1?types=order_status_change`, 
  ['jwt', jwt]
);

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

服務端心跳

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

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

枚舉類型

WebSocketDataType - WebSocket消息類型

枚舉項	說明
heartbeat	服務端側心跳通知
order_status_change	訂單狀態變更