Portfolio Tracker — Methodology Handbook

The Portfolio Tracker turns a list of holdings into a live picture of what you own, what it cost, what it is worth now, and how each position is performing. It covers stocks, ETFs, crypto and anything else you want to track manually — one account, one currency label, one allocation view.

1. What it tracks

Each holding is one position you own:

• Symbol — the ticker (e.g. AAPL, VOO, BTC). Stored uppercase.
• Name — optional human label (e.g. "Apple Inc.").
• Type — Stock, ETF, Crypto, Index, Commodity or Other. This drives which price source is used (see §3). Pick Index for S&P 500 / Nasdaq / Dow etc., or Commodity for gold, silver, oil and the like — a curated picker suggests the common ones.
• Quantity — how many shares / coins / units you hold.
• Average cost — your blended cost per unit. This is the number that makes cost basis and gain/loss correct; update it when you add to a position.
• Current price — optional manual override. Leave it empty to let the tracker fetch a live price; set it to pin your own price.
• Account — optional free-text label (e.g. "Brokerage", "Crypto wallet") so one portfolio can span several places.

2. The numbers, defined

For one holding:

• Cost basis = quantity × average cost. What you paid in total.
• Market value = quantity × current price. What it is worth now.
• Gain / loss = market value − cost basis. Unrealized — it is paper profit until you sell.
• Gain % = gain ÷ cost basis × 100.
• Allocation % = this holding's market value ÷ total portfolio value. The share of your portfolio this one position represents.

For the whole portfolio (the Overview cards):

• Total value = sum of every holding's market value.
• Invested = sum of every holding's cost basis.
• Total gain / loss = total value − invested, with the matching percent.
• Annualized return (XIRR) = the money-weighted annualized rate of return. Unlike the simple gain %, it accounts for when money went in and out: each buy is a cash outflow on its date, each sell and dividend an inflow, and your current value is treated as a final inflow today. The tracker solves for the yearly rate that makes those dated flows net to zero. This is the number that lets you compare a position held 5 years against one held 6 months fairly — it's what "serious" trackers (Sharesight et al.) report. Shown as "—" until there's at least one buy and one offsetting inflow to solve from.

Currency model

The base storage currency is USD — all holding cost basis, market value and gain/loss are computed in USD, then converted to your display currency at the current FX rate so the whole tracker reads in the currency you pick.

True multi-currency input: each transaction carries its own entry currency (the currency you actually paid in, e.g. GBP). When you save a foreign-currency trade, the tracker captures the historical FX rate on the trade date (entry currency → USD) and stores it on the row. Cost basis is then price × historical_rate, so a position bought in GBP last year and one bought in USD this year combine into one correct USD cost basis — and everything still displays in your chosen currency. Transaction rows show each trade in its own entry currency (the honest amount you paid); portfolio-level totals are in your display currency. Legacy trades default to USD at a rate of 1.

3. Where prices come from

Prices resolve in a fixed priority order:

1. Manual override — if you set "Current price" on a holding, that wins, always. Use this for assets the live feed can't quote (private holdings, foreign tickers, anything illiquid).
2. Live cached quote — otherwise the tracker fetches a current price:
   • Stocks / ETFs / other → Finnhub real-time quote endpoint.
   • Crypto → CoinGecko simple-price endpoint (batched, free).
   • Indices / commodities (S&P 500, gold, silver, oil…) → Yahoo Finance, falling back to Stooq. Both are free; some cloud networks throttle them, so if a quote can't be fetched, set a manual price — or track the exposure via its ETF (e.g. GLD for gold, SPY for the S&P 500), which prices through the reliable stock feed. Quotes are cached server-side for ~15 minutes in a shared price_cache table, so repeated views and many users don't hammer the upstream APIs.
3. None — if neither a manual price nor a fresh quote is available, the holding shows "—" for price and is excluded from totals until a price resolves. A small manual badge marks any price you set yourself.

The price feeds are best-effort: a transient upstream failure falls back to the last cached value, then to the manual price, then to "unpriced". Your cost basis is always exact because it comes from your own inputs, never the feed.

Logos: crypto logos come from CoinGecko; stock / ETF logos are resolved by ticker via Logo.dev (any listed ticker, not a fixed list), falling back to a favicon guess and then a coloured-initials avatar; indices show their provider's brand logo (S&P Global, Nasdaq…) via Logo.dev; commodities show a clean themed vector icon (gold/oil/gas). Logos are provided by Logo.dev.

4. Allocation & accounts view

The Overview tab renders a donut of your holdings weighted by market value, so you can see concentration at a glance — whether one position dominates, how much sits in crypto vs equities, etc. Holdings with no resolvable price are omitted from the donut (they have no value to weight).

Alongside it the Overview breaks value down by asset type (stock / ETF / crypto / other) and, once your positions span two or more accounts, by account (e.g. Brokerage vs Retirement vs Crypto wallet). On the Holdings tab a row of account chips lets you filter the table to one account at a time, and each row carries a small account tag so mixed views stay readable.

A Portfolio value trend chart sits at the top of the Overview. The tracker records one snapshot of your total value per day (captured automatically when you open the tracker — no setup), so the line fills in over time and shows your gain/loss across the visible window. It is a value-over-time view, not a benchmark comparison.

4b. Dividends & income

The Dividends tab logs the income your holdings pay out. Each entry records the symbol, the cash amount received, the pay date and an optional account. From that log the tab shows:

• Total income — every dividend ever logged.
• This year — income with a pay date in the current calendar year.
• Last 12 months — trailing-twelve-month income.
• Yield on cost — trailing-12-month income ÷ your total cost basis × 100, i.e. the cash return your invested capital is currently throwing off.

Dividends are logged manually (there is no automatic dividend feed). Deleting a payment is a soft delete — it goes to the Dividends Trash and can be restored.

4c. Assets vs transactions

The Holdings tab has two views, toggled at the top:

• Assets — your positions, one row per holding (the aggregate). Click any asset to open its detail page: current value, quantity, average buy price and total profit/loss, followed by that asset's full transaction history.
• Transactions — every buy and sell across all assets in one chronological list.

Transactions are the source of truth. When an asset has transactions, its quantity and average buy price are derived from them — buys add to the position and raise the average; sells reduce the quantity (and realize P&L on a running-average basis). You add a transaction (buy or sell) on the asset's detail page or from the Transactions view; creating a buy for a brand-new ticker creates the asset automatically. Assets entered directly (with a quantity and average cost, no transactions) keep using those stored numbers, so older entries keep working unchanged.

4d. Watchlist

The Watchlist tab tracks tickers you don't own — things you're considering or just want to keep an eye on — with the same live stock + crypto pricing as your holdings (price + 24-hour change). Add a symbol via the same ticker autocomplete used for transactions; it never counts toward your totals, cost basis or holdings cap. Removing an item is a soft delete. Watchlist is user-scoped, not per-portfolio (you watch a ticker regardless of which portfolio you're viewing). Stored in portfolio_watchlist. Free on both tiers.

4e. Price alerts

Set a price alert on any holding (asset detail view) or watchlist symbol via the 🔔 button: pick a direction (above / below) and a target price. An hourly background job checks live prices and, the moment one crosses your target, sends you a Web Push + in-app notification and disarms the alert (it fires once — re-arm it any time, or pause it). Targets are stored in USD; you enter and see them in your display currency. Stored in portfolio_price_alerts. Free on both tiers.

4h. Tax report (realized gains, lots)

The Tax tab turns your sells into a realized-gains report the way a tax preparer needs it. Unlike the running-average basis used elsewhere, this uses lot accounting: every buy is a lot with its own acquisition date and cost, and each sell is matched to specific lots by the method you choose — FIFO (first in, first out), LIFO (last in, first out) or HIFO (highest cost first, which minimizes the taxable gain). Each matched piece is a disposal, classified short-term (held ≤ 1 year) or long-term (held

1 year). Results are summarized by tax year (short / long / total gain, proceeds, cost basis) with a full lot-by-lot disposal list, and a free CSV export for your accountant. Buy fees/tax fold into cost basis; sell fees reduce proceeds. Amounts are in USD (a tax record shouldn't be re-rated to today's FX). It's a general summary, not tax advice.

4g. Benchmark comparison

On the value chart, the Compare dropdown overlays a benchmark — S&P 500, Nasdaq 100, Bitcoin or Gold — as a dashed line. It's cashflow- matched: it seeds the index with your portfolio's value at the window start, then "invests" each later contribution (the change in your cost basis) into the index on the day you made it — i.e. "what if every dollar you put in had gone into the index instead". That's the honest way to see whether you're beating the market: because it tracks your deposits too, the line stays comparable instead of looking flat when you add money. A chip next to the change badge shows the benchmark's own return over the window. Available on the daily ranges (not the 24-hour view). History comes from Yahoo Finance (indices/gold) and CoinGecko (BTC, ~1-year free limit), cached for an hour.

4f. Sharing a portfolio

The Share button (next to Favorite) creates a public, read-only link to your portfolio — handy for newsletters, threads or showing returns to others. You choose exactly what it exposes (total value, allocation, invested, unrealized / realized / total P/L, annualized return, holdings list) with checkboxes, and a "Hide all numbers" toggle that shows only percentages / allocation while masking every absolute amount. The link is an unguessable token; the public page renders only the fields you ticked, carries no login and no personal info, and is never indexed by search engines. One stable link per portfolio — update what it shows any time, or Revoke it (the link then stops working). Stored in portfolio_shares. Free on both tiers.

5. Adding, editing, deleting

• Add holding opens a form: symbol, type, name, quantity, average cost, optional current price, optional account.
• Import (Pro) — two sources feed the same editable review table:
  • Screenshot / photo — Claude Vision reads every position from a brokerage or exchange screenshot.
  • CSV file — columns are auto-mapped (ticker / quantity / avg cost / type under many common header names). You deselect or fix any row, then import the selected ones in one go.
• Export CSV (always free, any tier) — download every holding with its cost basis and live figures (price, market value, gain, gain %).
• Refresh prices — force a live re-fetch of stock + crypto quotes, bypassing the 15-minute cache.
• Edit reopens the same form pre-filled.
• Delete is a soft delete: the holding moves to Trash, it does not vanish. Restore it any time, or permanently delete it from the Trash panel. Soft-deleted holdings free up a free-tier slot. (A daily cleanup hard-deletes trashed rows after 30 days.)

6. Free vs Pro

The free tier tracks up to 10 holdings at once (deleting one frees a slot). Pro removes the cap. CSV export of your own data is always free. Live price fetching, the allocation donut and the Overview analytics are available on both tiers — the cap is purely on how many positions you can hold simultaneously.

7. What it is not

• It is not a brokerage connection — there is no live account linking or automatic sync. You enter holdings yourself, or seed them in bulk from a screenshot via the Pro Import from screenshot flow.
• It does not track realized P&L, dividends or tax lots — for trade-by-trade performance and realized P&L, use the Trading Journal, which is the transaction-level companion to this position-level tracker.
• It does convert currencies: prices are USD-based, each trade can be entered in its own currency (converted to USD at the trade-date historical rate), and the whole tracker re-displays in your chosen currency at the current rate (see §2 → Currency model).

8. Status

Shipped: holdings CRUD, live Finnhub + CoinGecko pricing with a shared 15-minute cache, manual price override, a tabbed workspace (Overview dashboard + Holdings), the Overview dashboard (headline tiles, allocation donut, value-by-asset-type, top holdings, best/worst performer), Pro screenshot import (Claude Vision → editable review → bulk insert), soft-delete Trash with restore, free-tier holdings cap with server-side enforcement, and the SiteAssistant cross-product snapshot (holdings count, invested, market value, unrealized gain, top positions).

Logos provided by Logo.dev