BrandSocket Async API 3.0.0

Welcome to the BrandSocket WebSocket API, designed to provide seamless and efficient live data streaming for brands using the Tradelocker platform. By leveraging the Socket.IO protocol, BrandSocket offers real-time updates and actionable insights, enabling you to make informed and timely decisions.

Compared to traditional REST APIs, which rely on frequent polling to retrieve updates, the WebSocket API maintains an always-on connection. This approach ensures you receive data changes as they happen, reducing latency and improving responsiveness.

Why WebSocket API?

Real-time updates - Instantly react to market changes, account status updates, and trade activities.
Efficient resource usage - Maintain a single persistent connection instead of repeatedly querying for updates.
Enhanced decision-making -Leverage live data to optimize trading strategies and outcomes.

Getting Started

  1. Setting Up the Connection
    To start streaming data, establish a WebSocket connection to BrandSocket using the Socket.IO client library. Once connected, the server will immediately begin streaming an initial set of data.

  2. Initial Data Synchronization
    When the connection is first established, BrandSocket sends a stream of messages containing the current state of your accounts, positions, and open orders. Once all the initial data has been sent, you will receive a special message type: SyncEnd

SyncEnd message signifies the completion of the initial data synchronization process.
After receiving SyncEnd, the server will only send updates for new events or changes in the data.

Message Types

BrandSocket sends different types of messages to keep you updated on key events:

  • AccountStatus: Provides updates about the status of an account, such as changes in balance, margin, or account status.

  • SyncEnd: Indicates that the initial synchronization of data is complete. After this, only updates will be sent.

  • Position: Updates on opening or modifying a positions.

  • ClosePosition: Sent when a position is closed, providing details of the closure, such as time and realized P&L.

  • OpenOrder: Details about new or updated order, allowing you to track pending trades in real-time.

The Socket.IO server configuration:

  • Namespace: /brand-socket
  • Handshake path: /brand-socket/socket.io
  • Transport: websocket

Implementation Example

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

// Configuration
const SERVER_URL = 'wss://api-dev.tradelocker.com';
const NAMESPACE = '/brand-socket';
const BRAND_API_KEY = '<your-brand-api-key>';
const HANDSHAKE_PATH = '/brand-api/socket.io';
const QUERY_PARAM_TYPE = 'LIVE';

// Create a connection to the Socket.IO server
const socket = io(SERVER_URL + NAMESPACE, {
  path: HANDSHAKE_PATH, // Custom handshake path
  transports: ['websocket'], // Use websocket transport
  query: {
    type: QUERY_PARAM_TYPE,
  },
  extraHeaders: {
    'brand-api-key': BRAND_API_KEY, // Add custom API key header
  },
});

// Event listeners
socket.on('connect', () => {
  console.log('Connected to Socket.IO server');
  console.log(`Socket ID: ${socket.id}`);
});

socket.on('stream', (data: any) => {
  console.log('stream: ', data);
});

// event listener for 'connection' events
socket.on('connection', (data: any) => {
  console.error('connection: ', data);
});

socket.on('disconnect', (reason) => {
  console.log('Disconnected: ', reason);
});

socket.on('error', (error) => {
  console.log('error: ', error);
});

// Disconnect after 30 seconds
setTimeout(() => {
  socket.disconnect();
  console.log('Disconnected manually');
}, 30000);

Brand API documentation

To explore the REST API documentation visit https://brand-docs.tradelocker.com/

Servers

  • wss://api.tradelocker.com/brand-api/socket.io/?type=LIVEwssproduction

    Production server for BrandSocket API.

    object
    type
    required
    string

    Query parameter for environment type.

    Default value:"LIVE"
      Allowed values:
    • "LIVE"
    • "DEMO"
  • wss://api-dev.tradelocker.com/brand-api/socket.io/?type=LIVEwssdevelopment

    Development server for BrandSocket API.

    object
    type
    required
    string

    Query parameter for environment type.

    Default value:"LIVE"
      Allowed values:
    • "LIVE"
    • "DEMO"

Operations

  • RECEIVE stream

    Socket.IO event stream

    Subscribe to this event to receive all updates from BrandSocket server.

    Operation IDstream.subscribe

    Available only on servers:

    Accepts one of the following messages:

    • #0AccountStatus
      Message IDAccountStatus

      The account status message contains real time TradeLocker account status:

      • balance
      • equity
      • marginAvailable
      • marginUsed
      • blockedBalance
      • credit
      object

      Examples

    • #1Property
      Message IDProperty
      object

      Examples

    • #2OpenOrder
      Message IDOpenOrder
      object

      Examples

    • #3Position
      Message IDPosition
      object

      Examples

    • #4ClosePosition
      Message IDClosePosition
      object

      Examples

  • RECEIVE connection

    Events for disconnect or other connection errors.

    Operation IDconnection.subscribe

    Available only on servers:

    Accepts the following message:

    ConnectionErrorMessage

    Connection updates and errors

    Message IDConnectionErrorMessage
    object

    Examples

Messages

  • #1AccountStatus
    Message IDAccountStatus

    The account status message contains real time TradeLocker account status:

    • balance
    • equity
    • marginAvailable
    • marginUsed
    • blockedBalance
    • credit
    object
  • #2Property
    Message IDProperty
    object
  • #3Position
    Message IDPosition
    object
  • #4ClosePosition
    Message IDClosePosition
    object
  • #5OpenOrder
    Message IDOpenOrder
    object
  • #6ConnectionErrorMessage

    Connection updates and errors

    Message IDConnectionErrorMessage
    object