Skip to main content
A Position represents the user’s holding in a specific asset — the quantity held, average cost basis, current market value, and unrealized profit or loss. Positions are created automatically when orders fill and updated in real-time as market prices change.

​
Position object

{
  "id": "pos_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_id": "3d0b0e65-35d3-4dcd-8df7-10286ebb4b4b",
  "symbol": "AAPL",
  "asset_id": "asset_9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "currency": "USD",
  "quantity": "10",
  "average_cost_basis": "178.50",
  "total_cost_basis": "1785.00",
  "current_price": "182.30",
  "market_value": "1823.00",
  "unrealized_pl": "38.00",
  "unrealized_pl_percent": "0.0213",
  "price_source": "ALPACA",
  "price_confidence": "REAL_TIME",
  "price_timestamp": "2025-06-15T14:30:00Z",
  "last_transaction_at": "2025-06-15T14:00:00Z",
  "created_at": "2025-06-15T14:00:00Z",
  "updated_at": "2025-06-15T14:30:00Z"
}
FieldDescription
idUnique position identifier
account_idAccount that holds this position
symbolTicker symbol
asset_idUnique asset identifier
currencyISO 4217 currency code
quantityNumber of shares held (can be fractional)
average_cost_basisVolume-weighted average purchase price
total_cost_basisquantity * average_cost_basis
current_priceLatest market price
market_valuequantity * current_price
unrealized_plmarket_value - total_cost_basis
unrealized_pl_percentUnrealized P&L as a percentage
price_sourceWhere the price came from (ALPACA, NAYA, DATABASE, UNAVAILABLE)
price_confidenceFreshness of the price (REAL_TIME, DELAYED, END_OF_DAY, STALE, UNAVAILABLE)
price_timestampWhen the price was last updated
last_transaction_atWhen the position was last affected by a transaction
created_atWhen the position was created
updated_atWhen the position was last updated

​
Querying positions

# All positions for an account
curl -X GET "$BASE_URL/trading/accounts/$ACCOUNT_ID/positions" \
  -H "Authorization: Basic $AUTH"

# Specific position
curl -X GET "$BASE_URL/trading/accounts/$ACCOUNT_ID/positions/$POSITION_ID" \
  -H "Authorization: Basic $AUTH"

​
How positions update

EventEffect on position
Buy order fillsCreates or increases position; recalculates average_cost_basis
Sell order fillsDecreases position; removes if fully sold
Market price changesUpdates current_price, market_value, unrealized_pl
Stock splitAdjusts quantity and average_cost_basis proportionally

​
Key endpoints

MethodPathDescription
GET/trading/accounts/{id}/positionsList all positions
GET/trading/accounts/{id}/positions/{position_id}Get position details