Skip to main content

開始使用 BETA

富果行情 WebSocket API 提供台股即時行情服務。透過 WebSocket API 可以滿足您想要接收即時行情的需求。

建立連線​

富果期權行情 WebSocket API 提供 v1.1 與 v1.0 兩個版本：

wss://api.fugle.tw/marketdata/v1.1/futopt/streaming
wss://api.fugle.tw/marketdata/v1.0/futopt/streaming
版本差異

兩個版本的唯一差異在 trades／books 頻道是否推送試撮訊息：

  • v1.0：恆不推送帶 isTrial: true 的 trades／books 訊息（整則丟棄）。
  • v1.1：試撮與正式行情一併推送，以逐筆訊息的 isTrial 欄位區分。

aggregates／candles 頻道兩版本行為完全相同。請特別注意：aggregates 的試撮欄位（頂層 isTrial、lastTrial）在 v1.0 連線一樣會出現，且試撮期間的 lastPrice／change 也會反映試撮價。無論使用哪個版本，程式都應判斷 isTrial，詳見 aggregates。

v1.0 退場預告

v1.0 預計於 2026 年底退場，且不會回頭推送試撮訊息。新專案請直接使用 v1.1，既有整合請預留遷移時間。

身份驗證​

建立 WebSocket 連線後，請使用 API 金鑰進行身份驗證，以獲授權訂閱各項頻道：

{
  "event": "auth",
  "data": {
    "apikey": "<API_KEY>"
  }
}

當驗證成功後，會收到以下訊息：

{
  "event": "authenticated",
  "data": {
    "message": "Authenticated successfully"
  }
}

若驗證失敗，則收到以下訊息：

{
  "event": "error",
  "data": {
    "message": "Invalid authentication credentials"
  }
}

Heartbeat​

每隔 30 秒 WebSocket server 會送出一個 heartbeat 訊息：

{
  "event": "heartbeat",
  "data": {
    "time": "<Timestamp>"
  }
}

Ping/Pong​

將以下 JSON 格式訊息發送到 WebSocket Server (state 為可選)：

{
  "event": "ping",
  "data": {
    "state": "<ANY>"
  }
}

WebSocket Server 會回應以下訊息 (若 ping 未送 state 則不會有該欄位)：

{
  "event": "pong",
  "data": {
    "time": "<TIMESTAMP>",
    "state": "<ANY>"
  }
}

Channels​

富果行情 WebSocket API 目前提供以下可訂閱頻道：

連續月別名​

訂閱時的 symbol 除了具體合約代碼（如 TXFG6），也可使用連續月別名 {ROOT}1!／2!／3! 訂閱第 1／2／3 近月合約（如 TXF1! 為最近月臺股期貨）。系統會自動解析為當前對應的具體合約，回傳 data 中的 symbol 為解析後的具體合約代碼。詳見 REST API — 商品代碼與連續月別名。

別名只在訂閱當下解析一次

連續月別名是在送出訂閱的當下解析成具體合約，之後該訂閱就固定綁在那個合約上。長時間保持的連線在跨過結算日之後不會自動重新解析——訂閱仍綁在已結算的舊合約，因而靜默地收不到任何資料。

跨結算日的長效連線請自行在換月後重新訂閱（unsubscribe 後再 subscribe），或改用具體合約代碼並自行控制轉倉。REST API 則不受影響，每次呼叫都會重新解析。

{
  "event": "subscribe",
  "data": {
    "channel": "trades",
    "symbol": "TXF1!"
  }
}

價差契約訂閱​

價差契約（如 TXFG6/H6）同樣以 symbol 欄位訂閱，代碼原樣放入即可。詳見 價差契約。

{
  "event": "subscribe",
  "data": {
    "channel": "trades",
    "symbol": "TXFG6/H6"
  }
}

訂閱頻道​

要訂閱一個頻道 JSON 格式訊息發送到 WebSocket Server：

{
  "event": "subscribe",
  "data": {
    "channel": "<CHANNEL_NAME>",
    "symbol": "<SYMBOL_ID>"
  }
}

訂閱成功後，會收到以下事件回應：

{
  "event": "subscribed",
  "data": {
    "id": "<CHANNEL_ID>",
    "channel": "<CHANNEL_NAME>",
    "symbol": "<SYMBOL_ID>"
  }
}

支援訂閱同頻道的多檔股票：

{
  "event": "subscribe",
  "data": {
    "channel": "<CHANNEL_NAME>",
    "symbols": ["<SYMBOL_ID_1>", "<SYMBOL_ID_2>"]
  }
}

訂閱成功後，會收到以下事件回應：

{
  "event": "subscribed",
  "data": [
    {
      "id": "<CHANNEL_ID>",
      "channel": "<CHANNEL_NAME>",
      "symbol": "<SYMBOL_ID_1>"
    },
    {
      "id": "<CHANNEL_ID>",
      "channel": "<CHANNEL_NAME>",
      "symbol": "<SYMBOL_ID_2>"
    }
  ]
}

取消訂閱​

要取消已訂閱頻道，請將以下 JSON 格式訊息發送到 WebSocket Server：

{
  "event": "unsubscribe",
  "data": {
    "id": "<CHANNEL_ID>"
  }
}

取消訂閱成功後，會收到以下事件回應：

{
  "event": "unsubscribed",
  "data": {
    "id": "<CHANNEL_ID>"
  }
}

支援取消訂閱多個頻道：

{
  "event": "unsubscribe",
  "data": {
    "ids": ["<CHANNEL_ID_1>", "<CHANNEL_ID_2>"]
  }
}

取消訂閱成功後，會收到以下事件回應：

{
  "event": "unsubscribed",
  "data": [
    {
      "id": "<CHANNEL_ID_1>"
    },
    {
      "id": "<CHANNEL_ID_2>"
    }
  ]
}

訂閱資訊​

要取得已訂閱的頻道，請將以下 JSON 格式訊息發送到 WebSocket Server：

{
  "event": "subscriptions"
}

然後會收到以下事件回應：

{
  "event": "subscriptions",
  "data": [
    {
      "id": "<CHANNEL_ID>",
      "channel": "<CHANNEL_NAME>",
      "symbol": "<SYMBOL_ID>"
    }
  ]
}

使用 SDK​

富果行情 WebSocket API 提供 Python 與 Node.js SDK。您可以透過以下方式存取 WebSocket API：

from fugle_marketdata import WebSocketClient

client = WebSocketClient(api_key = 'YOUR_API_KEY')
futopt = client.futopt

指定連線版本​

SDK 提供 version 選項指定期權要連線的 WebSocket 版本。期權（futopt）預設即為 v1.1，一般情況不需另行指定；若要維持既有的 v1.0 行為，請明確指定 v1.0。

from fugle_marketdata import WebSocketClient

# 期權預設連線 v1.1
client = WebSocketClient(api_key='YOUR_API_KEY')

# 明確指定版本
client = WebSocketClient(api_key='YOUR_API_KEY', version={'futopt': 'v1.1'})

# 維持既有 v1.0 行為（不接收 trades／books 試撮訊息）
client = WebSocketClient(api_key='YOUR_API_KEY', version={'futopt': 'v1.0'})
SDK 版本需求

version 選項需要 Node.js @fugle/marketdata v1.5.0／Python fugle-marketdata 2.5.0 以上。台股（stock）目前僅支援 v1.0，指定其他版本會拋出錯誤。

Last updated on