開始使用
- 富邦行情 WebSocket API(富邦新一代 API 行情服務)提供台股即時行情訂閱。
- 支援
Speed/Normal兩種行情模式。 - 需登入後建立行情連線並訂閱頻道。
- 下一步可前往各頻道說明頁。
| 項目 | 說明 |
|---|---|
| 介面 | WebSocket API |
| 市場 | 台股 |
| 模式 | Speed / Normal |
| SDK | Python / Node.js / C# |
| 訂閱方式 | 連線後訂閱頻道 |
富邦行情 WebSocket API 提供台股即時行情服務。透過 WebSocket API 可以滿足您想要接收即時行情的需求。
使用 SDK
富邦行情 WebSocket API 提供 Python 、 Node.js 與 C# SDK。您可以透過以下方式存取 WebSocket API、並透過行情 Mode 模式切換要訂閱的行情:
訂閱 WebSocket Callback 方法獲得下方 Callback 訊息。
行情 Mode 提供 Low Latency Speed Mode 以及完整資訊的 Normal Mode
- Python
- Node.js
- C#
from fubon_neo.sdk import FubonSDK,Mode
def handle_message(message):
print(message)
sdk = FubonSDK()
accounts = sdk.login("Your ID", "Your password", "Your cert path", "Your cert password") # 需登入後,才能取得行情權限
sdk.init_realtime() # 建立行情連線
# 可指定行情連線的Mode , Default 為Speed
# sdk.init_realtime(Mode.Speed) or sdk.init_realtime(Mode.Normal)
stock = sdk.marketdata.websocket_client.stock
stock.on('message', handle_message)
stock.connect()
const { FubonSDK, Mode } = require('fubon-neo');
const sdk = new FubonSDK();
const accounts = sdk.login("Your ID", "Your password", "Your cert path", "Your cert password");
sdk.initRealtime(); // 建立行情連線
// 可指定行情連線的Mode , Default 為Speed
// sdk.initRealtime(Mode.Speed) or sdk.initRealtime(Mode.Normal)
const stock = sdk.marketdata.webSocketClient.stock;
stock.on("message", (message) => {
const data = JSON.parse(message);
console.log(data);
});
(async () => {
await stock.connect();
stock.subscribe({
'channel': 'trades',
'symbol': '2881'
});
})()
using FubonNeo.Sdk;
using FugleMarketData.WebsocketModels;
var sdk = new FubonSDK();
var result = sdk.Login("Your ID", "Your password", "Your cert path", "Your cert password");
sdk.InitRealtime(); // 建立行情連線
// 可指定行情連線的Mode , Default 為Speed
// sdk.InitRealtime(Mode.Speed) or sdk.InitRealtime(Mode.Normal)
var stock = sdk.MarketData.WebSocketClient.Stock;
stock.OnMessage += (msg) => Console.WriteLine($"receive: {msg}");
await stock.Connect();
身份驗證
當驗證成功後,會收到以下訊息:
{
"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
SDK 每 30 秒會自動發送一次 ping 到伺服器;您也可以自行發送 ping,並可額外自訂 state(選填):
- Python
- Node.js
- C#
stock.ping('<ANY>')
stock.ping({state:'<ANY>'});
stock.Ping("<ANY>");
WebSocket Server 會回應以下訊息 (若 ping 未送 state 則不會有該欄位):
{
"event": "pong",
"data": {
"time": "<TIMESTAMP>",
"state": "<ANY>"
}
}
Channels
富邦行情 WebSocket API 目前提供以下可訂閱頻道:
trades- 接收訂閱股票最新成交資訊books- 接收訂閱股票最新最佳五檔委買委賣資訊indices- 接收訂閱股票最新指數行情資料
訂閱頻道
要訂閱一個頻道可用下方範例進行訂閱:
- Python
- Node.js
- C#
stock.subscribe({
"channel" : "<CHANNEL_NAME>",
"symbol" : "<SYMBOL_ID>"
#"intradayOddLot": True 若要訂閱盤中零股,可再額外加入此參數
})
stock.subscribe({
channel: '<CHANNEL_NAME>',
symbol: '<SYMBOL_ID>',
//intradayOddLot: true 若要訂閱盤中零股,可再額外加入此參數
});
stock.Subscribe(StockChannel.<CHANNEL_NAME>,"<SYMBOL_ID>");
//stock.Subscribe(StockChannel.Trades,new StockSubscribeParams{Symbol="<SYMBOL_ID>", IntradayOddLot=true}); 訂閱盤中零股
訂閱成功後,會收到以下事件回應:
{
"event": "subscribed",
"data": {
"id": "<CHANNEL_ID>",
"channel": "<CHANNEL_NAME>",
"symbol": "<SYMBOL_ID>"
}
}
支援訂閱同頻道的多檔股票:
- Python
- Node.js
- C#
stock.subscribe({
"channel" : "<CHANNEL_NAME>",
"symbols" : ["<SYMBOL_ID>","<SYMBOL_ID>"]
#"intradayOddLot": True 若要訂閱盤中零股,可再額外加入此參數
})
stock.subscribe({
channel: '<CHANNEL_NAME>',
symbols: ['<SYMBOL_ID>','<SYMBOL_ID>']
//intradayOddLot: true 若要訂閱盤中零股,可再額外加入此參數
});
stock.Subscribe(StockChannel.<CHANNEL_NAME>,"<SYMBOL_ID>","<SYMBOL_ID>");
//stock.Subscribe(StockChannel.Trades, new StockSubscribeParams{Symbols = new List<string>{"<SYMBOL_ID>", "<SYMBOL_ID>"}, IntradayOddLot=true}); 訂閱多檔盤中零股
訂閱成功後,會收到以下事件回應:
{
"event": "subscribed",
"data": [
{
"id": "<CHANNEL_ID>",
"channel": "<CHANNEL_NAME>",
"symbol": "<SYMBOL_ID_1>"
},
{
"id": "<CHANNEL_ID>",
"channel": "<CHANNEL_NAME>",
"symbol": "<SYMBOL_ID_2>"
}
]
}
取消訂閱
要取消頻道可用下方範例進行取消:
- Python
- Node.js
- C#
stock.unsubscribe({
'id':'<CHANNEL_ID>'
})
stock.unsubscribe({
id : '<CHANNEL_ID>'
});
stock.Unsubscribe("<CHANNEL_ID>");
取消訂閱成功後,會收到以下事件回應:
{
"event": "unsubscribed",
"data": {
"id": "<CHANNEL_ID>",
"channel" : "<CHANNEL_NAME>",
"symbol" : "<SYMBOL_ID>"
}
}
支援取消訂閱多個頻道:
- Python
- Node.js
- C#
stock.unsubscribe({
'ids':['<CHANNEL_ID>','<CHANNEL_ID>']
})
stock.unsubscribe({
ids : ['<CHANNEL_ID>','<CHANNEL_ID>']
});
stock.Unsubscribe("<CHANNEL_ID>","<CHANNEL_ID>");
取消訂閱成功後,會收到以下事件回應:
{
"event": "unsubscribed",
"data": [
{
"id": "<CHANNEL_ID_1>",
"channel" : "<CHANNEL_NAME>",
"symbol" : "<SYMBOL_ID>"
},
{
"id": "<CHANNEL_ID_2>",
"channel" : "<CHANNEL_NAME>",
"symbol" : "<SYMBOL_ID>"
}
]
}
訂閱資訊
要取得目前連線已訂閱的頻道清單,可用下方範例查詢:
- Python
- Node.js
stock.subscriptions()
stock.subscriptions();
會收到以下事件回應:
{
"event": "subscriptions",
"data": [
{
"id": "<CHANNEL_ID>",
"channel": "<CHANNEL_NAME>",
"symbol": "<SYMBOL_ID>"
}
]
}
錯誤處理
當您所訂閱或處理的 WebSocket Callback 有異常時,您可補充處理錯誤訊息如下。
disconnect 事件在兩種情況觸發:伺服器關閉連線,以及連線健康檢查逾時(超過約 60 秒未收到伺服器任何訊息時,SDK 會主動關閉連線並發出此事件)。逾時斷線在各語言的通知形態,見各範例下方說明。
- Python
- Node.js
- C#
def handle_connect():
print('market data connected')
def handle_disconnect(code, message, *reason): # 連線健康檢查逾時斷線時會多帶一個參數
print(f'market data disconnect: {code}, {message}')
def handle_error(error):
print(f'market data error: {error}')
stock.on("connect", handle_connect)
stock.on("disconnect", handle_disconnect)
stock.on("error", handle_error)
健康檢查逾時斷線時,disconnect 會多帶第三個參數 {'reason': 'health-check-timeout'},handler 以 *reason 接住即可。
stock.on("connect", () => {
console.log("market data connected");
});
stock.on("disconnect", (event, reason) => {
console.log("market data disconnect:", event.code, reason);
});
stock.on("error", (error) => {
console.log("market data error:", error);
});
健康檢查逾時斷線時,disconnect 的第二個參數為 { reason: 'health-check-timeout' }。
stock.OnConnected += (connmsg) => Console.WriteLine($"Connect: {connmsg}");
stock.OnDisconnected += (disconmsg) => Console.WriteLine($"Disconnect: {disconmsg}");
stock.OnError += (errmsg) => Console.WriteLine($"handle error: {errmsg}");
健康檢查需在 Connect 時以第二個參數開啟(Connect(5000, true),第一個參數為驗證逾時毫秒數);逾時斷線時 OnDisconnected 的訊息為 health-check-timeout。未開啟時,連線靜默中斷不會觸發 OnDisconnected。
斷線重連
連線中斷後,SDK 不會自動重新連線,也不會保留原有訂閱;程式需在收到 disconnect 事件後重新連線,並重新送出所有訂閱。以下範例接續上方的登入與建立連線程式:收到斷線事件後在背景重新連線與訂閱,重試間隔逐次拉長(2、4、8、16、30 秒)並以 5 次為上限,避免網路尚未恢復時短時間內大量重連。訂閱清單每個 頻道一筆、以 symbols 一次訂閱多檔,重連後重新訂閱的呼叫次數等於頻道數,不隨檔數增加。
- Python
- Node.js
- C#
# 接續 stock = sdk.marketdata.websocket_client.stock 之後,取代原本的 stock.connect()
import threading
import time
SUBSCRIPTIONS = [ # 初次訂閱與重連後重新訂閱共用同一份清單;每個頻道一筆,多檔用 symbols
{'channel': 'trades', 'symbols': ['2330', '2317']},
]
reconnect_needed = threading.Event()
def handle_disconnect(code, message, *reason): # 連線健康檢查逾時斷線時會多帶一個參數,用 *reason 接住
print(f'market data disconnect: {code}, {message}')
reconnect_needed.set() # 只通知,不在此直接重連
def subscribe_all():
for params in SUBSCRIPTIONS:
stock.subscribe(params)
def connect_with_timeout(seconds=10):
# 網路不通時 connect() 不會返回,另開執行緒加上逾時
result = {}
def run():
try:
stock.connect()
except Exception as error:
result['error'] = error
worker = threading.Thread(target=run, daemon=True)
worker.start()
worker.join(seconds)
if worker.is_alive():
raise TimeoutError('connect timeout')
if 'error' in result:
raise result['error']
def reconnect_loop():
retries = 0
while reconnect_needed.wait():
reconnect_needed.clear()
retries += 1
if retries > 5:
print('Reconnect failed 5 times, please check the network')
return
time.sleep(min(2 ** retries, 30)) # 等 2、4、8、16、30 秒後再試
try:
stock.disconnect() # 先重設連線狀態,否則 connect() 不會重新連線
connect_with_timeout()
subscribe_all()
retries = 0
print('Reconnected and resubscribed')
except Exception as error:
print(f'Reconnect failed: {error}')
reconnect_needed.set()
stock.on('disconnect', handle_disconnect)
threading.Thread(target=reconnect_loop, daemon=True).start()
stock.connect()
subscribe_all()
// 接續 sdk.login(...) 之後;initRealtime 與事件綁定改由 connectAndSubscribe() 處理
const SUBSCRIPTIONS = [ // 初次訂閱與重連後重新訂閱共用同一份清單;每個頻道一筆,多檔用 symbols
{ channel: 'trades', symbols: ['2330', '2317'] },
];
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let stock;
let reconnecting = false;
function handleMessage(message) {
console.log(JSON.parse(message));
}
async function connectAndSubscribe() {
sdk.initRealtime(); // 重連時重建行情連線物件,事件需重新綁定
stock = sdk.marketdata.webSocketClient.stock;
const client = stock;
client.on('message', handleMessage);
client.on('disconnect', (event, reason) => handleDisconnect(client, event, reason));
await Promise.race([ // 網路不通時 connect() 不會完成,加上逾時
client.connect(),
sleep(10000).then(() => { throw new Error('connect timeout'); }),
]);
for (const params of SUBSCRIPTIONS) client.subscribe(params);
}
async function handleDisconnect(client, event, reason) {
console.log('market data disconnect:', event.code, reason);
if (client !== stock || reconnecting) return; // 舊連線物件的事件、或已在重連中,略過
reconnecting = true;
try {
for (let retries = 1; retries <= 5; retries++) {
await sleep(Math.min(2 ** retries, 30) * 1000); // 等 2、4、8、16、30 秒後再試
try {
stock.disconnect(); // 關閉舊連線並停止其計時器
await connectAndSubscribe();
console.log('Reconnected and resubscribed');
return;
} catch (error) {
console.log(`Reconnect failed: ${error.message}`);
}
}
console.log('Reconnect failed 5 times, please check the network');
} finally {
reconnecting = false;
}
}
await connectAndSubscribe();
// 接續 var stock = sdk.MarketData.WebSocketClient.Stock; 之後,取代原本的 await stock.Connect()
var subscriptions = new[] { (StockChannel.Trades, new StockSubscribeParams { Symbols = new List<string> { "2330", "2317" } }) }; // 初次訂閱與重連後重新訂閱共用同一份清單;每個頻道一筆,多檔用 Symbols
var reconnecting = 0;
async Task SubscribeAll()
{
foreach (var (channel, param) in subscriptions)
await stock.Subscribe(channel, param);
}
stock.OnDisconnected += (msg) =>
{
Console.WriteLine($"market data disconnect: {msg}");
if (Interlocked.Exchange(ref reconnecting, 1) == 1) return; // 一次斷線可能收到多次通知,只保留一條重連流程
_ = Task.Run(async () =>
{
try
{
for (var retries = 1; retries <= 5; retries++)
{
await Task.Delay(TimeSpan.FromSeconds(Math.Min(Math.Pow(2, retries), 30))); // 等 2、4、8、16、30 秒後再試
try
{
await stock.Connect(5000, true); // 5 秒驗證逾時;開啟連線健康檢查
if (!stock.IsConnected) continue; // 驗證逾時時 Connect 不會拋出例外,需自行檢查
await SubscribeAll();
Console.WriteLine("Reconnected and resubscribed");
return;
}
catch (Exception ex)
{
Console.WriteLine($"Reconnect failed: {ex.Message}");
}
}
Console.WriteLine("Reconnect failed 5 times, please check the network");
}
finally
{
Interlocked.Exchange(ref reconnecting, 0);
}
});
};
await stock.Connect(5000, true); // 開啟連線健康檢查,連線靜默中斷時才會收到斷線通知
await SubscribeAll();