User Guide - Free Portfolio Tracker | Learn How to Track Your Investments

🚀 Getting Started

Free Portfolio Tracker runs entirely in your browser. Your data is stored locally on your device — nothing is ever sent to any server.

First-Time Setup

1Open the app and click ⚙️ Settings
2Set your preferred names for Person 1 and Person 2 (e.g. your names, or "Me" / "Partner")
3Paste your free Finnhub API key for live stock & crypto prices — get one at finnhub.io/register
4Optionally paste a Metals.dev API key if you hold gold, silver, or other precious metals — free at metals.dev
5Click Save Settings and start adding assets

💡

The app ships with demo data so you can explore before entering your own holdings. Delete demo assets whenever you're ready.

💼 Portfolio Page

Your main dashboard — all assets, live prices, and portfolio summary cards.

Quick Stats

💰 Total Value — Combined portfolio value across all assets and people
📈 Best Performer — Asset with the highest 24h price gain
📉 Worst Performer — Asset with the biggest 24h price loss
📊 Assets — Total number of assets tracked

Adding an Asset

1Click Add Asset
2Choose a type: Stock, Crypto, Metal, or Savings
3Enter the symbol — autocomplete will query Finnhub to help you find the right one
4Enter quantities for Person 1 and/or Person 2
5Click Save

Managing Assets

Edit — Click the ✏️ icon to change quantities or details
Delete — Click the 🗑️ icon to remove an asset
Search — Filter assets by name or symbol using the search box
Filter by type — Use All / Stocks / Crypto / Metals / Savings tabs
Sort — Click any column header to sort ascending or descending

Main Actions

🔄 Refresh Prices

Fetches live prices from Finnhub and Metals.dev. Spaced to stay within free-tier rate limits.

💾 Save Snapshot

Records your portfolio's current total value with a timestamp. Powers the History charts.

📤 Export

Downloads your entire portfolio as a JSON backup — assets, snapshots, and settings.

📥 Import

Restores a portfolio from a previously exported JSON backup file.

⚙️ Settings

Configure person names, API keys, and base currency.

💡

Prices are cached for 60 seconds. If the Refresh button is available again sooner than expected, the cache has expired — it's safe to refresh.

📈 History & Snapshots

The History page shows how your portfolio value has changed over time using saved snapshots.

Saving a Snapshot

1Refresh prices on the Portfolio page first
2Click 💾 Save Snapshot
3The app records total value, per-person values, and asset type breakdown

What the History page shows

Portfolio Value Over Time — Line chart of Combined, Person 1, and Person 2 values
Summary stats — Current value, first snapshot, total gain/loss, best & worst day
Snapshot table — All saved snapshots with date, value, change, and asset counts

💡

Save a snapshot weekly or after major portfolio changes to build up meaningful history over time.

📊 Charts

The Charts page provides a full visual breakdown of your portfolio using interactive Chart.js graphs.

Available Charts

Asset Allocation Donut — Percentage breakdown by type (Stocks, Crypto, Metals, Savings)
Person vs Person Bar — Side-by-side comparison of each person's holdings per asset type
Portfolio Breakdown — Horizontal bar of total value per asset type
Daily Gain/Loss Bar — Green/red bars showing daily change from each snapshot
Savings vs Invested Donut — Split between market-exposed assets and savings
Composition Over Time — Stacked bar showing how your asset mix shifts across snapshots
Cumulative Return Line — % return from your first snapshot to today
Performance Scatter — Each asset plotted by today's % change vs its total value (excludes savings)
Top 5 / Bottom 5 Performers — Best and worst assets by 24h price change

💡

Snapshot-based charts (Daily Gain/Loss, Composition, Cumulative Return) need at least 2 saved snapshots to display data.

⚖️ Compare

Side-by-side comparison of Person 1 and Person 2's holdings.

Total value for each person
Asset-by-asset breakdown showing quantity and value held by each person
Percentage ownership split per asset

📰 News

Get the latest market news for your stock holdings directly from Finnhub.

Requirements

A Finnhub API key configured in Settings
At least one stock asset in your portfolio

Features

General market news and asset-specific headlines
Filter by a specific stock symbol
Click any headline to read the full article

⚠️

Note: News is only available for stocks — crypto and metals are not supported by Finnhub's news API. The free tier has a limited number of news requests per day.

📥 Import CSV

Bulk-import assets from a CSV file instead of adding them one by one.

Supported Formats

M1 Finance Export — Import directly from an M1 Finance CSV export
Custom CSV — Columns: Symbol, Name, Type, Person1_Qty, Person2_Qty

How to Import

1Select import type (M1 Finance or Custom)
2Click Choose File and select your CSV
3Review the preview table
4Click Import Assets

💡

Import won't create duplicates — assets already in your portfolio are skipped automatically.

💾 Backup & Restore

Export (Backup)

1Click Export on the Portfolio page
2A portfolio_backup.json file downloads — includes all assets, snapshots, and settings
3Store this file somewhere safe (cloud storage, USB drive)

Import (Restore)

1Click Import on the Portfolio page
2Select your portfolio_backup.json file
3Your portfolio, snapshots, and settings are fully restored

⚠️

Warning: Importing replaces all current data. Export a backup first if you want to preserve your existing portfolio.

🔒 Privacy & Security

100% local — All data stored in your browser's localStorage. No backend, no server, no cloud sync.
No portfolio analytics — Umami Analytics tracks page views only (privacy-first, cookie-free). Your holdings, symbols, and values are never transmitted.
API keys stay local — Your Finnhub and Metals.dev keys are stored in localStorage only and never committed to any repository.
Clearing browser data — Deleting site data or localStorage will erase your portfolio. Export a backup first.
Multiple portfolios — Use different browser profiles or browsers to maintain completely separate portfolios.

🛠️ Troubleshooting

Prices not updating

Check your API key is saved in Settings
Wait 60 seconds — prices are cached and refreshes are rate-limited
Verify your key is valid at finnhub.io
Open DevTools (F12 → Console) to see specific error messages

Symbol not found

Stocks — Use the exact ticker (e.g. AAPL, not "Apple")
Crypto — Finnhub requires exchange prefix format, e.g. BINANCE:BTCUSDT
Metals — Use uppercase codes: XAU (gold), XAG (silver), XPT (platinum)
Use the autocomplete search when adding an asset — it queries Finnhub directly

Data disappeared

Check browser data wasn't cleared — localStorage is wiped when you clear site data
Make sure you're on the same browser and profile you used originally
Restore from your last JSON export backup

✨ Tips & Tricks

Regular snapshots — Save weekly or after major price moves to build meaningful history
Export monthly — Keep a JSON backup to protect against accidental data loss
Use search — The search box filters assets instantly, useful for large portfolios
Multiple browsers — Run separate portfolios (e.g. personal vs business) using different browsers
CSV import — Faster than manual entry if you have 10+ assets to add at once
Bookmark pages — Save direct links to Charts or History for quick access
Scatter chart — Use it after a market move to spot which of your assets were most impacted

📖 User Guide

Contents

First-Time Setup

Quick Stats

Adding an Asset

Managing Assets

Main Actions

🔄 Refresh Prices

💾 Save Snapshot

📤 Export

📥 Import

⚙️ Settings

Saving a Snapshot

What the History page shows

Available Charts

Requirements

Features

Supported Formats

How to Import

Export (Backup)

Import (Restore)

Prices not updating

Symbol not found

Data disappeared