Profit & Loss Stream

Beta

The WebSocket API is currently in beta. Features and endpoints are subject to change.

Overview

The PnL Stream provides real-time streaming of account profit and loss updates with position-level details. It updates based on price changes and order fills. This stream is designed to give you up-to-the-second insights into your account's performance, including both aggregate account values and individual position metrics.

Endpoint: wss://webapi.tradezero.com/stream/pnl

Usage

Step 1: Connect and Authenticate

First, connect to the PnL endpoint and authenticate as described in the Introduction page.

Step 2: Subscribe to an Account

After authentication, subscribe to PnL updates for a specific account by sending:

{
  "account": "YOUR_ACCOUNT_ID"
}

Subscription Responses

Success - Initial Snapshot:

You'll receive a complete snapshot of the account's current state:

{
  "ts": 1770232416261,
  "action": "init",
  "target": "pnlReturn",
  "pnlReturn": {
    "accountValue": 9883.69,
    "availableCash": 9755.18,
    "optionCashUsed": 0.0,
    "usedLeverage": 1.87,
    "allowedLeverage": 2.0,
    "sharesTraded": 0.0,
    "exposure": 18447.89,
    "dayUnrealized": -116.31,
    "dayRealized": 0.0,
    "dayPnl": -116.31,
    "totalUnrealized": -1068.22,
    "equityRatio": 0.535762704720142653,
    "positions": [
      {
        "positionId": "7260105185048870000",
        "symbol": "AAPL",
        "pnlCalc": {
          "unrealizedPnL": 60.08,
          "dayUnrealizedPnL": 23.44,
          "pctPnLMove": 5.77,
          "dayPctPnLMove": 2.17,
          "exposure": 1101.36
        },
        "realizedPnl": 0.0,
        "dayRealizedPnl": 0.0
      }
    ]
  }
}

Error - Invalid Account:

{
  "ts": 1770237416195,
  "action": "error",
  "message": "account not found"
}

Real-Time Updates

After receiving the initial snapshot, you'll receive two types of update messages:

1. Aggregate Account Updates

Updates to account-level aggregate values:

{
  "ts": 1770232416799,
  "action": "update",
  "target": "aggCalcs",
  "aggCalcs": {
    "accountValue": 9883.82,
    "exposure": 18448.02,
    "dayUnrealized": -116.18,
    "dayPnl": -116.18,
    "totalUnrealized": -1068.09,
    "equityRatio": 0.535765976119629001
  }
}

2. Position-Level Updates

Updates to individual position values:

{
  "ts": 1770232416799,
  "action": "update",
  "target": "position",
  "position": {
    "positionId": "7260109165951251001",
    "symbol": "MSFT",
    "pnlCalc": {
      "unrealizedPnL": -103.14,
      "dayUnrealizedPnL": 11.36,
      "pctPnLMove": -11.01,
      "dayPctPnLMove": 1.38,
      "exposure": 833.78
    }
  }
}

Multiple Account Subscriptions

You can subscribe to multiple accounts by sending additional account messages:

{
  "account": "ANOTHER_ACCOUNT_ID"
}

Each account will send its own initial snapshot followed by real-time updates.

Field Definitions

Account-Level Fields

Field	Type	Description
accountValue	number	Total account value
availableCash	number	Cash available for trading
optionCashUsed	number	Cash allocated to options positions
usedLeverage	number	Current leverage being used
allowedLeverage	number	Maximum allowed leverage
sharesTraded	number	Number of shares traded
exposure	number	Total market exposure
dayUnrealized	number	Unrealized profit/loss for the day
dayRealized	number	Realized profit/loss for the day
dayPnl	number	Total profit/loss for the day
totalUnrealized	number	Total unrealized profit/loss
equityRatio	number	Equity to account value ratio

Position-Level Fields

Field	Type	Description
positionId	string	Unique identifier for the position
symbol	string	Stock symbol
unrealizedPnL	number	Total unrealized profit/loss
dayUnrealizedPnL	number	Unrealized profit/loss for the day
pctPnLMove	number	Percentage change in total P&L
dayPctPnLMove	number	Percentage change in day P&L
exposure	number	Position's market exposure
realizedPnl	number	Total realized profit/loss
dayRealizedPnl	number	Realized profit/loss for the day