WebSocket reference

Finazon offers a dynamic financial data platform powered by WebSocket technology. Developers gain instant access to real-time data streams for stocks, ETFs, cryptocurrencies, and more, enabling seamless integration and immersive user experiences. With WebSocket, bidirectional communication channels facilitate continuous updates and responsive applications, amplifying how financial data is utilized.

Connection and authorization

Authorization takes place when connecting to the WebSocket by passing the apikey parameter:

Limits

You're permitted up to 3 active connections for each workspace.
Each connection can handle up to 100 event messages every minute.
The maximum size for an event message is set at 100kb.
There's no cap on the number of tickers you can subscribe to, unless you set a specific limit during configuration.

If your application requires higher limits, you may reach out to our support.

Usage

pip install websocket-client rel
python finazon_ws_example.py

import json
import rel

import websocket

dataset = 'nlsp'
tickers = ['BTC/USD']
api_key = 'your_api_key'


def on_message(wsapp, message):
    print(f'Message: {message}')


def on_error(wsapp, error):
    print(f'Error: {error}')


def on_close(wsapp, close_status_code, close_msg):
    print('Connection is closed')


def on_open(wsapp):
    print('Connection is opened')
    subscribe(wsapp, dataset, tickers)


def subscribe(wsapp, dataset, tickers):
    sub_request = {
        'event': 'subscribe',
        'dataset': dataset,
        'tickers': tickers,
        'channel': 'bars',
        'frequency': '1s',
        'aggregation': '1m'
    }
    wsapp.send(json.dumps(sub_request))


if __name__ == '__main__':
    # Open ws connection
    ws = websocket.WebSocketApp(f'wss://ws.finazon.io/v1?apikey={api_key}',
                                on_open=on_open,
                                on_message=on_message,
                                on_error=on_error)
    # Start event loop
    ws.run_forever(
        # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly
        dispatcher=rel, reconnect=5,
        # Sending ping with specified interval to prevent disconnecting
        ping_interval=30, ping_timeout=10,
    )
    # Handle Keyboard Interrupt event
    rel.signal(2, rel.abort)
    rel.dispatch()

Subscribe to 1min candle updates within a minute (time_series). Make similar changes to other endpoints:

Parameters Responses

dataset

string

required

Filter by Finazon's dataset code
Example: nlsp

tickers

array

required

Subscribe to an array of ticker symbols. Possible options: see nlsp ticker list
Example: BTC/USD, ADX/USDT

frequency

string

required

Accepts 1s, 10s, and 1m options. Data will stream at 1-second, 10-second, or 1-minute intervals accordingly.

aggregation

string

required

Accepts 1m option. Data will stream 1-minute bars.

channel

string

required

Accepts bars option. Data will stream as bars (candles).

request_id

string | number

Request id returned with the response.

Event

{
  "event": "subscribe",
  "dataset": "nlsp",
  "tickers": [ "BTC/USD", "ADX/USDT" ],
  "channel": "bars",
  "frequency": "1s",
  "aggregation": "1m",
  "request_id": 106
}

Subscribe success

{
  "status": "success",
  "code": "SUCCESS_SUBSCRIPTION",
  "data": [ "BTC/USD", "ADX/USDT" ],
  "request_id": 106
}

Candle update

{
  "d": "nlsp",
  "p": "nasdaq",
  "ch": "bars",
  "f": "1s",
  "aggr":" 1m",
  "s": "BTC/USD",
  "t": 1699540020,
  "o": 220.06,
  "h": 220.13,
  "l": 219.92,
  "c": 219.96,
  "v": 4572
}

Unsubscribe

To unsubscribe from a channel, you can use the following configuration:

Parameters Responses

dataset

string

required

Filter by Finazon's dataset code
Example: nlsp

tickers

array

required

An array of ticker symbols to unsubscribe. Possible options: see nlsp ticker list
Example: BTC/USD, ADX/USDT

frequency

string

required

Accepts 1s, 10s, and 1m options. Data will stream at 1-second, 10-second, or 1-minute intervals accordingly.

aggregation

string

required

Accepts 1m option. Data will stream 1-minute bars.

channel

string

required

Accepts bars option. Data will stream as bars (candles).

request_id

string | number

Request id returned with the response.

event

string

Event code. Always unsubscribe

status

string

Unsubscription status. Possible statuses: success, error

code

string

Response code. Possible statuses: SUCCESS_UNSUBSCRIPTION

data

array of string

Symbols list. Example: BTC/USD, ADX/USDT

request_id

string | number

Request ID equal to request_id from incoming message

Event

{
  "event": "unsubscribe",
  "dataset": "nlsp",
  "tickers": [ "BTC/USD" ],
  "channel": "bars",
  "frequency": "1s",
  "aggregation": "1m",
  "request_id": 107
}

Unsubscribe success

{
  "status": "success",
  "code": "SUCCESS_UNSUBSCRIPTION",
  "data": [ "BTC/USD" ],
  "request_id": 107
}

Heartbeat

To check if the connection is still alive, you can use the following configuration:

Parameters Responses

request_id

string | number

Request id returned with the response.

event

string

Event code. Always heartbeat

status

string

Event status. Possible statuses: success

request_id

string | number

Request ID equal to request_id from incoming message

Event

{
  "event": "heartbeat",
  "request_id": 108
}

Heartbeat success

{
  "event": "heartbeat",
  "status": "success",
  "request_id": 108
}

Reset

To reset all active subscriptions, you can use the following configuration. Server doesn't reply to this message.

Parameters Responses

request_id

string | number

Request id returned with the response.

event

string

Event code. Always reset

status

string

Event status. Possible statuses: success

request_id

string | number

Request ID equal to request_id from incoming message

Event

{
  "event": "reset",
  "request_id": 109
}

Reset success

{
  "event": "reset",
  "status": "success",
  "request_id": 109
}

Ping

Client can send ping frames to server to make sure that the server is still alive. Ping message isn't text-based, It's a control frame. Pings have an opcode of 0x9, and pongs have an opcode of 0xA. When ping is sent to server, client receive a pong with the exact same Payload Data as the ping.