Streams API 1.0.1 documentation

Streams API 1.0.1

application/json

Welcome to Tradelocker Streams API, designed to provide seamless and efficient live data streaming for third parties using the Tradelocker platform.

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, establish a WebSocket connection to Tradelocker Streams API using the Socket.IO client library. Once connected, the server will immediately begin streaming an initial set of data. You must send the developer-api-key header.
Getting a Streams API token for an account
Call the new auth endpoint on our Tradelocker Backend API which will return Streams API JWT tokens for all of the user's accounts. You should not send the developer-api-key header for this request.
Subscribing to an account
Subscribe to the account using the JWT, the account ID, and the Brand ID (Server name). Use Socket.IO's ACK functionality. You will receive responses regarding successful or unsucessful subscriptions.
Initial Data Synchronization
When the account subscription connection is first established, the API sends a stream of messages containing the current state of the user's accounts, positions, and open orders. Once all the initial data has been sent, you will receive a special message type: Property name: SyncEnd. This message indicates that the initial synchronization is complete, and the API will only send updates for new events or changes in the data.

Message Types

Streams API 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.
Property: messages are used for special signals. Property message with name: SyncEnd 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.
Position: Updates on opening or modifying 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: /streams-api
Handshake path: /streams-api/socket.io
Transport: websocket

Servers

https://stg.tradelocker.com/backend-apihttpsstaging-tl-api
Development server for Tradelocker Backend API.
wss://api.tradelocker.com/streams-api/socket.iowssproduction
Production server for Tradelocker Streams API.
wss://api-dev.tradelocker.com/streams-api/socket.iowssdevelopment
Development server for Tradelocker Streams API.

Operations

REQUEST /auth/jwt/accounts/tokens
Operation IDget-tokens
Available only on servers:
- staging-tl-api
object
method
POST
Accepts the following message:
Combination of the user's email, password and server
application/json
Message IDuserMessage
object
Examples values:
{"email":"[email protected]","password":"Password1!","server":"BAPIA"}
email
string
password
string
server
string
Additional properties are allowed.
Examples
#1 Example
{ "email": "[email protected]", "password": "Password1!", "server": "BAPIA" }
REPLY INFORMATION
REPLY CHANNEL INFORMATION
Reply will be provided via this designated address: /auth/jwt/accounts/tokens
Address: /auth/jwt/accounts/tokens
Available only on servers:
staging-tl-api
Message:
Combination of the user's email, password and server
application/json
Message IDuserMessage
object
Examples values:
{"email":"[email protected]","password":"Password1!","server":"BAPIA"}
email
string
password
string
server
string
Additional properties are allowed.
Examples
#1 Example
{ "email": "[email protected]", "password": "Password1!", "server": "BAPIA" }

application/json
Message IDGetAccountTokensResponse
object
object
accessToken
required
string
JWT token for API access

expireDate
required
string
format: date-time
Token expiration date

accountId
required
string
User account identifier

Additional properties are allowed.
Additional properties are allowed.
Examples
{ "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", "expireDate": "2025-04-02T09:28:32.000Z", "accountId": "L#737031" } }

This example has been generated automatically.
RECEIVE stream
Socket.IO event stream

Subscribe to this event to receive all updates for accounts.

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.
  
  balanceWithoutCredit
  string
  Account balance without credit.
  
  equity
  string
  Account equity.
  
  marginAvailable
  string
  Margin available for the account.
  
  marginUsed
  string
  Used margin.
  
  blockedBalance
  string
  Blocked balance.
  
  credit
  string
  Credit balance.
  
  brandId
  string
  Brand ID (Server field from HTTP auth endpoint).
  
  userId
  string
  User ID (UUID).
  
  Additional properties are allowed.
  Examples
  { "type": "AccountStatus", "accountId": "L#706984", "currency": "USD", "balance": "9888.95", "marginAvailable": "3583.45", "marginUsed": "6305.5", "equity": "10628.95", "brandId": "BAPIA", "userId": "4f78705c-d09e-4fa8-9744-7a87d81b4327" }
  
  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"
  brandId
  string
  Brand ID (Server field from HTTP auth endpoint).
  
  userId
  string
  User ID (UUID).
  
  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", "brandId": "BAPIA", "userId": "4f78705c-d09e-4fa8-9744-7a87d81b4327" }
  
  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.
  
  maintMargin
  required
  string
  Maintenance margin required for the position.
  
  takeProfitOrderId
  string | null
  Identifier of the associated take-profit order, or null if not set.
  
  side
  required
  string
  Side of the trade.
  
  Allowed values:
  "BUY"
  "SELL"
  brandId
  string
  Brand ID (Server field from HTTP auth endpoint).
  
  userId
  string
  User ID (UUID).
  
  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", "side": "BUY", "fee": "0", "swaps": "0", "brandId": "BAPIA", "userId": "4f78705c-d09e-4fa8-9744-7a87d81b4327" }
  
  This example has been generated automatically.
- #4
  application/json
  Message IDClosePosition
  object
  type
  required
  string
  Allowed values:
  "ClosePosition"
  accountId
  string
  Account identifier.
  
  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.
  
  brandId
  string
  Brand ID (Server field from HTTP auth endpoint).
  
  userId
  string
  User ID (UUID).
  
  Additional properties are allowed.
  Examples
  { "type": "ClosePosition", "accountId": "L#775077", "positionId": "144115188076313663", "closePrice": "0.62947", "closeDateTime": "2025-01-27T13:43:53.987Z", "brandId": "BAPIA", "userId": "4f78705c-d09e-4fa8-9744-7a87d81b4327" }
  
  This example has been generated automatically.
REQUEST subscriptions
Socket.IO event subscriptions receives messages for SUBSCRIBE and UNSUBSCRIBE to an account stream.

Socket.IO event that handles subscription actions with acknowledgment responses.

Operation IDsubscriptions.publish
Available only on servers:
- production
- development
Accepts one of the following messages:
- #0
  Subscribe to an account stream
  application/json
  Message IDAccountSubscribeAction
  object
  action
  string
  Subscription action.
  
  Allowed values:
  "SUBSCRIBE"
  token
  string
  JWT token retrieved from HTTP auth endpoint.
  
  Additional properties are allowed.
  Examples
  { "action": "SUBSCRIBE", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30" }
  
  This example has been generated automatically.
- #1
  Unsubscribe from an account stream
  application/json
  Message IDAccountUnsubscribeAction
  object
  action
  string
  Subscription action.
  
  Allowed values:
  "UNSUBSCRIBE"
  accountId
  string
  User account identifier
  
  brandId
  string
  Brand identifier (server from HTTP auth endpoint)
  
  Additional properties are allowed.
  Examples
  { "action": "UNSUBSCRIBE", "accountId": "L#737031", "brandId": "BAPIA" }
  
  This example has been generated automatically.
REPLY INFORMATION
REPLY CHANNEL INFORMATION
#0
General status message for updates and errors
application/json
Message IDStatusMessage
object
Examples values:
{"status":"ok","code":"connected","message":"Successfully connected to the streams socket server."}
{"status":"ok","code":"disconnected","message":"Disconnect initiated."}
{"status":"ok","code":"shutdown","message":"Streams Socket Service shutting down, disconnecting."}
{"status":"error","code":"unauthorized.invalidApiKey","message":"Invalid API key provided, make sure header developer-api-key is valid."}
{"status":"error","code":"unknown","message":"Unknown runtime error."}
{"status":"ok","code":"connected","message":"Connected to account BAPIA#L#737031","remainingRequests":29}
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.

remainingRequests
number
Number of requests remaining in time window until rate limited (currently applies only for the SUBSCRIBE action).

Additional properties are allowed.
Examples
#1 Example
{ "status": "ok", "code": "connected", "message": "Successfully connected to the streams socket server." }

#2 Example
{ "status": "ok", "code": "disconnected", "message": "Disconnect initiated." }

#3 Example
{ "status": "ok", "code": "shutdown", "message": "Streams Socket Service shutting down, disconnecting." }

#4 Example
{ "status": "error", "code": "unauthorized.invalidApiKey", "message": "Invalid API key provided, make sure header developer-api-key is valid." }

#5 Example
{ "status": "error", "code": "unknown", "message": "Unknown runtime error." }

#6 Example
{ "status": "ok", "code": "connected", "message": "Connected to account BAPIA#L#737031", "remainingRequests": 29 }

#1
Error acknowledgment for subscription actions
application/json
Message IDSubscriptionErrorAck
object
Examples values:
{"status":"error","code":"invalidJwt","message":"jwt expired"}
{"status":"error","code":"accountNotFound","message":"Account not found"}
status
required
string
Status of the response.

Allowed values:
"error"
code
required
string
Error code identifying the specific error.

Allowed values:
"invalidJwt"
"accountNotFound"
"unauthorized"
"rateLimit"
message
required
string
Detailed error message.

Additional properties are allowed.
Examples
#1 Example
{ "status": "error", "code": "invalidJwt", "message": "jwt expired" }

#2 Example
{ "status": "error", "code": "accountNotFound", "message": "Account not found" }
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 updates and errors
  application/json
  Message IDStatusMessage
  object
  Examples values:
  {"status":"ok","code":"connected","message":"Successfully connected to the streams socket server."}
  {"status":"ok","code":"disconnected","message":"Disconnect initiated."}
  {"status":"ok","code":"shutdown","message":"Streams Socket Service shutting down, disconnecting."}
  {"status":"error","code":"unauthorized.invalidApiKey","message":"Invalid API key provided, make sure header developer-api-key is valid."}
  {"status":"error","code":"unknown","message":"Unknown runtime error."}
  {"status":"ok","code":"connected","message":"Connected to account BAPIA#L#737031","remainingRequests":29}
  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.
  
  remainingRequests
  number
  Number of requests remaining in time window until rate limited (currently applies only for the SUBSCRIBE action).
  
  Additional properties are allowed.
  Examples
  #1 Example
  { "status": "ok", "code": "connected", "message": "Successfully connected to the streams socket server." }
  
  #2 Example
  { "status": "ok", "code": "disconnected", "message": "Disconnect initiated." }
  
  #3 Example
  { "status": "ok", "code": "shutdown", "message": "Streams Socket Service shutting down, disconnecting." }
  
  #4 Example
  { "status": "error", "code": "unauthorized.invalidApiKey", "message": "Invalid API key provided, make sure header developer-api-key is valid." }
  
  #5 Example
  { "status": "error", "code": "unknown", "message": "Unknown runtime error." }
  
  #6 Example
  { "status": "ok", "code": "connected", "message": "Connected to account BAPIA#L#737031", "remainingRequests": 29 }

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.

balanceWithoutCredit
string
Account balance without credit.

equity
string
Account equity.

marginAvailable
string
Margin available for the account.

marginUsed
string
Used margin.

blockedBalance
string
Blocked balance.

credit
string
Credit balance.

brandId
string
Brand ID (Server field from HTTP auth endpoint).

userId
string
User ID (UUID).

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.

maintMargin
required
string
Maintenance margin required for the position.

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

side
required
string
Side of the trade.

Allowed values:
"BUY"
"SELL"
brandId
string
Brand ID (Server field from HTTP auth endpoint).

userId
string
User ID (UUID).

Additional properties are allowed.
#4
- application/json
Message IDClosePosition
object
type
required
string
Allowed values:
"ClosePosition"
accountId
string
Account identifier.

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.

brandId
string
Brand ID (Server field from HTTP auth endpoint).

userId
string
User ID (UUID).

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"
brandId
string
Brand ID (Server field from HTTP auth endpoint).

userId
string
User ID (UUID).

Additional properties are allowed.
#6
Subscribe to an account stream
- application/json
Message IDAccountSubscribeAction
object
action
string
Subscription action.

Allowed values:
"SUBSCRIBE"
token
string
JWT token retrieved from HTTP auth endpoint.

Additional properties are allowed.
#7
Unsubscribe from an account stream
- application/json
Message IDAccountUnsubscribeAction
object
action
string
Subscription action.

Allowed values:
"UNSUBSCRIBE"
accountId
string
User account identifier

brandId
string
Brand identifier (server from HTTP auth endpoint)

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 updates and errors
- application/json
Message IDStatusMessage
object
Examples values:
{"status":"ok","code":"connected","message":"Successfully connected to the streams socket server."}
{"status":"ok","code":"disconnected","message":"Disconnect initiated."}
{"status":"ok","code":"shutdown","message":"Streams Socket Service shutting down, disconnecting."}
{"status":"error","code":"unauthorized.invalidApiKey","message":"Invalid API key provided, make sure header developer-api-key is valid."}
{"status":"error","code":"unknown","message":"Unknown runtime error."}
{"status":"ok","code":"connected","message":"Connected to account BAPIA#L#737031","remainingRequests":29}
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.

remainingRequests
number
Number of requests remaining in time window until rate limited (currently applies only for the SUBSCRIBE action).

Additional properties are allowed.
#10
ACK Status messages for subscription actions
- application/json
Message IDSubscriptionsStatusMessage
object
Examples values:
{"status":"error","code":"unknown","message":"Unknown runtime error."}
{"status":"ok","code":"connected","message":"Connected to account BAPIA#L#737031","remainingRequests":29}
{"status":"error","code":"alreadyConnectedError","message":"Already connected to account BAPIA#L#737031"}
status
required
string
Response status.

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

message
required
string
Detailed status message.

remainingRequests
number
Number of requests remaining in time window until rate limited (currently applies only for the SUBSCRIBE action).

Additional properties are allowed.
#11
Combination of the user's email, password and server
- application/json
Message IDGetAccountTokensPayload
object
Examples values:
{"email":"[email protected]","password":"Password1!","server":"BAPIA"}
email
string
password
string
server
string
Additional properties are allowed.
#12
- application/json
Message IDGetAccountTokensResponse
object
object
accessToken
required
string
JWT token for API access

expireDate
required
string
format: date-time
Token expiration date

accountId
required
string
User account identifier

Additional properties are allowed.
Additional properties are allowed.
#13
Error acknowledgment for subscription actions
- application/json
Message IDSubscriptionErrorAck
object
Examples values:
{"status":"error","code":"invalidJwt","message":"jwt expired"}
{"status":"error","code":"accountNotFound","message":"Account not found"}
status
required
string
Status of the response.

Allowed values:
"error"
code
required
string
Error code identifying the specific error.

Allowed values:
"invalidJwt"
"accountNotFound"
"unauthorized"
"rateLimit"
message
required
string
Detailed error message.

Additional properties are allowed.

Streams API 1.0.1

Why WebSocket API?

Getting Started

Message Types

The Socket.IO server configuration:

Servers

Operations

REQUEST /auth/jwt/accounts/tokens

Examples

#1 Example

REPLY CHANNEL INFORMATION

Examples

#1 Example

Examples

This example has been generated automatically.

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.

REQUEST subscriptions

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

REPLY CHANNEL INFORMATION

Examples

#1 Example

#2 Example

#3 Example

#4 Example

#5 Example

#6 Example

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

Messages