Skip to main content
WSS
/
v1
/
accounts
/
ws
Messages
Authentication Request
type:object

Authenticate with a JWT token

Subscribe Request
type:object

Subscribe to real-time updates

Unsubscribe Request
type:object

Unsubscribe from updates

Ping
type:object

Keep-alive ping

Authentication Expired
type:object

Session has expired

Refresh Authentication Warning
type:object

Session expires soon, re-authentication recommended

Order Update
type:object

Real-time order update

Position Update
type:object

Real-time position update

Balance Update
type:object

Real-time balance update

Account Info Update
type:object

Real-time account information update

P&L Candle Update
type:object

Real-time P&L candle data

Watchlist Update
type:object

Real-time watchlist updates

News Update
type:object

Real-time news updates

Error
type:object

Error response

Key Features

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 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 subscription

P&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 params

Watchlist 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

StateDescription
ConnectedWebSocket connection established
AuthenticatedSuccessfully authenticated, ready to subscribe
SubscribedActively receiving updates
Refresh WarningSession expiring in 5 minutes
ExpiredSession 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

  1. Connect to WebSocket endpoint
  2. Authenticate within 5 seconds
  3. Subscribe to desired topics
  4. Receive initial snapshot (for account and pnl topics)
  5. Stream real-time updates
  6. Unsubscribe when done
  7. Monitor session expiration warnings

Common Errors

Error CodeCauseResolution
AUTH_REQUIREDDid not authenticate within 5 secondsAuthenticate immediately after connecting
INVALID_TOKENInvalid or expired JWT tokenGenerate a new token and re-authenticate
MISSING_ACCOUNT_IDaccountId not provided in paramsInclude accountId in subscription params
UNKNOWN_TOPICInvalid subscription topicUse valid topic: account, pnl, watchlist, news
INVALID_INTERVALInvalid PnL candle intervalUse: 15s, 1m, 5m, 15m, 1h, 1d, 1mo
ACCESS_DENIEDUser does not own the accountVerify the account ID belongs to the authenticated user

Error Response Format

{
  "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.

Performance Optimization

  • 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.

Account Updates

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

IntervalDescription
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.

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"
    }
  }
}

Order Status Values

StatusDescription
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.

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"
    }
  }
}

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

{
  "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"
    }
  }
}

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"
    }
  }
}

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

Error Response Format

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();
};