價格串流參考文件

存取權限與限制

價格串流適用於 Basic 和 Pro 方案。 使用 Free 方案金鑰時會收到 plan_upgrade_required，接著連線關閉。

價格、事件和預測串流共用並行連線數上限：Free 為 1 個、Basic 為 2 個、Pro 為 10 個。每個連線會使用一次每月呼叫額度。

連線

將 API 金鑰放入 Authorization: Bearer 標頭，連線至 wss://api.narwhalapi.com/v1/prices/stream。

瀏覽器無法在 WebSocket 連線中設定該標頭。請從伺服器傳送 POST /v1/prices/stream-ticket，再透過 ?ticket= 帶入傳回的票證建立連線。票證只能使用一次，30 秒後到期，且要求來源已獲允許。 預測串流適用相同的票證規則。

訂閱

伺服器傳送 {"type":"ready"}。請在 5 秒內傳送一則訂閱訊息：

{
  "action": "subscribe",
  "commodities": [
    {
      "commodity": "XAU",
      "currency": "USD"
    }
  ],
  "fx": [
    {
      "base": "USD",
      "currencies": [
        "EUR",
        "JPY"
      ]
    }
  ]
}

• commodities：最多指定 20 組受 GET /v1/commodities/spot/{commodity}/{currency} 支援的商品與貨幣配對。
• fx：最多指定 5 種基準貨幣。currencies 為選填：省略時接收該基準貨幣支援的所有貨幣，也可以列出最多 64 種貨幣。

伺服器回覆 {"type":"subscribed"}，並將每個已訂閱價格傳送一次。此後，只有價格變動時才會傳送。價格約每秒檢查一次。

若要變更訂閱，請重新連線。傳送第二則訂閱訊息會使連線以 resubscribe_required 關閉。

訊息

價格訊息的本文與 REST 端點的回應本文相同，包括小數位數、備用值和資料過期旗標。

{
  "type": "commodity",
  "spot": {
    "symbol": "XAU-USD",
    "price": "4195.86",
    "currency": "USD",
    "unit": "troy_ounce",
    "timestamp": "2026-10-11T06:25:00Z",
    "stale": false
  }
}

{
  "type": "fx",
  "base": "USD",
  "market_session": "open",
  "rate": {
    "currency": "EUR",
    "rate": "0.8924",
    "timestamp": "2026-10-09T00:00:00Z",
    "stale": false
  }
}

現貨價格參考文件 · 外匯匯率參考文件

維持連線

傳送 {"action":"ping"} 即可取得 {"type":"pong"}。伺服器也會每 30 秒傳送一次 heartbeat。請及時讀取訊息：用戶端若連續 5 秒未讀取訊息，連線將以 slow_consumer 關閉。

每個連線最多可傳送 30 個影格。重新連線後，所有已訂閱價格都會再次傳送；錯過的價格變動不會重播。

錯誤

錯誤以 {"type":"error","code":"..."} 的形式送達，接著連線關閉。