Portfolio Tracking

When to use

When Joseph provides holding updates (quantity changes, new purchases, avg price changes) and wants to maintain the tracking file and generate a dated portfolio snapshot. Also when generating the weekly portfolio news digest (every Sunday via cron). This is the recurring maintenance workflow — distinct from quarterly analysis (see portfolio-analysis).

Key Files

• wiki/wealth/invest/portfolio/tracking/holdings.csv — master holdings (source, code, ticker, name, qty, cost_price, asset_class)
• wiki/wealth/invest/portfolio/tracking/YYYY-MM-DD-portfolio.md — dated snapshots
• wiki/wealth/invest/portfolio/news/YYYY-Wnn-weekly-news.md — weekly news digests (ISO week number)

Workflow

1. Update holdings.csv

1. Parse Joseph's update: fund/stock name, new units, new avg price, total invested value

2. Locate the matching row in holdings.csv (match by name or scheme code)

3. Patch the row: update qty and cost_price columns

4. Verify the patch landed correctly (read back the affected lines)

holdings.csv format: source,code,nse_ticker,yahoo_symbol,name,qty,cost_price,asset_class

2. Fetch current prices

• Stocks/ETFs: Yahoo Finance v8 chart API (requires crumb auth — see Pitfalls)
• MFs: AMFI portal.amfiindia.com/spages/NAVAll.txt (semicolon-delimited)

Batch-fetch all tickers in one script. Do not make serial curl calls (times out).

3. Generate portfolio snapshot

1. Read holdings.csv for all quantities and cost prices

2. Compute weighted-average buy price for stocks held in both ICICI and Zerodha (e.g., Coal India, GAIL, NMDC)

3. Value = qty × CMP (stocks/ETFs) or units × NAV (MFs)

4. P&L = value - (qty × cost_price)

5. Asset allocation: stocks %, ETFs % (with gold/silver/index sub-breakdown), MFs %

6. Write YYYY-MM-DD-portfolio.md following the template (see references/snapshot-template.md)

4. Confirm to Joseph

• Summary table: total value, P&L, asset allocation
• Day-over-day change if previous snapshot exists
• Note any NAV lag (PPFAS funds publish NAV with2-day delay)

Pitfalls

Yahoo Finance API auth

• v7/finance/quote returns 401 Unauthorized — do not use this endpoint
• Use v8/chart with crumb auth:

1. GET https://fc.yahoo.com (ignore error, just need cookie)

2. GET https://query2.finance.yahoo.com/v1/test/getcrumb (returns crumb string)

3. Use http.cookiejar + urllib.request.build_opener to maintain session

4. Fetch: https://query2.finance.yahoo.com/v8/finance/chart/{ticker}?range=1d&interval=1d&crumb={crumb}

• For specific date prices: use period1/period2 timestamps instead of range=1d
• Write the fetch script to a file and run it — f-string escaping in inline scripts is fragile

AMFI NAV format

• URL: https://portal.amfiindia.com/spages/NAVAll.txt
• Semicolon delimited — Fields: Scheme Code;ISIN Payout;ISIN Reinvest;Scheme Name;Plan;Option;NAV;Date
• Filter by scheme code using awk for speed (not Python line-by-line)
• PPFAS funds have2-day NAV lag — snapshot may show older NAV for Parag Parikh funds. Note this.

Number formatting

• Indian lakhs/crores: ₹1,36,96,321 (not ₹13,696,321)
• Format: last 3 digits comma-separated, then groups of 2 going left
• Percentages: one decimal place, signed (+/-)

holdings.csv gotchas

• Same stock in ICICI + Zerodha → separate rows, merged in portfolio snapshot
• MF scheme codes are the reliable identifier (names vary across platforms)
• cost_price is average buy price, not current price
• Asset classes: stock, etf, mf

Weekly News Digest

A weekly digest covering news for ALL holdings (stocks, ETFs, MFs). Complements the price snapshot — snapshot tracks values, digest tracks events.

When to run

Every Sunday morning via cron. Covers the Mon–Sat trading week.

Workflow

1. Read holdings.csv for the full portfolio (stocks, ETFs, MFs).

2. Fetch price data via yfinance for all stock/ETF tickers (5-day period for WoW change).

3. Fetch news — yfinance .news attribute returns empty for Indian (.NS) tickers. Use web_search as fallback. Focus searches on significant movers (>2% WoW change) to avoid noise. Search queries: "{stock name} India stock news September 2026".

4. Get market context — Nifty 50, crude oil, gold, silver, Nasdaq 100 levels and WoW change via yfinance.

5. Write digest to wiki/wealth/invest/portfolio/news/YYYY-Wnn-weekly-news.md (date = ISO week number of today).

Format rules

• Every holding gets a section — even if "No material news this week." Nothing should feel missed.
• Stocks: individual sections with CMP, WoW %, and news bullets. Big movers (>5%) get ⚡ flag.
• ETFs: single table with INR price, WoW change, underlying price, underlying WoW change. Flag currency impact if INR commodity ETFs diverge from USD underlying.
• MFs: single table with notes column. Rarely have weekly news; quarterly holdings disclosures are the signal.
• Market Context: Nifty, crude, gold, silver, Nasdaq + key events for the week.
• Action Items: dividend record dates, ex-dates, AGMs, things to monitor.
• Number formatting: Indian lakhs/crores, signed percentages (+/-), one decimal place.

Pitfalls

• yfinance .news is empty for Indian tickers — always use web_search fallback. Don't assume the API will work.
• Don't search news for ALL tickers — that's 25+ web searches. Filter to movers (>2% WoW change) + any stock with known upcoming events (dividends, earnings).
• ETF currency impact — Gold/Silver ETFs in INR can diverge from USD underlying due to INR/USD movement. Always compare INR change vs underlying change and flag significant divergence.
• Dividend dates — check BSE/NSE corporate action calendars. Record dates matter (must hold before), not ex-dates.
• MF NAV lag — PPFAS funds publish NAV with 2-day delay. Note this in the digest if NAVs appear stale.

Storage

• wiki/wealth/invest/portfolio/news/ — one file per week
• File naming: YYYY-Wnn-weekly-news.md (ISO week number of run date)
• Joseph may clean up files older than 1 year

Template

See references/news-digest-template.md for the markdown structure.

Data Sources Reference

• references/yahoo-finance-api.md — crumb auth, endpoints, rate limits
• references/amfi-nav.md — NAV file format, scheme code lookup
• references/snapshot-template.md — portfolio snapshot markdown template
• references/news-digest-template.md — weekly news digest markdown template