Order Status Updates Real-time notifications when orders are placed, filled, partially filled, or cancelled. Track order lifecycle with millisecond latency.
Position Changes Live updates when positions are opened, modified, or closed. Monitor both stock and option positions in real-time.
Balance Updates Instant account balance updates including buying power, equity, cash movements, and margin changes.
P&L Candles Real-time profit/loss candles at various intervals (15s, 1m, 5m, 15m, 1h, 1d, 1mo) for performance tracking.
Watchlist Updates Live updates when symbols are added, updated, or removed from user watchlists.
News Feed Real-time news updates relevant to your portfolio and watchlist symbols.
Endpoint Connect to the accounts WebSocket endpoint for all account-related streams (orders, positions, balances, P&L candles, watchlist updates, and news): Production: wss://api.aries.com/v1/accounts/wsMigration: If you were using wss://api.ariesfinancial.com/ws, update to the URL above.After connecting, authenticate within 5 seconds, then subscribe to the topics you need: account, pnl, watchlist, or news.
Authentication & Security
Authentication Required Send a request message to POST /auth with your token in payload.body: Auth request example: {
"type" : "request" ,
"id" : "auth-001" ,
"payload" : {
"method" : "post" ,
"path" : "/auth" ,
"body" : {
"token" : "YOUR_ACCESS_TOKEN"
}
}
}
Authentication is required and must be completed within 5 seconds of connection. This WebSocket contains sensitive account information and requires a valid JWT token. All connections must use WSS (WebSocket Secure) protocol. Each user receives only their own account updates, ensuring data privacy and security. Session Management Sessions expire after 65 minutes (3900000ms). The server:
Sends a refresh warning 5 minutes before expiration
Closes the connection when the session expires
Requires re-authentication after expiration
Security Best Practices
Always use WSS in production
Store JWT tokens securely
Implement automatic re-authentication on expiration warnings
Monitor connection status and implement reconnection logic
Account Updates (account) Subscribe to all account-level updates in a single subscription:
Orders : Order status changes (new, filled, partial, cancelled, rejected)
Positions : Position changes for stocks and options
Balance : Buying power, equity, margin, and cash updates
Account Info : Account information changes
Requires: accountId in paramsInitial Snapshot: Server sends current orders, positions, and balance upon subscriptionP&L Candles (pnl) Subscribe to profit/loss candle data at specified intervals for performance tracking. Supported Intervals: 15s, 1m, 5m, 15m, 1h, 1d, 1moRequires: accountId, interval, and startTime in paramsWatchlist Updates (watchlist) Subscribe to user’s watchlist changes (add/update/delete events). Requires: None (user-level subscription)News Updates (news) Subscribe to real-time news feed updates relevant to your portfolio. Optional params: symbols (array), topics (array) to filter news
Ping/Pong Keepalive Send periodic pings to keep the WebSocket connection alive and detect network issues: Recommendation: Send a ping every 30-60 seconds to maintain connection health.Handling Disconnects Always implement reconnection logic with exponential backoff:
Start with 1 second delay
Double the delay on each retry (2s, 4s, 8s)
Cap maximum delay at 60 seconds
Re-authenticate after reconnection
Connection States State Description Connected WebSocket connection established Authenticated Successfully authenticated, ready to subscribe Subscribed Actively receiving updates Refresh Warning Session expiring in 5 minutes Expired Session expired, connection closing
Monitor the connection state and handle state transitions gracefully in your application.
Trading Applications Real-time order status for trading platforms. Display live order fills, rejections, and modifications.
Portfolio Monitoring Track position changes, P&L, and balance updates for portfolio management dashboards.
Risk Management Monitor buying power, margin levels, and position sizes in real-time for risk control systems.
Order Notifications Push notifications to mobile apps when orders are filled or positions change.
Performance Analytics Real-time P&L candles for performance tracking and analytics dashboards.
News Alerts Real-time news feed integration for trading signals and market sentiment analysis.
Connection Lifecycle Subscription Flow
Connect to WebSocket endpoint
Authenticate within 5 seconds
Subscribe to desired topics
Receive initial snapshot (for account and pnl topics)
Stream real-time updates
Unsubscribe when done
Monitor session expiration warnings
Common Errors Error Code Cause Resolution AUTH_REQUIREDDid not authenticate within 5 seconds Authenticate immediately after connecting INVALID_TOKENInvalid or expired JWT token Generate a new token and re-authenticate MISSING_ACCOUNT_IDaccountId not provided in paramsInclude accountId in subscription params UNKNOWN_TOPICInvalid subscription topic Use valid topic: account, pnl, watchlist, news INVALID_INTERVALInvalid PnL candle interval Use: 15s, 1m, 5m, 15m, 1h, 1d, 1mo ACCESS_DENIEDUser does not own the account Verify the account ID belongs to the authenticated user
{
"type" : "response" ,
"id" : "req-002" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 400 ,
"error" : "accountId is required" ,
"code" : "MISSING_ACCOUNT_ID"
}
}
Always implement comprehensive error handling to gracefully handle network issues, authentication failures, and server errors.
Subscribe once per account to account topic to receive all account events
Use specific intervals for P&L candles based on your needs
Implement batching for handling high-frequency updates
Store state locally to avoid unnecessary re-subscriptions
Reliability
Monitor connection health with periodic pings (30-60 second intervals)
Implement exponential backoff for reconnections
Handle session expiration proactively using refresh warnings
Store subscription state to restore after reconnection
Security
Rotate tokens periodically
Use environment variables for connection URLs and tokens
Log authentication events for audit trails
Validate all incoming messages before processing
Development
Use development environment for testing
Test failure scenarios (disconnects, authentication failures, malformed messages)
Monitor bandwidth usage in production
Implement message queuing for high-volume scenarios
Authentication
Authenticate Connection
Authentication must be completed within 5 seconds of connection establishment.
{
"type" : "request" ,
"id" : "auth-001" ,
"payload" : {
"method" : "post" ,
"path" : "/auth" ,
"body" : {
"token" : "YOUR_ACCESS_TOKEN"
}
}
}
Authentication Success Response
{
"type" : "event" ,
"payload" : {
"action" : "authSuccess" ,
"data" : {
"expiresIn" : 3900000
},
"id" : "auth-001" ,
"timestamp" : 1703001234567
}
}
The expiresIn field indicates session duration in milliseconds (65 minutes = 3900000ms).
If authentication is not completed within 5 seconds, the server will close the connection with an authTimeout event.
Subscribing to Updates
Subscribe to Account Updates
Subscribe to all account-level updates including orders, positions, balance, and account information.
Subscribe to All Account Updates Get orders, positions, balance, and account info for a specific account: {
"type" : "subscribe" ,
"id" : "req-002" ,
"payload" : {
"topic" : "account" ,
"params" : {
"accountId" : "ACC123456"
}
}
}
Response with Initial Snapshot The server responds with a subscribed message containing current account state: {
"type" : "subscribed" ,
"id" : "req-002" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 200 ,
"topic" : "account" ,
"params" : {
"accountId" : "ACC123456"
},
"data" : {
"orders" : [
{
"ordId" : "ORD-001" ,
"symbol" : "AAPL" ,
"side" : "buy" ,
"qty" : "100" ,
"price" : "150.50" ,
"status" : "filled"
}
],
"positions" : [
{
"symbol" : "AAPL" ,
"qty" : "100" ,
"avgCost" : "150.45" ,
"marketValue" : "15200.00"
}
],
"balance" : {
"accountId" : "ACC123456" ,
"totalEquity" : "50000.00" ,
"netBuyingPower" : "25000.00"
}
}
}
}
The initial snapshot includes current orders, positions, and balance. After this, you’ll receive real-time event messages as changes occur.
Subscribe to P&L Candles Track profit/loss at specified intervals. startTime is required: {
"type" : "subscribe" ,
"id" : "req-003" ,
"payload" : {
"topic" : "pnl" ,
"params" : {
"accountId" : "ACC123456" ,
"interval" : "1m" ,
"startTime" : "2024-01-01T00:00:00Z"
}
}
}
Supported Intervals Interval Description 15s15 seconds 1m1 minute 5m5 minutes 15m15 minutes 1h1 hour 1d1 day 1mo1 month
Subscribe to Watchlist Updates Get notified when symbols are added, updated, or removed from watchlists: {
"type" : "subscribe" ,
"id" : "req-004" ,
"payload" : {
"topic" : "watchlist"
}
}
Subscribe to News Updates Receive real-time news. Optionally filter by symbols or topics: {
"type" : "subscribe" ,
"id" : "req-005" ,
"payload" : {
"topic" : "news" ,
"params" : {
"symbols" : [ "AAPL" , "TSLA" ],
"topics" : [ "earnings" ]
}
}
}
Omit params entirely to receive all news without filtering. Watchlist and news subscriptions are user-level and don’t require an account ID.
Real-Time Update Messages
Once subscribed, the server pushes event messages as data changes.
Order Updates
Receive notifications when order status changes.
Stock Order
Option Spread
Order Filled {
"type" : "event" ,
"timestamp" : "2024-01-15T10:30:05Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.order" ,
"target" : "account:ACC123456" ,
"data" : {
"ordId" : "ORD-12345" ,
"clOrdId" : "CLIENT-001" ,
"accountId" : "ACC123456" ,
"symbol" : "AAPL" ,
"side" : "buy" ,
"type" : "limit" ,
"timeInForce" : "day" ,
"qty" : "100" ,
"price" : "150.50" ,
"status" : "filled" ,
"cumQty" : "100" ,
"leavesQty" : "0" ,
"avgPrice" : "150.45" ,
"currency" : "USD" ,
"exDestination" : "NASDAQ" ,
"securityType" : "stock" ,
"category" : "equity" ,
"createdAt" : "2024-01-15T10:30:00Z" ,
"updatedAt" : "2024-01-15T10:30:05Z"
}
}
}
Multi-Leg Option Order {
"type" : "event" ,
"timestamp" : "2024-01-15T11:00:10Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.order" ,
"target" : "account:ACC123456" ,
"data" : {
"ordId" : "ORD-67890" ,
"clOrdId" : "CLIENT-002" ,
"accountId" : "ACC123456" ,
"symbol" : "SPY" ,
"side" : "buy" ,
"type" : "limit" ,
"qty" : "1" ,
"price" : "2.50" ,
"status" : "partiallyFilled" ,
"cumQty" : "1" ,
"avgPrice" : "2.48" ,
"securityType" : "option" ,
"category" : "spread" ,
"legs" : [
{
"symbol" : "SPY" ,
"side" : "buy" ,
"ratioQty" : "1" ,
"securityType" : "option" ,
"maturity" : "2024-12-20" ,
"strikePrice" : "450" ,
"positionEffect" : "open" ,
"putCall" : "call"
},
{
"symbol" : "SPY" ,
"side" : "sell" ,
"ratioQty" : "1" ,
"securityType" : "option" ,
"maturity" : "2024-12-20" ,
"strikePrice" : "460" ,
"positionEffect" : "open" ,
"putCall" : "call"
}
],
"createdAt" : "2024-01-15T11:00:00Z" ,
"updatedAt" : "2024-01-15T11:00:10Z"
}
}
}
Order Status Values
Status Description newOrder has been accepted partiallyFilledOrder partially executed filledOrder fully executed canceledOrder has been cancelled rejectedOrder was rejected pendingOrder is pending submission
Position Updates
Receive notifications when positions change.
Stock Position
Option Position
Long Stock Position {
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.position" ,
"target" : "account:ACC123456" ,
"data" : {
"accountId" : "ACC123456" ,
"symbol" : "AAPL" ,
"securityType" : "stock" ,
"qty" : "100" ,
"avgCost" : "150.45" ,
"buyingPowerUsed" : "15045.00" ,
"marketValue" : "15200.00" ,
"unRealizedPL" : "155.00" ,
"realizedPL" : "0" ,
"todayPL" : "155.00" ,
"side" : "long" ,
"instrument" : "stock" ,
"createdAt" : "2024-01-15T10:30:05Z" ,
"updatedAt" : "2024-01-15T14:30:00Z"
}
}
}
Long Call Option {
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.position" ,
"target" : "account:ACC123456" ,
"data" : {
"accountId" : "ACC123456" ,
"symbol" : "SPY" ,
"securityType" : "option" ,
"qty" : "1" ,
"avgCost" : "248.00" ,
"marketValue" : "260.00" ,
"unRealizedPL" : "12.00" ,
"realizedPL" : "0" ,
"todayPL" : "12.00" ,
"side" : "long" ,
"instrument" : "option" ,
"putCall" : "call" ,
"strikePrice" : "450" ,
"maturity" : "2024-12-20" ,
"createdAt" : "2024-01-15T11:00:10Z" ,
"updatedAt" : "2024-01-15T14:30:00Z"
}
}
}
Balance Updates
{
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.balance" ,
"target" : "account:ACC123456" ,
"data" : {
"accountId" : "ACC123456" ,
"sodPositionsMarketValue" : "48000.00" ,
"netBuyingPower" : "25155.00" ,
"stockBuyingPower" : "50310.00" ,
"dayTradeBuyingPower" : "100620.00" ,
"optionBuyingPower" : "25155.00" ,
"totalEquity" : "50155.00" ,
"settledFunds" : "35000.00" ,
"unsettledFunds" : "0" ,
"maintReq" : "7646.50" ,
"realizedPL" : "0" ,
"unRealizedPL" : "167.00" ,
"PDT" : 0 ,
"startOfDayCash" : "35000.00" ,
"valueBought" : "15293.00" ,
"valueSold" : "0"
}
}
}
Account Info Updates
{
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "account" ,
"name" : "account.info" ,
"target" : "account:ACC123456" ,
"data" : {
"id" : "ACC123456" ,
"description" : "John Doe Trading Account" ,
"accountType" : "margin" ,
"accountClass" : "individual" ,
"optionsLevel" : "3" ,
"maintenanceExcess" : "17508.50" ,
"cashAvailable" : "25155.00" ,
"netLiquidity" : "50155.00" ,
"marginEquity" : "50155.00" ,
"sma" : "25155.00" ,
"maintReq" : "7646.50"
}
}
}
P&L Candle Updates
{
"type" : "event" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"topic" : "pnl" ,
"data" : {
"accountId" : "ACC123456" ,
"interval" : "1m" ,
"timestamp" : 1703001000000 ,
"open" : "50000.00" ,
"high" : "50300.00" ,
"low" : "49900.00" ,
"close" : "50155.00" ,
"realizedPnL" : "0" ,
"unrealizedPnL" : "155.00" ,
"totalPnL" : "155.00"
}
}
}
Watchlist Updates
Symbol Added
Symbol Removed
{
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "watchlist" ,
"data" : {
"id" : "WL-001" ,
"symbol" : "TSLA" ,
"name" : "Tesla Inc" ,
"lastPrice" : "242.50" ,
"change" : "+2.35" ,
"changePercent" : "+0.98"
}
}
}
{
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "watchlist" ,
"data" : {
"id" : "WL-001"
}
}
}
News Updates
{
"type" : "event" ,
"timestamp" : "2024-01-15T14:30:00Z" ,
"payload" : {
"topic" : "news" ,
"data" : {
"msgType" : "add" ,
"items" : [
{
"id" : "12345" ,
"headline" : "Fed Announces Rate Decision" ,
"summary" : "Federal Reserve maintains interest rates..." ,
"source" : "Reuters" ,
"publishedAt" : "2024-01-15T14:30:00Z" ,
"symbols" : [ "SPY" , "QQQ" ]
}
]
}
}
}
Unsubscribing from Updates
Stop receiving updates for specific topics.
Unsubscribe from Account Updates {
"type" : "unsubscribe" ,
"id" : "req-007" ,
"payload" : {
"topic" : "account" ,
"params" : {
"accountId" : "ACC123456"
}
}
}
Response {
"type" : "response" ,
"id" : "req-007" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 200 ,
"data" : {
"unsubscribed" : true ,
"topic" : "account" ,
"accountId" : "ACC123456"
}
}
}
Unsubscribe from Watchlist Updates {
"type" : "unsubscribe" ,
"id" : "req-008" ,
"payload" : {
"topic" : "watchlist"
}
}
Response {
"type" : "response" ,
"id" : "req-008" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 200 ,
"data" : {
"unsubscribed" : true ,
"topic" : "watchlist"
}
}
}
Unsubscribe from News Updates {
"type" : "unsubscribe" ,
"id" : "req-009" ,
"payload" : {
"topic" : "news"
}
}
Response {
"type" : "response" ,
"id" : "req-009" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 200 ,
"data" : {
"unsubscribed" : true ,
"topic" : "news"
}
}
}
Connection Management
Ping/Pong Keepalive
Send periodic pings to maintain connection health and detect network issues.
Ping Request:
{
"type" : "ping" ,
"id" : "ping-001"
}
Pong Response:
{
"type" : "pong" ,
"id" : "ping-001" ,
"timestamp" : "2024-01-15T10:30:00Z"
}
Recommendation: Send a ping every 30-60 seconds to keep the connection alive.
Session Expiration
Refresh Warning (5 minutes before expiration):
{
"type" : "event" ,
"payload" : {
"action" : "refreshAuth" ,
"data" : {
"expiresIn" : 300000 ,
"expiresAt" : 1703001534567
},
"id" : "system" ,
"timestamp" : 1703001234567
}
}
Session Expired:
{
"type" : "event" ,
"payload" : {
"action" : "authExpired" ,
"data" : {
"error" : "session expired"
},
"id" : "system" ,
"timestamp" : 1703001234567
}
}
When you receive a refreshAuth warning, you should re-authenticate or be prepared to reconnect. The connection will be closed when the session expires.
Error Handling
All errors follow this format:
{
"type" : "response" ,
"id" : "req-002" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 400 ,
"error" : "accountId is required" ,
"code" : "MISSING_ACCOUNT_ID"
}
}
Common Error Scenarios
Authentication Timeout {
"type" : "event" ,
"payload" : {
"action" : "authTimeout" ,
"data" : {
"error" : "authentication timeout"
},
"id" : "system" ,
"timestamp" : 1703001234567
}
}
Cause: Did not authenticate within 5 seconds of connection.Resolution: Send authentication request immediately after connecting.Invalid Token {
"type" : "response" ,
"id" : "auth-001" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 401 ,
"error" : "token is invalid or expired" ,
"code" : "INVALID_TOKEN"
}
}
Cause: JWT token is invalid or expired.Resolution: Generate a new token and re-authenticate.
Missing Account ID {
"type" : "response" ,
"id" : "req-002" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 400 ,
"error" : "accountId is required" ,
"code" : "MISSING_ACCOUNT_ID"
}
}
Cause: accountId not provided in params for account or pnl subscription.Resolution: Include accountId in payload.params.Unknown Topic {
"type" : "response" ,
"id" : "req-003" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"payload" : {
"status" : 400 ,
"error" : "unknown subscription topic: badtopic" ,
"code" : "UNKNOWN_TOPIC"
}
}
Cause: Invalid topic specified.Resolution: Use valid topics: account, pnl, watchlist, news.
Best Practices
Reliable Connection Handling
Implement exponential backoff for reconnections:
let reconnectDelay = 1000 ; // Start with 1 second
function reconnect () {
setTimeout (() => {
connectWebSocket ();
reconnectDelay = Math . min ( reconnectDelay * 2 , 60000 ); // Cap at 60 seconds
}, reconnectDelay );
}
ws . onclose = () => {
console . log ( 'Connection closed, reconnecting...' );
reconnect ();
};
ws . onopen = () => {
reconnectDelay = 1000 ; // Reset delay on successful connection
authenticate ();
};
Handle Session Expiration
ws . onmessage = ( event ) => {
const msg = JSON . parse ( event . data );
const payload = msg . payload ;
if ( msg . type === 'event' && payload ?. action === 'refreshAuth' ) {
console . log ( 'Session expiring in 5 minutes' );
// Option 1: Get a new token and re-authenticate
getNewToken (). then ( token => authenticate ( token ));
// Option 2: Prepare to reconnect
scheduleReconnect ();
}
if ( msg . type === 'event' && payload ?. action === 'authExpired' ) {
console . log ( 'Session expired, reconnecting...' );
reconnect ();
}
};
Efficient Subscription Management
Subscribe once to account updates for all order, position, balance, and account changes:
// Subscribe to all account events
ws . send ( JSON . stringify ({
type: 'subscribe' ,
id: 'req-002' ,
payload: {
topic: 'account' ,
params: { accountId: 'ACC123456' }
}
}));
Store State Locally
Keep local state to avoid unnecessary re-subscriptions:
let subscriptions = new Set ();
function subscribe ( topic , params ) {
const key = ` ${ topic } : ${ JSON . stringify ( params ) } ` ;
if ( subscriptions . has ( key )) {
console . log ( 'Already subscribed to' , topic );
return ;
}
ws . send ( JSON . stringify ({
type: 'subscribe' ,
id: `sub- ${ Date . now () } ` ,
payload: { topic , params }
}));
subscriptions . add ( key );
}
ws . onclose = () => {
// Clear subscriptions on disconnect
subscriptions . clear ();
};