Portfolio Holdings

Manage portfolio holdings — add, update, remove positions and run analysis.

GET/api/portfolio/holdings

List all portfolio holdings sorted by target allocation.

Response

{
  "holdings": [
    {
      "id": 1,
      "ticker": "AAPL",
      "target_allocation": 15,
      "cost_basis": 165.20,
      "shares": 100,
      "added_at": "2026-01-15T00:00:00Z",
      "updated_at": "2026-04-28T00:00:00Z"
    }
  ]
}

POST/api/portfolio/holdings

Add a new holding to the portfolio.

Request Body

Field	Type	Required	Description
ticker	string	Yes	Stock ticker (auto-uppercased)
target_allocation	number	Yes	Target allocation percentage (0-100)
cost_basis	number	No	Average cost per share
shares	number	No	Number of shares held

Response

{
  "holding": {
    "id": 2,
    "ticker": "NVDA",
    "target_allocation": 10,
    "cost_basis": 450.00,
    "shares": 50,
    "added_at": "2026-05-02T00:00:00Z",
    "updated_at": "2026-05-02T00:00:00Z"
  }
}

PATCH/api/portfolio/holdings/[id]

Update an existing holding.

Request Body

Field	Type	Required	Description
target_allocation	number	No	New target allocation
cost_basis	number	No	Updated cost basis
shares	number	No	Updated share count

Response

{
  "holding": { "id": 2, "ticker": "NVDA", "target_allocation": 12, ... }
}

DELETE/api/portfolio/holdings/[id]

Remove a holding from the portfolio.

Response

{
  "success": true,
  "message": "Holding deleted"
}

GET/api/portfolio/analyze

Run portfolio analysis — risk metrics, allocation drift, recommendations.

Response

{
  "holdings": 8,
  "totalAllocation": 100,
  "risk": { "beta": 1.12, "sharpe": 1.45, "maxDrawdown": -12.3 },
  "drift": [
    { "ticker": "AAPL", "target": 15, "actual": 18.2, "drift": 3.2 }
  ]
}