Portfolios

Portfolio endpoints let you create multi-asset portfolios, record trade history, compute current positions and NAV, and generate a structured context payload for analysis.

All portfolio endpoints are owner-scoped — each API key can only access its own portfolios.

---

Endpoints

Method	Path	Description
GET	/v1/portfolios	List your portfolios
POST	/v1/portfolios	Create a new portfolio
GET	/v1/portfolios/:id	Get portfolio metadata
PATCH	/v1/portfolios/:id	Update portfolio metadata
DELETE	/v1/portfolios/:id	Delete a portfolio
GET	/v1/portfolios/:id/outstanding	Current positions (mark-to-market)
GET	/v1/portfolios/:id/nav	NAV history
GET	/v1/portfolios/:id/trades	Trade ledger
GET	/v1/portfolios/:id/context	LLM-ready portfolio context
POST	/v1/portfolios/:id/trades	Add a trade
PATCH	/v1/portfolios/:id/trades/:trade_id	Edit a trade
DELETE	/v1/portfolios/:id/trades/:trade_id	Remove a trade
DELETE	/v1/portfolios/:id/positions/:listing_id	Remove all trades for a position

---

GET /v1/portfolios

List all portfolios belonging to the authenticated API key.

Parameter	Type	Description
include	string	Optional: breakdown — include theme/country distribution per portfolio.

GET /v1/portfolios

---

POST /v1/portfolios

Create a new portfolio.

Request body

{
  "name": "Tech Growth 2026",
  "description": "US-focused high-growth tech names",
  "base_currency": "USD",
  "mode": "standard"
}

Field	Type	Required	Description
name	string	✅	Portfolio name.
description	string	—	Optional description.
base_currency	string	—	Base currency code. Default USD.
mode	string	—	standard (default) or advanced (enables short/leverage trades).

Returns 201 Created with the new portfolio object.

---

GET /v1/portfolios/:id

Metadata for a single portfolio — name, description, base currency, mode, and investor intent summary.

GET /v1/portfolios/42

---

PATCH /v1/portfolios/:id

Update editable metadata.

{
  "name": "Tech Growth 2026 (revised)",
  "description": "Updated focus",
  "base_currency": "USD"
}

Editable fields: name, description, base_currency, mode, margin.

---

DELETE /v1/portfolios/:id

Delete a portfolio and all its trade history. Irreversible.

---

GET /v1/portfolios/:id/outstanding

Current positions with mark-to-market values. Returns each position's quantity, average cost, current price, unrealized P&L (in base currency and %), and weight.

GET /v1/portfolios/42/outstanding

---

GET /v1/portfolios/:id/nav

NAV (net asset value) history — daily portfolio value from inception to today. Useful for plotting cumulative returns and drawdowns.

GET /v1/portfolios/42/nav

---

GET /v1/portfolios/:id/trades

Full trade ledger — all buy/sell entries with dates, quantities, prices, and fees.

GET /v1/portfolios/42/trades

---

GET /v1/portfolios/:id/context

LLM-ready portfolio context — a structured snapshot for analysis. Returns a composite payload including:

• Holdings summary (position weights, sectors, countries, themes)
• Performance attribution over the selected window
• Key metrics (volatility, Sharpe, max drawdown)
• Recent news impact on held positions

:::info Cost GET /v1/portfolios/:id/context charges 5 credits. :::

Parameter	Type	Description
window	string	Analysis window: 7d, 30d, 90d, 1y, mtd, qtd, ytd.
from / to	string	ISO date range, alternative to window.
snapshots	string	Composition granularity override.

90-day portfolio context

GET /v1/portfolios/42/context?window=90d

---

POST /v1/portfolios/:id/trades

Add a trade to the portfolio.

Request body

{
  "ticker": "NVDA.US",
  "date": "2026-01-15",
  "quantity": 100,
  "price": 142.50,
  "fee": 1.00,
  "direction": "buy"
}

Field	Type	Required	Description
ticker	string	✅	Asset ticker in SYMBOL.EXCHANGE format.
date	string	✅	Trade date YYYY-MM-DD.
quantity	number	✅	Number of shares/units (positive).
price	number	✅	Execution price per share (in the asset's native currency).
fee	number	—	Commission/fee. Default 0.
direction	string	—	buy (default) or sell. In advanced mode: also short and cover.

---

PATCH /v1/portfolios/:id/trades/:trade_id

Edit an existing trade. Use the same fields as POST /v1/portfolios/:id/trades. Only the fields you send are updated.

---

DELETE /v1/portfolios/:id/trades/:trade_id

Remove a single trade entry from the ledger.

---

DELETE /v1/portfolios/:id/positions/:listing_id

Remove all trades for a specific position (identified by its internal listing_id). This closes out the entire position history for that stock.

Parameter	Type	Description
after	string	Only delete trades after this date YYYY-MM-DD.
before	string	Only delete trades before this date YYYY-MM-DD.

Close out NVDA position entirely

DELETE /v1/portfolios/42/positions/12345