Websocket V1

WebSocket API Documentation for real time Tickers Monitoring

Overview

This API allows clients to subscribe to real-time updates of ticker states via a WebSocket connection. The service supports operations to subscribe and unsubscribe to specific token tickers, ensuring clients receive updates for only their tokens of interest.

Note: When using the WebSocket, we append a sentTimestampMs field to each ticker object. This field represents the timestamp (in milliseconds) at which the record was transmitted.

WebSocket endpoint

WebSocket communication is implemented using a socket.io server, providing built-in support for automatic message compression and automatic reconnections, making client integration simpler and more reliable.

To connect, use the following WebSocket endpoint:

• Server URL: https://pricing.aleno.ai

• Socket.IO path: /v1/socket

Javascript Example (using socket.io-client):

import { io } from 'socket.io-client';

const socket = io('https://pricing.aleno.ai', {
  path: '/v1/socket',
});

To use this javascript code, you need to install socket.io-client package: https://www.npmjs.com/package/socket.io-client

Subscribing to Token Updates

After connecting, clients can subscribe to receive updates for specific token tickers. The subscription request should specify the tickers the client is interested in as a list of strings.

• If arguments are wrongly typed, no changes will be applied.

• Currently, updates are sent every 1 sec.

import { io } from 'socket.io-client';

const socket = io(`https://pricing.aleno.ai`, {
  path: '/v1/socket',
});

socket.on('connect', () => {
  console.log('Connected to the server');

  // Subscribe to tickers with acknowledgment
  const tickersToSubscribe = ['ETH/USD', 'BTC/USD'];
  socket.emit('subscribe_ticker', tickersToSubscribe, (response) => {
    if (response.status === 'ok') {
      console.log('Subscription successful:', response.subscriptionsAfterUpdate);
    } else {
      console.log('Subscription failed:', response);
    }
  });
});

// Handle incoming updates
socket.on('new_token_states', (data) => {
  console.log('Received token state updates:', data);
});

// Event listener for connection errors
socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

Unsubscribing from token updated

Clients can unsubscribe from tickers they are no longer interested in by sending an unsubscribe request.

/// Unsubscribe from a ticker
const tickersToUnsubscribe = ['BTC/USD'];
socket.emit('unsubscribe_ticker', tickersToUnsubscribe, (response) => {
  if (response.status === 'ok') {
    console.log('Unsubscription successful:', response.subscriptionsAfterUpdate);
  } else {
    console.log('Unsubscription failed:', response);
  }
});

Handling updates

When the server processes a new block and updates token states, it emits a list of BaseTokenState with an additional field sentTimestampMs indicating the precise time of the update.

Handling Acknowledgements

The server provides callbacks for both subscribe and unsubscribe events, enabling the client to handle acknowledgments effectively. These callbacks offer structured feedback that informs the client of the outcome of their subscription management actions.

Callback Payload Structure:

• status: A string indicating the result of the operation. It returns 'ok' for successful operations and an error code or message for unsuccessful attempts.

• involvedSubscriptions: An array of tickers that were part of the request, indicating which tickers were attempted to be subscribed or unsubscribed.

• subscriptionsAfterUpdate: An array listing all tickers the client is currently subscribed to following the operation. This provides a clear and updated snapshot of active subscriptions, ensuring the client has accurate information to manage their subscriptions effectively.

Outcomes:

• Successful Operation: The status will be 'ok', and Subscriptions After Update will reflect the new state of subscriptions after the operation.

• Unsuccessful Operation: The status will contain an error message detailing why the operation failed. The Subscriptions After Update will show the current state of subscriptions, unchanged by the failed operation.

This callback mechanism is critical for maintaining an accurate and reliable subscription list on the client side, allowing immediate verification and management of subscriptions based on real-time server feedback.

Handling Server Crashes and Connection Losses

While Socket.IO automatically handles the reconnection process in the event of a connection loss, it's important to note that any active subscriptions might be lost if the server crashes unexpectedly. Therefore, the client is responsible for ensuring that subscription requests are reissued upon successfully reestablishing a connection. This proactive management of subscriptions ensures that the client receives timely updates without interruption, even after server downtime or network disruptions.

To address this, implement logic in your client that automatically resubscribes to the necessary feeds as soon as the connection is restored. This approach helps maintain a consistent flow of data updates and minimizes the operational impact of unexpected server crashes.