Enterprise WebSocket API

1. Getting Started

Enterprise Solution Overview

This documentation covers the WebSocket/PubSub solution designed specifically for enterprise clients.

Enterprise deployments use a different authentication flow than our public plans. This enhanced approach provides better security and reliability for business-critical operations.

Prerequisites

Before getting started, ensure you have the following:

1. Azure Active Directory Credentials - Our team will send these via email
2. WebSocket/PubSub Server Information - Connection details provided by our team
3. Implementation Knowledge - Familiarity with the two-step authentication process (covered in the next section)

Data Delivery Options

Our enterprise solution offers two data delivery methods to fit your infrastructure needs:

• WebSocket - Direct real-time communication
• Pub/Sub (Message Queue) - Better scalability for high-volume processing

2. Authentication

Enterprise Authentication Flow

Enterprise authentication uses a secure two-step process that ensures your connection is properly authorized.

Follow these steps in order to establish your authenticated connection:

1. Obtain Microsoft Azure OAuth Access Token

   Use the Azure credentials provided by our team to request an OAuth token from Microsoft:

   BASHCopy

   curl -X POST "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id={client_id}&scope={scope}&client_secret={client_secret}&grant_type=client_credentials"

   A successful request returns an access token:

   JSONCopy

   {
     "token_type": "Bearer",
     "expires_in": 3599,
     "ext_expires_in": 3599,
     "access_token": "eyJ0eXAiOi...JWT_TOKEN_HERE"
   }

2. Authenticate with Our Server

   Take the access_token from step 1 and use it to authenticate with our enterprise server:

   BASHCopy

   curl -X POST "https://{host_name}/.auth/login/aad" \
     -H "Content-Type: application/json" \
     -d '{"access_token": "JWT_TOKEN_HERE..."}'

   Our server responds with your final authentication token:

   JSONCopy

   {
     "authenticationToken": "ANOTHER_JWT_TOKEN_HERE",
     "user": {
       "userId": "sid:a50f42b1481ca31efcf853fabb13e95b"
     }
   }

Using the Authentication Token

Once you have your authentication token, connect to our WebSocket service:

1. Add the authenticationToken to your WebSocket headers as X-ZUMO-AUTH
2. This token authenticates all communications with our server

// Example WebSocket connection with authentication
const socket = new WebSocket('wss://{host_name}/ws');

// Set the authentication header before connecting
socket.setRequestHeader('X-ZUMO-AUTH', authenticationToken);

Email Registration

After connecting to the WebSocket server, register your support email for service communications.

// Send email registration after connection is established
socket.onopen = function() {
  // Register email for support purposes
  socket.send(JSON.stringify({
    "email": "your-engineering-team@example.com"
  }));
};

Note: This email is for support communications only, not verification. Choose an address your engineering team actively monitors for service updates and issue notifications.

Keeping Connections Alive (Optional)

Implement a ping-pong mechanism to maintain stable connections and detect network issues early.

Benefits: Regular pings help detect connection drops quickly, especially in environments with unreliable networks or proxy servers that terminate inactive connections.

3. Response Data Formats

Enterprise WebSocket responses use optimized field names to reduce bandwidth and improve performance.

This section covers the three main data types you'll receive: quotes, series data, and tick data.

Quote Data Format

Real-time market quotes provide current pricing and volume information.

The table below shows how standard field names are abbreviated in enterprise responses:

Example Quote Response:

{
  "c": "NASDAQ:AAPL",
  "lt": 1733432340.0,
  "v": 533779.0,
  "lp": 243.08,
  "a": 243.09,
  "b": 243.08,
  "as": 520.0,
  "bs": 430.0
}

Series Data Format

Series data provides OHLCV (Open, High, Low, Close, Volume) bar information for different time intervals.

The main response structure uses these abbreviated field names:

Each bar within the series array contains these OHLCV fields:

Example Series Response:

{
  "c": "NASDAQ:AAPL",
  "be": 1733432399.0,
  "lu": 1733432399820,
  "bt": "1m",
  "s": [
    {
      "t": 1733432340.0,
      "o": 242.89,
      "h": 243.09,
      "l": 242.82,
      "c": 243.08,
      "v": 533779.0
    }
  ]
}

Tick Data Format

Tick data represents individual trades with microsecond precision timestamps.

Each tick contains the following trade information:

Example Tick Data Response:

{
  "c": "NASDAQ:AAPL",
  "t": 1749462520.177003,
  "p": 242.89,
  "v": 200.0
}