BrandSocket Async API 1.2.0 documentation

BrandSocket Async API 1.2.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

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.
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:
- production
- development
Accepts one of the following messages:
- #0
  application/json
  Message IDAccountStatus
  The account status message contains real time TradeLocker account status:
  
  balance
  
  equity
  
  marginAvailable
  
  marginUsed
  
  blockedBalance
  
  credit
  
  object
  type
  required
  string
  Allowed values:
  "AccountStatus"
  accountId
  required
  string
  Account identifier.
  
  currency
  required
  string
  Account currency.
  
  balance
  string
  Account balance.
  
  equity
  string
  Account equity.
  
  marginAvailable
  string
  Margin available for the account.
  
  marginUsed
  string
  Used margin.
  
  blockedBalance
  string
  Blocked balance.
  
  credit
  string
  Credit balance.
  
  Additional properties are allowed.
  Examples
  { "type": "AccountStatus", "accountId": "L#706984", "currency": "USD", "balance": "9888.95", "marginAvailable": "3583.45", "marginUsed": "6305.5", "equity": "10628.95" }
  
  This example has been generated automatically.
- #1
  application/json
  Message IDProperty
  object
  type
  required
  string
  Property messages. SyncEnd property message means that the initial data sync is over and the upcoming messages are realtime events from the Tradelocker engine.
  
  Allowed values:
  "Property"
  name
  required
  string
  Name of the property.
  
  Allowed values:
  "SyncEnd"
  Additional properties are allowed.
  Examples
  { "type": "Property", "name": "SyncEnd" }
  
  This example has been generated automatically.
- #2
  application/json
  Message IDOpenOrder
  object
  type
  string
  Allowed values:
  "OpenOrder"
  accountId
  string
  Account identifier.
  
  orderId
  string
  Unique order identifier.
  
  instrument
  string
  Trading instrument.
  
  amount
  string
  Order amount as a decimal string.
  
  lotSize
  string
  Lot size for the order.
  
  side
  string
  Side of the trade.
  
  Allowed values:
  "BUY"
  "SELL"
  price
  string
  Order price.
  
  status
  string
  Order status.
  
  Allowed values:
  "PENDING"
  "EXECUTED"
  "CANCELLED"
  Additional properties are allowed.
  Examples
  { "type": "OpenOrder", "accountId": "L#706984", "instrument": "AUDUSD", "orderId": "144115188077153593", "orderType": "MARKET", "status": "STATUS_FILLED", "positionId": "144115188076313665", "price": "0.62956", "side": "BUY", "amount": "10", "lotSize": "100000", "lastUpdate": "2025-01-27T13:43:57.532Z", "createdDateTime": "2025-01-27T13:43:57.327Z", "isOpen": true, "tif": "IOC", "trStopOffset": "0", "averageFilledPrice": "0.62962", "filledAmount": "10" }
  
  This example has been generated automatically.
- #3
  application/json
  Message IDPosition
  object
  type
  required
  string
  Type of the message.
  
  Allowed values:
  "Position"
  accountId
  required
  string
  Account identifier.
  
  positionId
  required
  string
  Unique position identifier.
  
  lots
  required
  string
  Number of lots in the position.
  
  lotSize
  string
  Size of each lot.
  
  units
  string
  Total number of units in the position.
  
  instrument
  required
  string
  Trading instrument for the position.
  
  openPrice
  required
  string
  Opening price for the position.
  
  openDateTime
  required
  string
  format: date-time
  The date and time when the position was opened.
  
  openOrderId
  required
  string
  Identifier of the order that opened the position.
  
  stopLossOrderId
  string | null
  Identifier of the associated stop-loss order, or null if not set.
  
  stopLossLimit
  string
  Stop-loss price limit.
  
  maintMargin
  required
  string
  Maintenance margin required for the position.
  
  takeProfitOrderId
  string | null
  Identifier of the associated take-profit order, or null if not set.
  
  takeProfitLimit
  string
  Take-profit price limit.
  
  side
  required
  string
  Side of the trade.
  
  Allowed values:
  "BUY"
  "SELL"
  fee
  string
  Commission fee associated with the position.
  
  swaps
  string
  Swap charges associated with the position.
  
  Additional properties are allowed.
  Examples
  { "type": "Position", "accountId": "L#617509", "lots": "0.01", "lotSize": "10", "units": "0.1", "instrument": "ETHUSD", "openPrice": "3299.71", "openDateTime": "2024-03-19T20:15:51.465Z", "positionId": "144115188076017329", "openOrderId": "144115188076017329", "maintMargin": "3.06485", "stopLossLimit": "0", "takeProfitLimit": "0", "side": "BUY", "fee": "0", "swaps": "0" }
  
  This example has been generated automatically.
- #4
  application/json
  Message IDClosePosition
  object
  type
  required
  string
  Allowed values:
  "ClosePosition"
  positionId
  required
  string
  Identifier of the closed position.
  
  closePrice
  string
  Price at which the position was closed.
  
  closeDateTime
  required
  string
  format: date-time
  Date and time when the position was closed.
  
  Additional properties are allowed.
  Examples
  { "type": "ClosePosition", "positionId": "144115188076313663", "closePrice": "0.62947", "closeDateTime": "2025-01-27T13:43:53.987Z" }
  
  This example has been generated automatically.
RECEIVE subscriptions
Socket.IO event subscriptions sends out messages containg instrument price changes.

Operation IDsubscriptions.subscribe
Available only on servers:
- production
- development
Accepts the following message:
Instrument price quotes.
application/json
Message IDInstrumentSubscriptionsAction
object
type
string
Allowed values:
"Quote"
instrument
string
Trading instrument identifier.

routeId
string
Route identifier for the quote.

timestamp
string
format: date-time
Time when the quote was generated.

bid
string
format: decimal
The bid price as a decimal string.

ask
string
format: decimal
The ask price as a decimal string.

Additional properties are allowed.
Examples
{ "type": "Quote", "instrument": "EURUSD", "routeId": "620892", "timestamp": "2025-03-19T18:12:52.584Z", "bid": "1.08919", "ask": "1.08921" }

This example has been generated automatically.
SEND subscriptions
Socket.IO event subscriptions receives messages for SUBSCRIBE and UNSUBSCRIBE to the instrument quotes.

Operation IDsubscriptions.publish
Available only on servers:
- production
- development
Accepts the following message:
Subscribe/Unsubscribe to a Quote stream per instrument name.
application/json
Message IDInstrumentSubscriptionsAction
object
Examples values:
{"action":"SUBSCRIBE","instrument":"EURUSD"}
{"action":"UNSUBSCRIBE","instrument":"EURUSD"}
action
string
Subscription action.

Allowed values:
"SUBSCRIBE"
"UNSUBSCRIBE"
instrument
string
Instrument name.

Additional properties are allowed.
Examples
#1 Example
{ "action": "SUBSCRIBE", "instrument": "EURUSD" }

#2 Example
{ "action": "UNSUBSCRIBE", "instrument": "EURUSD" }
RECEIVE connection
Events for disconnect or other connection errors.

Operation IDconnection.subscribe
Available only on servers:
- production
- development
Accepts one of the following messages:
- #0
  Connection updates and errors
  application/json
  Message IDConnectionErrorMessage
  object
  status
  string
  Connection status.
  
  Allowed values:
  "ok"
  "error"
  message
  string
  status message.
  
  Additional properties are allowed.
  Examples
  { "status": "ok", "message": "string" }
  
  This example has been generated automatically.
- #1
  General status message for connection updates and errors
  application/json
  Message IDStatusMessage
  object
  Examples values:
  {"status":"ok","code":"connected","message":"Connected successfully."}
  {"status":"ok","code":"disconnected","message":"Disconnect initiated."}
  {"status":"ok","code":"shutdown","message":"Brand Socket Service shutting down, disconnecting."}
  {"status":"error","code":"unauthorized.invalidApiKey","message":"Invalid API key provided, make sure header brand-api-key is valid."}
  {"status":"error","code":"unknown","message":"Unknown runtime error."}
  {"status":"error","code":"duplicateConnection","message":"New socket connection for brand 'BAPIA' initiated, disconnecting."}
  {"status":"error","code":"shutdown","message":"Brand Socket Service shutting down, disconnecting."}
  status
  required
  string
  Connection status.
  
  Allowed values:
  "ok"
  "error"
  code
  required
  string
  Status code identifying the specific event or error.
  
  message
  required
  string
  Detailed status message.
  
  Additional properties are allowed.
  Examples
  #1 Example
  { "status": "ok", "code": "connected", "message": "Connected successfully." }
  
  #2 Example
  { "status": "ok", "code": "disconnected", "message": "Disconnect initiated." }
  
  #3 Example
  { "status": "ok", "code": "shutdown", "message": "Brand Socket Service shutting down, disconnecting." }
  
  #4 Example
  { "status": "error", "code": "unauthorized.invalidApiKey", "message": "Invalid API key provided, make sure header brand-api-key is valid." }
  
  #5 Example
  { "status": "error", "code": "unknown", "message": "Unknown runtime error." }
  
  #6 Example
  { "status": "error", "code": "duplicateConnection", "message": "New socket connection for brand 'BAPIA' initiated, disconnecting." }
  
  #7 Example
  { "status": "error", "code": "shutdown", "message": "Brand Socket Service shutting down, disconnecting." }

Messages

#1
- application/json
Message IDAccountStatus
The account status message contains real time TradeLocker account status:

balance

equity

marginAvailable

marginUsed

blockedBalance

credit
object
type
required
string
Allowed values:
"AccountStatus"
accountId
required
string
Account identifier.

currency
required
string
Account currency.

balance
string
Account balance.

equity
string
Account equity.

marginAvailable
string
Margin available for the account.

marginUsed
string
Used margin.

blockedBalance
string
Blocked balance.

credit
string
Credit balance.

Additional properties are allowed.
#2
- application/json
Message IDProperty
object
type
required
string
Property messages. SyncEnd property message means that the initial data sync is over and the upcoming messages are realtime events from the Tradelocker engine.

Allowed values:
"Property"
name
required
string
Name of the property.

Allowed values:
"SyncEnd"
Additional properties are allowed.
#3
- application/json
Message IDPosition
object
type
required
string
Type of the message.

Allowed values:
"Position"
accountId
required
string
Account identifier.

positionId
required
string
Unique position identifier.

lots
required
string
Number of lots in the position.

lotSize
string
Size of each lot.

units
string
Total number of units in the position.

instrument
required
string
Trading instrument for the position.

openPrice
required
string
Opening price for the position.

openDateTime
required
string
format: date-time
The date and time when the position was opened.

openOrderId
required
string
Identifier of the order that opened the position.

stopLossOrderId
string | null
Identifier of the associated stop-loss order, or null if not set.

stopLossLimit
string
Stop-loss price limit.

maintMargin
required
string
Maintenance margin required for the position.

takeProfitOrderId
string | null
Identifier of the associated take-profit order, or null if not set.

takeProfitLimit
string
Take-profit price limit.

side
required
string
Side of the trade.

Allowed values:
"BUY"
"SELL"
fee
string
Commission fee associated with the position.

swaps
string
Swap charges associated with the position.

Additional properties are allowed.
#4
- application/json
Message IDClosePosition
object
type
required
string
Allowed values:
"ClosePosition"
positionId
required
string
Identifier of the closed position.

closePrice
string
Price at which the position was closed.

closeDateTime
required
string
format: date-time
Date and time when the position was closed.

Additional properties are allowed.
#5
- application/json
Message IDOpenOrder
object
type
string
Allowed values:
"OpenOrder"
accountId
string
Account identifier.

orderId
string
Unique order identifier.

instrument
string
Trading instrument.

amount
string
Order amount as a decimal string.

lotSize
string
Lot size for the order.

side
string
Side of the trade.

Allowed values:
"BUY"
"SELL"
price
string
Order price.

status
string
Order status.

Allowed values:
"PENDING"
"EXECUTED"
"CANCELLED"
Additional properties are allowed.
#6
Subscribe/Unsubscribe to a Quote stream per instrument name.
- application/json
Message IDInstrumentSubscriptionsAction
object
Examples values:
{"action":"SUBSCRIBE","instrument":"EURUSD"}
{"action":"UNSUBSCRIBE","instrument":"EURUSD"}
action
string
Subscription action.

Allowed values:
"SUBSCRIBE"
"UNSUBSCRIBE"
instrument
string
Instrument name.

Additional properties are allowed.
#7
Instrument price quotes.
- application/json
Message IDQuote
object
type
string
Allowed values:
"Quote"
instrument
string
Trading instrument identifier.

routeId
string
Route identifier for the quote.

timestamp
string
format: date-time
Time when the quote was generated.

bid
string
format: decimal
The bid price as a decimal string.

ask
string
format: decimal
The ask price as a decimal string.

Additional properties are allowed.
#8
Connection updates and errors
- application/json
Message IDConnectionErrorMessage
object
status
string
Connection status.

Allowed values:
"ok"
"error"
message
string
status message.

Additional properties are allowed.
#9
General status message for connection updates and errors
- application/json
Message IDStatusMessage
object
Examples values:
{"status":"ok","code":"connected","message":"Connected successfully."}
{"status":"ok","code":"disconnected","message":"Disconnect initiated."}
{"status":"ok","code":"shutdown","message":"Brand Socket Service shutting down, disconnecting."}
{"status":"error","code":"unauthorized.invalidApiKey","message":"Invalid API key provided, make sure header brand-api-key is valid."}
{"status":"error","code":"unknown","message":"Unknown runtime error."}
{"status":"error","code":"duplicateConnection","message":"New socket connection for brand 'BAPIA' initiated, disconnecting."}
{"status":"error","code":"shutdown","message":"Brand Socket Service shutting down, disconnecting."}
status
required
string
Connection status.

Allowed values:
"ok"
"error"
code
required
string
Status code identifying the specific event or error.

message
required
string
Detailed status message.

Additional properties are allowed.

BrandSocket Async API 1.2.0

Why WebSocket API?

Getting Started

Message Types

The Socket.IO server configuration:

Implementation Example

Brand API documentation

Servers

Operations

RECEIVE stream

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

RECEIVE subscriptions

Examples

This example has been generated automatically.

SEND subscriptions

Examples

#1 Example

#2 Example

RECEIVE connection

Examples

This example has been generated automatically.

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

#6 Example

#7 Example

Messages