Positions API

View current trading positions.

Endpoints

Method	Endpoint	Description
GET	/api/v1/positions	List all positions
GET	/api/v1/positions/:accountId	List positions for an account

List All Positions

Retrieve positions across all accounts.

GET /api/v1/positions
Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Description
accountId	string	Filter by account ID
symbol	string	Filter by symbol

Response

{
  "positions": [
    {
      "id": "uuid",
      "accountId": "uuid",
      "symbol": "AAPL",
      "quantity": 100,
      "side": "LONG",
      "avgCost": 150.25,
      "currentPrice": 155.50,
      "marketValue": 15550.00,
      "unrealisedPnl": 525.00,
      "unrealisedPnlPercent": 3.49,
      "dayChange": 2.50,
      "dayChangePercent": 1.64,
      "lastUpdated": "2026-02-25T10:30:00Z"
    },
    {
      "id": "uuid",
      "accountId": "uuid",
      "symbol": "MSFT",
      "quantity": 50,
      "side": "LONG",
      "avgCost": 380.00,
      "currentPrice": 395.25,
      "marketValue": 19762.50,
      "unrealisedPnl": 762.50,
      "unrealisedPnlPercent": 4.01,
      "dayChange": -1.25,
      "dayChangePercent": -0.32,
      "lastUpdated": "2026-02-25T10:30:00Z"
    }
  ],
  "summary": {
    "totalMarketValue": 35312.50,
    "totalUnrealisedPnl": 1287.50,
    "positionCount": 2
  }
}

List Account Positions

Retrieve positions for a specific account.

GET /api/v1/positions/:accountId
Authorization: Bearer <access_token>

Response

{
  "accountId": "uuid",
  "positions": [
    {
      "id": "uuid",
      "symbol": "AAPL",
      "quantity": 100,
      "side": "LONG",
      "avgCost": 150.25,
      "currentPrice": 155.50,
      "marketValue": 15550.00,
      "unrealisedPnl": 525.00,
      "unrealisedPnlPercent": 3.49,
      "lastUpdated": "2026-02-25T10:30:00Z"
    }
  ],
  "summary": {
    "totalMarketValue": 15550.00,
    "totalUnrealisedPnl": 525.00,
    "positionCount": 1
  }
}

Position Fields

Field	Type	Description
id	string	Position ID
accountId	string	Account ID
symbol	string	Stock symbol
quantity	number	Number of shares
side	string	LONG or SHORT
avgCost	number	Average cost per share
currentPrice	number	Current market price
marketValue	number	Current market value
unrealisedPnl	number	Unrealised profit/loss
unrealisedPnlPercent	number	Unrealised P&L as percentage
dayChange	number	Price change today
dayChangePercent	number	Percentage change today
lastUpdated	string	Last sync timestamp

Position Side

Side	Description
LONG	Bought shares (positive quantity)
SHORT	Sold short (borrowing shares)

Notes

• Positions are synced from the broker automatically
• Use account sync to refresh position data
• Prices update based on broker data frequency
• Closed positions (quantity = 0) are not returned

Error Responses

Account Not Found

{
  "error": "ACCOUNT_NOT_FOUND",
  "message": "Account with ID xyz not found"
}

Positions Unavailable

{
  "error": "POSITIONS_UNAVAILABLE",
  "message": "Unable to fetch positions. Broker may be disconnected."
}