Skip to main content

Quick Start

Key takeaways
  • Fubon Futures Market Data WebSocket API provides real-time futures subscriptions.
  • Supports Speed and Normal modes.
  • Login is required before subscribing to channels.
ItemDetails
InterfaceWebSocket API
MarketTaiwan futures / options
ModesSpeed / Normal
SDKPython / Node.js / C#
SubscriptionConnect then subscribe to channels

Fubon Futures Market Data WebSocket API provides real-time futures market data for Taiwan.

Using SDK​

Fubon Futures Market Data WebSocket API provides Python, Node.js, and C# SDKs. You can access the WebSocket API through the following methods:

And subscribe webSocket callback method to receive the callback messages below.

info

WebSocket api provides Low Latency Speed Mode and Multi-Information Normal Mode.

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()
# Offer MarketData Mode ， Default : Speed 
# sdk.init_realtime(Mode.Speed) or sdk.init_realtime(Mode.Normal)

futopt = sdk.marketdata.websocket_client.futopt
futopt.on('message', handle_message)
futopt.connect()

Authenticated​

When the verification is successful, you will receive the following message：

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

When the verification is failed, you will receive the following message：

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

Heartbeat​

Every 30 seconds, the WebSocket server will send out a heartbeat message：

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

Ping/Pong​

Every 30 seconds, sdk will send the following JSON-formatted message to the WebSocket Server, or follow the below example (where state is optional)：

futopt.ping({
  'state' : '<ANY>'
})

The WebSocket Server will respond with the following message (if ping was sent, the state field will not be present):

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

Channels​

The Fubon Futures Market Data WebSocket API currently provides the following subscribable channels:

Continuous Month Aliases​

In addition to a concrete contract symbol (e.g. TXFG6), the symbol used when subscribing can also be a continuous month alias: {ROOT}1!／2!／3!, which subscribes to the 1st／2nd／3rd nearby month contract (e.g. TXF1! for the nearest-month Taiwan stock index future). The system automatically resolves the alias to the currently corresponding concrete contract and rolls over automatically after settlement; the symbol returned in data events is the resolved concrete contract code. See Web API — Contract Symbols and Continuous Month Aliases for details.

futopt.subscribe({
  "channel": "trades",
  "symbol": "TXF1!"  # Continuous month alias, subscribes to the nearest-month Taiwan stock index future
  #"afterHours" : True   Subscribe after-hours 
})

v2.2.9 Advanced Futures/Options Market Data​

  • Continuous-month quotes: Subscribe with a {ROOT}1!/2!/3! nearby-month alias; see “Continuous Month Aliases” above.
  • Spread-contract quotes: First retrieve spread contract symbols with isSpread=true from Intraday Tickers, then use the returned symbol in the WebSocket subscription.
  • Derived best-level quotes: derivedBid/derivedAsk in the books channel provide a derived best quote level, primarily for spread contracts.
  • Trial-matching information: isTrial in books and lastTrial in aggregates disclose information for the trial-matching phase.

Subscribe Channel​

Subscribe to a channel, send following example to the WebSocket Server：

futopt.subscribe({
  "channel" : "<CHANNEL_NAME>",
  "symbol" : "<SYMBOL_ID>"
  #"afterHours" : True   Subscribe after-hours 
})

After a successful subscription, you will receive the following event response：

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

Supports the subscription of multiple stocks within the same channel：

futopt.subscribe({
  "channel" : "<CHANNEL_NAME>",
  "symbols" : ["<SYMBOL_ID>","<SYMBOL_ID>"]
  #"afterHours" : True  Subscribe after-hours 
})

After a successful subscription, you will receive the following event response：

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

Unsubscribe​

Unsubscribe from a subscribed channel, please send the following example to WebSocket Server：

futopt.unsubscribe({
    'id':'<CHANNEL_ID>'
})

After a successful unsubscription, you will receive the following event response：

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

Supports the unsubscription from multiple channels：

futopt.unsubscribe({
    'ids':['<CHANNEL_ID>','<CHANNEL_ID>']
})

After a successful unsubscription, you will receive the following event response：

{
  "event": "unsubscribed",
  "data": [
    {
      "id": "<CHANNEL_ID_1>",
      "channel" : "<CHANNEL_NAME>",
      "symbol" : "<SYMBOL_ID>"
    },
    {
      "id": "<CHANNEL_ID_2>",
      "channel" : "<CHANNEL_NAME>",
      "symbol" : "<SYMBOL_ID>"
    }
  ]
}

Error Handle​

When there is an anomaly in the WebSocket callback you subscribed to or processed, you can handle error messages as follows：

def handle_connect():
    print('market data connected')


def handle_disconnect(code, message):
    print(f'market data disconnect: {code}, {message}')


def handle_error(error):
    print(f'market data error: {error}')

futopt.on("connect", handle_connect)
futopt.on("disconnect", handle_disconnect)
futopt.on("error", handle_error)

Reconnection​

The following is a simple demonstration that automatically reconnects the websocket when a disconnection event is detected using a callback:

def handle_disconnect(code, message):
    print(f'market data disconnect: {code}, {message}')
    futopt.connect()
    print("Reconnected Succuess")
    print("Resubscribe")
    futopt.subscribe({    # 重新訂閱您已訂閱過的Channel與Symbol
        'channel': '<CHANNEL_NAME>', 
        'symbol': '<SYMBOL_ID>'
    })