Skip to main content
A position is a user’s holding in a single asset — how many shares, at what average cost, worth how much now, and up or down by how much. Positions are created when buy orders fill and updated as prices move and further orders execute. Each carries a prefixed pos_ id.

​
Core fields

FieldDescription
symbolTicker symbol
quantityShares held (may be fractional)
average_cost_basisVolume-weighted average purchase price
market_valuequantity × current_price
unrealized_plmarket_value − total cost basis
current_priceLatest market price
Positions also expose the currency, total cost basis, price freshness, and timestamps — see the API reference for the complete schema.

​
How positions change

EventEffect
Buy fillsCreates or increases the position; recalculates average_cost_basis
Sell fillsDecreases the position; removed when fully sold
Price movesUpdates current_price, market_value, unrealized_pl

​
Reading positions

List all positions for an investor, or fetch one by its pos_ id:
  • GET /v1/investors/{investor_id}/positions
  • GET /v1/investors/{investor_id}/positions/{position_id}
To retrieve and interpret holdings step by step, see the journey guide: Track positions. Position schemas are in the API reference.