Account Updates WebSocket

Messages

{
  "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",
      "clientId": "CLIENT-USER-001",
      "symbol": "AAPL",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "DAY",
      "qty": "100",
      "price": "150.50",
      "stopPrice": "0",
      "ordStatus": "FILLED",
      "cumQty": "100",
      "leavesQty": "0",
      "avgPrice": "150.45",
      "currency": "USD",
      "exDestination": "MNGDFTE",
      "securityType": "EQUITY",
      "category": "EQUITY",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:05Z"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T14:30:00Z",
  "payload": {
    "topic": "account",
    "name": "account.position",
    "target": "account:ACC123456",
    "data": {
      "accountId": "ACC123456",
      "symbol": "AAPL",
      "securityType": "EQUITY",
      "qty": "100",
      "avgPrice": "150.45",
      "avgCost": "150.45",
      "unRealizedPL": "155.00",
      "todayRealizedPnL": "0",
      "realizedPL": "0",
      "todayPL": "155.00",
      "instrument": "EQUITY",
      "createdAt": "2024-01-15T10:30:05Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  }
}

{
  "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",
      "dayTradeOvernightRegTBuyingPower": "50310.00",
      "totalEquity": "50155.00",
      "settledFunds": "35000.00",
      "unsettledFunds": "0",
      "heldBackFunds": "0",
      "grossMargin": "15045.00",
      "pendingOrdersMarginRequirements": "0",
      "maintReq": "7646.50",
      "creditMultiplier": "2",
      "pendingOrdersCount": 0,
      "credit": "50000.00",
      "creditRemaining": "25155.00",
      "realizedPL": "0",
      "unRealizedPL": "167.00",
      "SMA": "25155.00",
      "smaCreditRemaining": "25155.00",
      "PDT": "0",
      "pdtCreditRemaining": "100620.00",
      "startOfDayCash": "35000.00",
      "valueBought": "15293.00",
      "valueSold": "0"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T14:30:00Z",
  "payload": {
    "topic": "account",
    "name": "account.info",
    "target": "account:ACC123456",
    "data": {
      "id": "ACC123456",
      "sterlingAccountId": "STERLING-123",
      "apexAccountId": "",
      "fdid": "FDID-123456",
      "description": "John Doe Trading Account",
      "accountType": "MARGIN",
      "accountClass": "INDIVIDUAL",
      "optionsLevel": "LEVEL_3",
      "maintenanceExcess": "17508.50",
      "cashAvailable": "25155.00",
      "exchangeSurplus": "0",
      "accruedCash": "0",
      "netLiquidity": "50155.00",
      "marginEquity": "50155.00",
      "sma": "25155.00",
      "maintReq": "7646.50",
      "email": "john.doe@example.com",
      "cell": "+1234567890",
      "groupId": "TRADING"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "topic": "pnl",
    "data": {
      "accountId": "ACC123456",
      "interval": "1m",
      "t": [
        1703001000
      ],
      "c": [
        50155
      ]
    }
  }
}

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

{
  "type": "subscribed",
  "id": "req-002",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "status": 200,
    "topic": "account",
    "params": {
      "accountId": "ACC123456"
    },
    "data": {
      "account": {
        "accountNumber": "ACC123456",
        "accountType": "MARGIN",
        "accountClass": "INDIVIDUAL",
        "optionsLevel": "LEVEL_3",
        "cashAvailable": "25155.00",
        "netLiquidity": "50155.00",
        "marginEquity": "50155.00",
        "maintenanceExcess": "17508.50",
        "sma": "25155.00",
        "maintReq": "7646.50",
        "netBuyingPower": "25155.00",
        "stockBuyingPower": "50310.00",
        "dayTradeBuyingPower": "100620.00",
        "optionBuyingPower": "25155.00",
        "totalEquity": "50155.00",
        "pendingOrdersCount": 0
      },
      "positions": [],
      "orders": [],
      "ordersV2": []
    }
  }
}

{
  "type": "response",
  "id": "req-006",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "status": 200,
    "data": {
      "unsubscribed": true,
      "topic": "account",
      "accountId": "ACC123456"
    }
  }
}

WSS

accounts

What this stream gives you. Open one connection to wss://api.aries.com/v1/accounts/ws, authenticate, and the server will push updates whenever anything changes on your trading account — an order fills, a position is opened or closed, your buying power moves, news drops on a stock you hold, or a watchlist gets edited on another device. You get the same live picture a brokerage app would show, without polling.

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.

Connection

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

Subscription Topics

Each topic is a separate stream — subscribe only to what your app needs.

Account Updates (`account`)

One subscription covers everything that happens on a trading account:

Orders — order status changes as your orders move through the system (see the full status list below).
Positions — when a position is opened, increased, reduced, or closed, for both stocks and options.
Balance — buying power, equity, margin, and cash movements.
Account info — changes to the account record itself (type, options level, etc.).

Requires: accountId in params — the ID of the account you want to subscribe to.Initial snapshot: Right after you subscribe, the server sends a snapshot containing current account/balance fields, all open positions, legacy orders, and the new ordersV2 list, so you start with the full state.

P&L Candles (`pnl`)

A live time-series of your account’s profit-and-loss, broken into “candles” of a fixed length (just like price candles on a chart). Useful for plotting equity curves and intraday performance.Supported intervals — choose the candle length that matches your dashboard:

Interval	Candle length	Typical use
`15s`	15 seconds	Very granular intraday tracking
`1m`	1 minute	Default — intraday equity curve
`5m`	5 minutes	Smoother intraday view
`15m`	15 minutes	Half-day / full-day view
`1h`	1 hour	Multi-day view
`1d`	1 day	Daily P&L history
`1mo`	1 month	Long-term performance

Requires: accountId and startTime (an RFC3339 timestamp marking how far back to start the series) in params. interval is optional and defaults to 1m.

Watchlist Updates (`watchlist`)

Pushes a message every time a symbol is added to, updated in, or removed from any of your watchlists — including changes made on other devices, so apps stay in sync.Requires: Nothing extra. The subscription is tied to your authenticated user, not a specific account.

News Updates (`news`)

Pushes news articles relevant to your portfolio in real time.Optional params (omit for the firehose of all news):

symbols — array of tickers to filter by, e.g. ["AAPL", "TSLA"]. You’ll only receive news mentioning these symbols.
topics — array of topic categories to filter by, e.g. ["earnings"].

Connection Management

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.

Use Cases

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.

Message Flow

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

Error Handling

Common Errors

Error Code	Cause	Resolution
`AUTH_REQUIRED`	Did not authenticate within 5 seconds	Authenticate immediately after connecting
`INVALID_TOKEN`	Invalid or expired JWT token	Generate a new token and re-authenticate
`MISSING_ACCOUNT_ID`	`accountId` not provided in `params`	Include `accountId` in subscription params
`UNKNOWN_TOPIC`	Invalid subscription topic	Use valid topic: `account`, `pnl`, `watchlist`, `news`
`MISSING_START_TIME`	`startTime` not provided for P&L	Include an RFC3339 timestamp in `params.startTime`
`INVALID_INTERVAL`	Invalid PnL candle interval	Use: `15s`, `1m`, `5m`, `15m`, `1h`, `1d`, `1mo`
`ACCESS_DENIED`	User does not own the account	Verify 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.

Best Practices

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 all account-level updates including orders, positions, balance, and account information.

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. Decimal values are serialized as JSON strings.

{
  "type": "subscribed",
  "id": "req-002",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "status": 200,
    "topic": "account",
    "params": {
      "accountId": "ACC123456"
    },
    "data": {
      "account": {
        "accountNumber": "ACC123456",
        "accountType": "MARGIN",
        "accountClass": "INDIVIDUAL",
        "optionsLevel": "LEVEL_3",
        "cashAvailable": "25155.00",
        "netLiquidity": "50155.00",
        "marginEquity": "50155.00",
        "maintenanceExcess": "17508.50",
        "sma": "25155.00",
        "maintReq": "7646.50",
        "netBuyingPower": "25155.00",
        "stockBuyingPower": "50310.00",
        "dayTradeBuyingPower": "100620.00",
        "optionBuyingPower": "25155.00",
        "totalEquity": "50155.00",
        "pendingOrdersCount": 0
      },
      "positions": [
        {
          "accountId": "ACC123456",
          "symbol": "AAPL",
          "securityType": "EQUITY",
          "qty": "100",
          "avgPrice": "150.45",
          "avgCost": "150.45",
          "unRealizedPL": "155.00",
          "todayRealizedPnL": "0",
          "realizedPL": "0",
          "todayPL": "155.00",
          "instrument": "EQUITY"
        }
      ],
      "orders": [
        {
          "ordId": "ORD-001",
          "clOrdId": "CLIENT-001",
          "accountId": "ACC123456",
          "symbol": "AAPL",
          "side": "BUY",
          "type": "LIMIT",
          "timeInForce": "DAY",
          "qty": "100",
          "price": "150.50",
          "ordStatus": "FILLED"
        }
      ],
      "ordersV2": []
    }
  }
}

The initial snapshot includes merged account and balance fields, positions, legacy orders, and ordersV2. After this, you’ll receive real-time event messages as changes occur.

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
`15s`	15 seconds
`1m`	1 minute
`5m`	5 minutes
`15m`	15 minutes
`1h`	1 hour
`1d`	1 day
`1mo`	1 month

Watchlist & News

Get notified when symbols are added, updated, or removed from watchlists:

{
  "type": "subscribe",
  "id": "req-004",
  "payload": {
    "topic": "watchlist"
  }
}

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.

Payload Data Types

Field group	JSON type	Notes
`id`, `topic`, `params.accountId`, enum fields	string	Request IDs and topic/account identifiers are strings.
Trading amounts and quantities	string	Decimal fields such as `qty`, `price`, `avgPrice`, `totalEquity`, `PDT`, and P&L values are serialized as strings.
`pendingOrdersCount`	integer	Count fields remain numeric integers.
`timestamp`, `createdAt`, `updatedAt`	string	WebSocket envelopes and domain timestamps use RFC3339 strings. Auth event payload timestamps use Unix milliseconds.
`expiresIn`, `expiresAt`, `t`	integer	Auth expiry values are Unix milliseconds. P&L `t` values are Unix seconds.
`orders`, `ordersV2`, `positions`	array	Account subscription snapshots return arrays for these fields.

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",
      "ordStatus": "FILLED",
      "cumQty": "100",
      "leavesQty": "0",
      "avgPrice": "150.45",
      "currency": "USD",
      "exDestination": "MNGDFTE",
      "securityType": "EQUITY",
      "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",
      "ordStatus": "PARTIALLY_FILLED",
      "cumQty": "1",
      "avgPrice": "2.48",
      "securityType": "OPTION",
      "category": "MULTI_LEG",
      "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"
    }
  }
}

`ordStatus` Values

The order status field is ordStatus. These are the full set of states an order can be in over its lifetime:

Status	What it means	What to show the user
`PENDING_NEW`	The order is on its way to the exchange but hasn’t been accepted yet.	”Submitting…”
`NEW`	The exchange has accepted the order and it is live in the book (working but not yet executed).	”Working” / “Open”
`PARTIALLY_FILLED`	Some of the order’s quantity has executed; the rest is still working. Watch `cumQty` and `leavesQty`.	”Partially filled”
`FILLED`	The entire order quantity has executed. The order is done.	”Filled” / “Complete”
`PENDING_CANCEL`	You sent a cancel request; the exchange has not confirmed it yet.	”Cancelling…”
`CANCELED`	The order was cancelled (by you, by the system, or by the exchange). It will not execute further.	”Cancelled”
`PENDING_REPLACE`	You sent a modify/replace request; the exchange has not confirmed it yet.	”Modifying…”
`REJECTED`	The order was refused (bad parameters, insufficient buying power, halted symbol, etc.). It never made it onto the book.	”Rejected” + error reason
`EXPIRED`	The order reached its time-in-force limit without filling (e.g. a `DAY` order that didn’t fill before market close).	”Expired”

Order field enums

Order event payloads contain several enum fields. Here’s the full vocabulary you’ll see across stocks and options: side — direction of the trade:

Value	Meaning
`BUY`	Buying — opening a long position or closing a short.
`SELL`	Selling — closing a long position or opening a short.
`SELL_SHORT`	Selling shares you do not own (short sale). Subject to short-sale regulations.
`BUY_TO_COVER`	Buying back shares to close an existing short position.

type — order type, i.e. how the order is priced:

Value	Meaning
`MARKET`	Execute immediately at the best available price. No price guarantee.
`LIMIT`	Execute only at the specified `price` or better. Price guarantee, no execution guarantee.
`STOP`	Sits inactive until the stop price is touched, then becomes a market order.
`STOP_LIMIT`	Sits inactive until the stop price is touched, then becomes a limit order at the limit price.
`TRAILING_STOP`	A stop that follows the market by a fixed dollar or percentage offset.

timeInForce — how long the order stays alive:

Value	Meaning
`DAY`	Active until the end of today’s regular trading session, then cancelled if not filled.
`GTC`	Good ‘Til Cancelled — stays open until you cancel it (broker may cap at 60–90 days).
`IOC`	Immediate Or Cancel — fill whatever you can immediately, cancel the rest.
`FOK`	Fill Or Kill — fill the entire order immediately, or cancel it entirely.
`GTD`	Good ‘Til Date — stays open until a specific date you provide.
`OPG`	At the market open.
`CLO`	At the market close.

securityType / instrument — what asset class:

Value	Meaning
`EQUITY`	Stock or ETF.
`OPTION`	Single option contract.
`MULTI_LEG`	Multi-leg option order (spread, condor, etc.) — see `legs` array.

putCall (options only): CALL or PUT. positionEffect (options only): OPEN (creates/increases a position) or CLOSE (reduces/closes one).

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": "EQUITY",
      "qty": "100",
      "avgPrice": "150.45",
      "avgCost": "150.45",
      "unRealizedPL": "155.00",
      "todayRealizedPnL": "0",
      "realizedPL": "0",
      "todayPL": "155.00",
      "instrument": "EQUITY",
      "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": "SPY241220C00450000",
      "securityType": "OPTION",
      "qty": "1",
      "avgPrice": "248.00",
      "avgCost": "248.00",
      "unRealizedPL": "12.00",
      "todayRealizedPnL": "0",
      "realizedPL": "0",
      "todayPL": "12.00",
      "instrument": "OPTION",
      "putCall": "CALL",
      "strikePrice": "450",
      "maturity": "2024-12-20",
      "createdAt": "2024-01-15T11:00:10Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  }
}

Position updates emit primary fields avgPrice, todayRealizedPnL, and securityType. The backend also emits backward-compatible aliases avgCost, realizedPL, and instrument.

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",
      "dayTradeOvernightRegTBuyingPower": "50310.00",
      "totalEquity": "50155.00",
      "settledFunds": "35000.00",
      "unsettledFunds": "0",
      "heldBackFunds": "0",
      "grossMargin": "15045.00",
      "pendingOrdersMarginRequirements": "0",
      "maintReq": "7646.50",
      "creditMultiplier": "2",
      "pendingOrdersCount": 0,
      "credit": "50000.00",
      "creditRemaining": "25155.00",
      "realizedPL": "0",
      "unRealizedPL": "167.00",
      "SMA": "25155.00",
      "smaCreditRemaining": "25155.00",
      "PDT": "0",
      "pdtCreditRemaining": "100620.00",
      "startOfDayCash": "35000.00",
      "valueBought": "15293.00",
      "valueSold": "0"
    }
  }
}

Balance field reference — decimal values arrive as JSON strings to preserve precision:

Field	What it means
`accountId`	The account this balance update belongs to.
`sodPositionsMarketValue`	Start-of-day market value of all open positions (i.e. what your holdings were worth when the trading day opened).
`netBuyingPower`	Total purchasing power available right now across all instruments. The most common number to display as “buying power” in a UI.
`stockBuyingPower`	How much you can use specifically to buy stock (typically up to 2× cash on margin).
`dayTradeBuyingPower`	How much you can use for same-day round-trip trades (typically up to 4× equity for pattern day traders). Resets at end of day.
`optionBuyingPower`	How much you can use to buy options. Options usually require cash, so this is typically lower than stock buying power.
`dayTradeOvernightRegTBuyingPower`	Day-trade buying power that can also be held overnight under Reg T rules.
`totalEquity`	Cash + market value of positions − margin debit. Your account’s net worth.
`settledFunds`	Cash that has fully settled and is freely available (T+1/T+2 has passed).
`unsettledFunds`	Cash from recent sales that hasn’t settled yet — usable for most trades, but cash accounts have restrictions.
`heldBackFunds`	Cash temporarily reserved for pending orders or compliance holds. Not usable.
`grossMargin`	Total amount you have borrowed from the broker on margin.
`pendingOrdersMarginRequirements`	Margin already earmarked for orders that are working but not yet filled.
`maintReq`	Maintenance requirement — the minimum equity you must hold to support your current positions. Drop below this and you may get a margin call.
`creditMultiplier`	How many times your equity you can borrow on standard margin (typically `2`).
`pendingOrdersCount`	Number of orders currently working.
`credit`	Total margin credit line extended to the account.
`creditRemaining`	How much of that credit line is still available.
`realizedPL`	Cumulative profit/loss from positions that have been closed.
`unRealizedPL`	Profit/loss on positions you currently hold open — i.e. paper gains/losses based on current market value.
`SMA`	Special Memorandum Account — a margin-account balance that effectively stores up “extra” buying power from gains. Reg T concept.
`smaCreditRemaining`	SMA buying power still available.
`PDT`	Pattern Day Trader flag balance — relates to the four-day-trade rule and the $25,000 minimum equity requirement under FINRA Rule 4210.
`pdtCreditRemaining`	Remaining day-trade buying power for a flagged PDT account.
`startOfDayCash`	Cash balance at the start of today’s session. Useful for calculating daily change.
`valueBought`	Dollar value of purchases executed today.
`valueSold`	Dollar value of sales executed today.

Account-level enums

The account-info and account snapshot messages include a few enum fields. Here are the full sets of values you may see: accountType — how the account is funded and settled:

Value	Meaning
`CASH`	Cash account — trades must be paid for with settled funds; no margin borrowing.
`MARGIN`	Standard margin account — can borrow against equity (subject to Reg T).
`IRA`	Individual Retirement Account — tax-advantaged, no margin borrowing.
`ROTH_IRA`	Roth IRA — after-tax retirement account.
`RETIREMENT`	Generic retirement account (401k, SEP, etc.).

accountClass — who owns the account:

Value	Meaning
`INDIVIDUAL`	Single-person account.
`JOINT`	Joint ownership (two or more individuals).
`CORPORATE`	Owned by a corporation.
`TRUST`	Owned by a trust.
`LLC`	Owned by an LLC.

optionsLevel — what option strategies the account is approved for. Higher levels unlock more complex (and risky) strategies:

Value	What you can trade
`LEVEL_0`	Not approved for options.
`LEVEL_1`	Covered calls and cash-secured puts only.
`LEVEL_2`	Adds long calls and long puts (buying options).
`LEVEL_3`	Adds spreads (e.g. vertical spreads, iron condors) — defined-risk multi-leg strategies.
`LEVEL_4`	Adds naked option selling — undefined-risk strategies. Requires the highest equity threshold.

Account Info Updates

{
  "type": "event",
  "timestamp": "2024-01-15T14:30:00Z",
  "payload": {
    "topic": "account",
    "name": "account.info",
    "target": "account:ACC123456",
    "data": {
      "id": "ACC123456",
      "sterlingAccountId": "STERLING-123",
      "apexAccountId": "",
      "fdid": "FDID-123456",
      "description": "John Doe Trading Account",
      "accountType": "MARGIN",
      "accountClass": "INDIVIDUAL",
      "optionsLevel": "LEVEL_3",
      "maintenanceExcess": "17508.50",
      "cashAvailable": "25155.00",
      "exchangeSurplus": "0",
      "accruedCash": "0",
      "netLiquidity": "50155.00",
      "marginEquity": "50155.00",
      "sma": "25155.00",
      "maintReq": "7646.50",
      "email": "john.doe@example.com",
      "cell": "+1234567890",
      "groupId": "TRADING"
    }
  }
}

P&L Candle Updates

{
  "type": "event",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "topic": "pnl",
    "data": {
      "accountId": "ACC123456",
      "interval": "1m",
      "t": [1703001000],
      "c": [50155]
    }
  }
}

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.

Account
Watchlist
News

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

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 Errors

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.

Subscription Errors

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

Messages

{
  "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",
      "clientId": "CLIENT-USER-001",
      "symbol": "AAPL",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "DAY",
      "qty": "100",
      "price": "150.50",
      "stopPrice": "0",
      "ordStatus": "FILLED",
      "cumQty": "100",
      "leavesQty": "0",
      "avgPrice": "150.45",
      "currency": "USD",
      "exDestination": "MNGDFTE",
      "securityType": "EQUITY",
      "category": "EQUITY",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:05Z"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T14:30:00Z",
  "payload": {
    "topic": "account",
    "name": "account.position",
    "target": "account:ACC123456",
    "data": {
      "accountId": "ACC123456",
      "symbol": "AAPL",
      "securityType": "EQUITY",
      "qty": "100",
      "avgPrice": "150.45",
      "avgCost": "150.45",
      "unRealizedPL": "155.00",
      "todayRealizedPnL": "0",
      "realizedPL": "0",
      "todayPL": "155.00",
      "instrument": "EQUITY",
      "createdAt": "2024-01-15T10:30:05Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  }
}

{
  "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",
      "dayTradeOvernightRegTBuyingPower": "50310.00",
      "totalEquity": "50155.00",
      "settledFunds": "35000.00",
      "unsettledFunds": "0",
      "heldBackFunds": "0",
      "grossMargin": "15045.00",
      "pendingOrdersMarginRequirements": "0",
      "maintReq": "7646.50",
      "creditMultiplier": "2",
      "pendingOrdersCount": 0,
      "credit": "50000.00",
      "creditRemaining": "25155.00",
      "realizedPL": "0",
      "unRealizedPL": "167.00",
      "SMA": "25155.00",
      "smaCreditRemaining": "25155.00",
      "PDT": "0",
      "pdtCreditRemaining": "100620.00",
      "startOfDayCash": "35000.00",
      "valueBought": "15293.00",
      "valueSold": "0"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T14:30:00Z",
  "payload": {
    "topic": "account",
    "name": "account.info",
    "target": "account:ACC123456",
    "data": {
      "id": "ACC123456",
      "sterlingAccountId": "STERLING-123",
      "apexAccountId": "",
      "fdid": "FDID-123456",
      "description": "John Doe Trading Account",
      "accountType": "MARGIN",
      "accountClass": "INDIVIDUAL",
      "optionsLevel": "LEVEL_3",
      "maintenanceExcess": "17508.50",
      "cashAvailable": "25155.00",
      "exchangeSurplus": "0",
      "accruedCash": "0",
      "netLiquidity": "50155.00",
      "marginEquity": "50155.00",
      "sma": "25155.00",
      "maintReq": "7646.50",
      "email": "john.doe@example.com",
      "cell": "+1234567890",
      "groupId": "TRADING"
    }
  }
}

{
  "type": "event",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "topic": "pnl",
    "data": {
      "accountId": "ACC123456",
      "interval": "1m",
      "t": [
        1703001000
      ],
      "c": [
        50155
      ]
    }
  }
}

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

{
  "type": "subscribed",
  "id": "req-002",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "status": 200,
    "topic": "account",
    "params": {
      "accountId": "ACC123456"
    },
    "data": {
      "account": {
        "accountNumber": "ACC123456",
        "accountType": "MARGIN",
        "accountClass": "INDIVIDUAL",
        "optionsLevel": "LEVEL_3",
        "cashAvailable": "25155.00",
        "netLiquidity": "50155.00",
        "marginEquity": "50155.00",
        "maintenanceExcess": "17508.50",
        "sma": "25155.00",
        "maintReq": "7646.50",
        "netBuyingPower": "25155.00",
        "stockBuyingPower": "50310.00",
        "dayTradeBuyingPower": "100620.00",
        "optionBuyingPower": "25155.00",
        "totalEquity": "50155.00",
        "pendingOrdersCount": 0
      },
      "positions": [],
      "orders": [],
      "ordersV2": []
    }
  }
}

{
  "type": "response",
  "id": "req-006",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "status": 200,
    "data": {
      "unsubscribed": true,
      "topic": "account",
      "accountId": "ACC123456"
    }
  }
}

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

Authentication Success

type:object

Authentication succeeded

Authentication Timeout

type:object

Authentication timed out

Subscribed

type:object

Subscription confirmed with snapshot

Unsubscription Confirmed

type:object

Server confirms unsubscription

Pong

type:object

Keep-alive pong response

Charting WebSocket Watchlist WebSocket

Documentation Index

Order Status Updates

Position Changes

Balance Updates

P&L Candles

Watchlist Updates

News Feed

​Endpoint

​Authentication Required

​Session Management

​Security Best Practices

​Account Updates (account)

​P&L Candles (pnl)

​Watchlist Updates (watchlist)

​News Updates (news)

​Ping/Pong Keepalive

​Handling Disconnects

​Connection States

Trading Applications

Portfolio Monitoring

Risk Management

Order Notifications

Performance Analytics

News Alerts

​Connection Lifecycle

​Subscription Flow

​Common Errors

​Error Response Format

​Performance Optimization

​Reliability

​Security

​Development

​Authentication

​Authenticate Connection

​Authentication Success Response

​Subscribing to Updates

​Subscribe to Account Updates

​Subscribe to All Account Updates

​Response with Initial Snapshot

​Subscribe to P&L Candles

​Supported Intervals

​Subscribe to Watchlist Updates

​Subscribe to News Updates

​Payload Data Types

​Real-Time Update Messages

​Order Updates

​Order Filled

​Multi-Leg Option Order

​ordStatus Values

​Order field enums

​Position Updates

​Long Stock Position

​Long Call Option

​Balance Updates

​Account-level enums

​Account Info Updates

​P&L Candle Updates

​Watchlist Updates

​News Updates

​Unsubscribing from Updates

​Unsubscribe from Account Updates

​Response

​Unsubscribe from Watchlist Updates

​Response

​Unsubscribe from News Updates

​Response

​Connection Management

​Ping/Pong Keepalive

​Session Expiration

​Error Handling

​Error Response Format

​Common Error Scenarios

​Authentication Timeout

​Invalid Token

​Missing Account ID

​Unknown Topic

​Best Practices

​Reliable Connection Handling

​Handle Session Expiration

​Efficient Subscription Management

Endpoint

Authentication Required

Session Management

Security Best Practices

Account Updates (`account`)

P&L Candles (`pnl`)

Watchlist Updates (`watchlist`)

News Updates (`news`)

Ping/Pong Keepalive

Handling Disconnects

Connection States

Connection Lifecycle

Subscription Flow

Common Errors

Error Response Format

Performance Optimization

Reliability

Security

Development

Authentication

Authenticate Connection

Authentication Success Response

Subscribing to Updates

Subscribe to Account Updates

Subscribe to All Account Updates

Response with Initial Snapshot

Subscribe to P&L Candles

Supported Intervals

Subscribe to Watchlist Updates

Subscribe to News Updates

Payload Data Types

Real-Time Update Messages

Order Updates

Order Filled

Multi-Leg Option Order

`ordStatus` Values

Order field enums

Position Updates

Long Stock Position

Long Call Option

Balance Updates

Account-level enums

Account Info Updates

P&L Candle Updates

Watchlist Updates

News Updates

Unsubscribing from Updates

Unsubscribe from Account Updates

Response

Unsubscribe from Watchlist Updates

Response

Unsubscribe from News Updates

Response

Connection Management

Ping/Pong Keepalive

Session Expiration

Error Handling

Error Response Format

Common Error Scenarios

Authentication Timeout

Invalid Token

Missing Account ID

Unknown Topic

Best Practices

Reliable Connection Handling

Handle Session Expiration

Efficient Subscription Management

Store State Locally