commit

bufdev · bufdev · commit fd2c7902fe40 · 2026-03-03T12:46:19.000-05:00
diff --git a/README.md b/README.md
@@ -30,6 +30,9 @@ ibctl holding list
 # View holdings in CAD instead of USD.
 ibctl holding list --base-currency CAD
 
+# View holdings with real-time prices from Yahoo Finance.
+ibctl holding list --realtime
+
 # View all transactions for the year.
 ibctl transaction list --from 20250101 --to 20251231 --base-currency USD
 ```
@@ -56,9 +59,8 @@ ibctl transaction list --from 20250101 --to 20251231 --base-currency USD
 | `ibctl holding value` | Display portfolio value with estimated tax impact |
 | `ibctl transaction list` | List all transactions (buys, sells, dividends, interest, WHT, etc.) chronologically |
 | `ibctl transaction sale list` | List realized security sales with FIFO lot matching for tax reporting |
-| `ibctl probe` | Probe the API and show per-account data counts |
 
-All commands accept `--dir` to specify the ibctl directory (defaults to `.`). All holding and transaction commands accept `--base-currency` (default `USD`) to convert values to a different currency. Use `--help` on any command for detailed documentation.
+All commands accept `--dir` to specify the ibctl directory (defaults to `.`). All holding and transaction commands accept `--base-currency` (default `USD`) to convert values to a different currency. Holding commands accept `--realtime` to fetch current stock prices and FX rates from Yahoo Finance on-demand. For international symbols where IBKR and Yahoo symbols differ, add mappings to `realtime_symbols` in `ibctl.yaml`. Use `--help` on any command for detailed documentation.
 
 ## Tax Reporting
 
diff --git a/book/src/commands/holding-category-list.md b/book/src/commands/holding-category-list.md
@@ -1,7 +1,7 @@
 # holding category list
 
 ```
-ibctl holding category list [--dir DIR] [--format FORMAT] [--download] [--geo GEO] [--base-currency CURRENCY]
+ibctl holding category list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--geo GEO] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by category and displays each category's market value, percentage of net liquidation value, and capital gains breakdown.
@@ -38,5 +38,6 @@ Use `--geo` to filter holdings to a single geographic classification before aggr
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
+| `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
 | `--geo` | (all) | Filter by geographic classification before aggregating (e.g., `US`, `INTL`) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |
diff --git a/book/src/commands/holding-geo-list.md b/book/src/commands/holding-geo-list.md
@@ -1,7 +1,7 @@
 # holding geo list
 
 ```
-ibctl holding geo list [--dir DIR] [--format FORMAT] [--download] [--category CATEGORY] [--base-currency CURRENCY]
+ibctl holding geo list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--category CATEGORY] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by geographic classification and displays each geo's market value, percentage of net liquidation value, and capital gains breakdown.
@@ -38,5 +38,6 @@ Use `--category` to filter holdings to a single category before aggregating by g
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
+| `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
 | `--category` | (all) | Filter by category before aggregating (e.g., `EQUITY`, `FIXED_INCOME`) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |
diff --git a/book/src/commands/holding-list.md b/book/src/commands/holding-list.md
@@ -1,7 +1,7 @@
 # holding list
 
 ```
-ibctl holding list [--dir DIR] [--format FORMAT] [--download] [--base-currency CURRENCY]
+ibctl holding list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--base-currency CURRENCY]
 ```
 
 Shows combined positions across all accounts. Positions are computed via FIFO tax lot matching with weighted average cost basis, then verified against IBKR-reported positions.
@@ -62,11 +62,18 @@ The command verifies computed positions against IBKR-reported positions and logs
 
 Unmatched sells (where the buy occurred before the data window) are also logged as warnings.
 
+## Real-time pricing
+
+Use `--realtime` to fetch current market prices and FX rates from Yahoo Finance on-demand, without downloading or persisting data. This is useful for intraday portfolio monitoring. Symbols that Yahoo cannot resolve (bonds, unmapped international tickers) fall back to cached IBKR prices with a warning.
+
+For international symbols where IBKR and Yahoo Finance symbols differ (e.g., Canadian equities), add symbol mappings to the `realtime_symbols` section of your config. Real-time data is not cached — each run fetches fresh prices from Yahoo Finance.
+
 ## Flags
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
+| `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |
diff --git a/book/src/commands/holding-lot-list.md b/book/src/commands/holding-lot-list.md
@@ -1,7 +1,7 @@
 # holding lot list
 
 ```
-ibctl holding lot list [--dir DIR] [--format FORMAT] [--download] [--symbol SYMBOL] [--base-currency CURRENCY]
+ibctl holding lot list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--symbol SYMBOL] [--base-currency CURRENCY]
 ```
 
 Lists individual FIFO tax lots. Unlike `holding list`, which aggregates positions by symbol, this command shows each tax lot separately with its own open date, quantity, and cost basis.
@@ -51,5 +51,6 @@ The table output includes a totals row summing P&L {BASE}, STCG {BASE}, LTCG {BA
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
+| `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
 | `--symbol` | (all) | Filter to a specific symbol. Omit to show all symbols. |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |
diff --git a/book/src/commands/holding-value.md b/book/src/commands/holding-value.md
@@ -1,7 +1,7 @@
 # holding value
 
 ```
-ibctl holding value [--dir DIR] [--download] [--base-currency CURRENCY]
+ibctl holding value [--dir DIR] [--download] [--realtime] [--base-currency CURRENCY]
 ```
 
 Displays the total portfolio value, unrealized short-term and long-term capital gains, estimated tax liability, and after-tax portfolio value.
@@ -54,4 +54,5 @@ Tax-exempt holdings (RRSP, TFSA, additions with `tax_exempt: true`) contribute z
 |------|---------|-------------|
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--download` | `false` | Download fresh data before displaying |
+| `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |
diff --git a/book/src/configuration.md b/book/src/configuration.md
@@ -68,6 +68,13 @@ additions:
     quantity: "100"
     last_price: "115.30"
     tax_exempt: true
+
+# Symbol mapping for real-time quote lookups.
+# Optional. Maps IBKR symbols to Yahoo Finance symbols for international tickers
+# where symbols differ. Only used with the --realtime flag.
+realtime_symbols:
+  BRK B: BRK-B
+  "700": "0700.HK"
 ```
 
 ## Field Reference
@@ -137,3 +144,14 @@ If not set, both rates default to zero and the `holding value` command shows no
 | `quantity` | Quantity as a decimal string | Yes |
 | `last_price` | Most recent market price as a decimal string (fallback when no IBKR position exists) | Yes |
 | `tax_exempt` | Whether this trade is in a tax-sheltered account (TFSA, RRSP). When true, P&L, STCG, and LTCG are shown as zero in all output. | No (default: `false`) |
+
+### `realtime_symbols`
+
+**Optional.** A mapping from IBKR ticker symbols to Yahoo Finance symbols, used by the `--realtime` flag on holding commands. Only needed for international tickers where IBKR and Yahoo Finance use different symbols (e.g., Canadian equities, Hong Kong stocks).
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Key (IBKR symbol) | The ticker symbol as reported by IBKR | `BRK B`, `700` |
+| Value (Yahoo symbol) | The equivalent symbol on Yahoo Finance | `BRK-B`, `0700.HK` |
+
+US-listed securities typically need no mapping. If a symbol is not mapped and Yahoo Finance cannot resolve the IBKR symbol, the command logs a warning and falls back to the cached IBKR price for that symbol.
diff --git a/book/src/quickstart.md b/book/src/quickstart.md
@@ -56,6 +56,12 @@ View holdings in CAD instead of the default USD:
 ibctl holding list --base-currency CAD
 ```
 
+View holdings with real-time prices from Yahoo Finance:
+
+```bash
+ibctl holding list --realtime
+```
+
 View all transactions for a tax year:
 
 ```bash
diff --git a/cmd/ibctl/internal/command/holding/category/categorylist/categorylist.go b/cmd/ibctl/internal/command/holding/category/categorylist/categorylist.go
@@ -21,6 +21,7 @@ import (
 	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
 	"github.com/bufdev/ibctl/internal/ibctl/ibctlrealtime"
 	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
 	"github.com/spf13/pflag"
 )
 
@@ -51,7 +52,10 @@ config are grouped as "UNCATEGORIZED". Sorted by market value descending.
 
 Use --geo to filter to a single geographic classification before
 aggregating. For example, --geo US shows only US holdings grouped by
-category. The --geo flag is case-insensitive.`,
+category. The --geo flag is case-insensitive.
+
+Use --realtime to fetch current stock prices and FX rates from Yahoo Finance
+for real-time category breakdowns.`,
 		Args: appcmd.NoArgs,
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appext.Container) error {
@@ -134,7 +138,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	// Override market prices and FX rates with real-time data from Yahoo Finance.
 	if flags.Realtime {
 		todayDate := time.Now().Format("2006-01-02")
-		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
 			return err
 		}
 	}
diff --git a/cmd/ibctl/internal/command/holding/geo/geolist/geolist.go b/cmd/ibctl/internal/command/holding/geo/geolist/geolist.go
@@ -21,6 +21,7 @@ import (
 	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
 	"github.com/bufdev/ibctl/internal/ibctl/ibctlrealtime"
 	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
 	"github.com/spf13/pflag"
 )
 
@@ -52,7 +53,10 @@ descending.
 
 Use --category to filter to a single asset category before aggregating.
 For example, --category EQUITY shows only equity holdings grouped by geo.
-The --category flag is case-insensitive.`,
+The --category flag is case-insensitive.
+
+Use --realtime to fetch current stock prices and FX rates from Yahoo Finance
+for real-time geographic breakdowns.`,
 		Args: appcmd.NoArgs,
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appext.Container) error {
@@ -135,7 +139,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	// Override market prices and FX rates with real-time data from Yahoo Finance.
 	if flags.Realtime {
 		todayDate := time.Now().Format("2006-01-02")
-		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
 			return err
 		}
 	}
diff --git a/cmd/ibctl/internal/command/holding/holdinglist/holdinglist.go b/cmd/ibctl/internal/command/holding/holdinglist/holdinglist.go
@@ -24,6 +24,7 @@ import (
 	"github.com/bufdev/ibctl/internal/pkg/cliio"
 	"github.com/bufdev/ibctl/internal/pkg/mathpb"
 	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
 	"github.com/spf13/pflag"
 )
 
@@ -81,6 +82,12 @@ Manual cash adjustments from the config are folded into the cash totals.
 Tax-exempt lots (from additions with tax_exempt: true) have zero P&L,
 STCG, and LTCG. Their market value is still included.
 
+Use --realtime to fetch current stock prices and FX rates from Yahoo Finance
+for intraday portfolio monitoring. Symbols that Yahoo cannot resolve (bonds,
+unmapped international tickers) fall back to cached IBKR prices with a warning.
+Use realtime_symbols in ibctl.yaml to map IBKR symbols to Yahoo symbols for
+international tickers where symbols differ (e.g., BRK B → BRK-B).
+
 Computed positions are verified against IBKR-reported positions. Quantity
 mismatches and cost basis discrepancies above 0.1% are logged as warnings.`,
 		Args: appcmd.NoArgs,
@@ -164,7 +171,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	// Override market prices and FX rates with real-time data from Yahoo Finance.
 	if flags.Realtime {
 		todayDate := time.Now().Format("2006-01-02")
-		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
 			return err
 		}
 	}
diff --git a/cmd/ibctl/internal/command/holding/holdingvalue/holdingvalue.go b/cmd/ibctl/internal/command/holding/holdingvalue/holdingvalue.go
@@ -25,6 +25,7 @@ import (
 	"github.com/bufdev/ibctl/internal/pkg/cliio"
 	"github.com/bufdev/ibctl/internal/pkg/mathpb"
 	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
 	"github.com/spf13/pflag"
 )
 
@@ -58,7 +59,10 @@ The computation is:
 
 Tax-exempt holdings (from additions with tax_exempt: true) have zero
 STCG and LTCG, so they do not contribute to the estimated tax.
-Losses reduce the tax estimate (can be negative).`,
+Losses reduce the tax estimate (can be negative).
+
+Use --realtime to fetch current stock prices and FX rates from Yahoo Finance
+for an intraday portfolio valuation with real-time tax impact estimates.`,
 		Args: appcmd.NoArgs,
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appext.Container) error {
@@ -131,7 +135,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	// Override market prices and FX rates with real-time data from Yahoo Finance.
 	if flags.Realtime {
 		todayDate := time.Now().Format("2006-01-02")
-		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
 			return err
 		}
 	}
diff --git a/cmd/ibctl/internal/command/holding/lot/lotlist/lotlist.go b/cmd/ibctl/internal/command/holding/lot/lotlist/lotlist.go
@@ -22,6 +22,7 @@ import (
 	"github.com/bufdev/ibctl/internal/ibctl/ibctlrealtime"
 	"github.com/bufdev/ibctl/internal/pkg/cliio"
 	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
 	"github.com/spf13/pflag"
 )
 
@@ -60,7 +61,10 @@ STCG = 0, LTCG = 0 in all currencies. Market value is still displayed.
 
 STCG/LTCG is classified per lot based on the lot's open date to today:
   - Held < 365 days: entire lot P&L is STCG
-  - Held >= 365 days: entire lot P&L is LTCG`,
+  - Held >= 365 days: entire lot P&L is LTCG
+
+Use --realtime to fetch current stock prices and FX rates from Yahoo Finance
+for real-time per-lot P&L tracking.`,
 		Args: appcmd.NoArgs,
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appext.Container) error {
@@ -144,7 +148,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	// Override market prices and FX rates with real-time data from Yahoo Finance.
 	if flags.Realtime {
 		todayDate := time.Now().Format("2006-01-02")
-		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
 			return err
 		}
 	}
diff --git a/internal/ibctl/ibctlfxrates/ibctlfxrates.go b/internal/ibctl/ibctlfxrates/ibctlfxrates.go
@@ -134,8 +134,8 @@ func (s *Store) OverrideLatestRates(todayDate string, pairRatesMicros map[string
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	for pairKey, rateMicros := range pairRatesMicros {
-		pair, loaded := s.pairs[pairKey]
-		if !loaded || pair == nil {
+		pair, found := s.pairs[pairKey]
+		if !found || pair == nil {
 			// Create a new pair entry for a pair not yet loaded from disk.
 			pair = &pairData{
 				rates: make(map[string]int64),
diff --git a/internal/ibctl/ibctlrealtime/ibctlrealtime.go b/internal/ibctl/ibctlrealtime/ibctlrealtime.go
@@ -44,17 +44,17 @@ type RealTimeData struct {
 // ApplyOverrides fetches real-time quotes and FX rates from Yahoo Finance,
 // then overrides position market prices and FX store rates in-memory.
 // The todayDate parameter should be in YYYY-MM-DD format for FX store date keying.
-// Returns an error if the API is unreachable or any symbol/FX pair cannot be resolved.
+// Returns an error if the API is unreachable.
 func ApplyOverrides(
 	ctx context.Context,
 	logger *slog.Logger,
+	yahooClient yahoofinance.Client,
 	positions []*datav1.Position,
 	fxStore *ibctlfxrates.Store,
 	config *ibctlconfig.Config,
 	baseCurrency string,
 	todayDate string,
 ) error {
-	yahooClient := yahoofinance.NewClient()
 	realTimeData, err := FetchData(ctx, logger, yahooClient, positions, config, baseCurrency)
 	if err != nil {
 		return err
diff --git a/internal/pkg/yahoofinance/yahoofinance.go b/internal/pkg/yahoofinance/yahoofinance.go
@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"sync"
 
 	mathv1 "github.com/bufdev/ibctl/internal/gen/proto/go/standard/math/v1"
@@ -47,7 +48,8 @@ type Quote struct {
 type Client interface {
 	// GetQuotes fetches current prices for the given symbols.
 	// Symbols can be equities (AAPL, SHOP.TO) or FX pairs (USDCAD=X).
-	// Returns an error if any symbol cannot be resolved or the API is unreachable.
+	// Per-symbol errors are skipped — the caller handles missing symbols
+	// via fallback to cached data.
 	GetQuotes(ctx context.Context, symbols []string) ([]Quote, error)
 }
 
@@ -98,7 +100,8 @@ func (c *client) GetQuotes(ctx context.Context, symbols []string) ([]Quote, erro
 func (c *client) getQuote(ctx context.Context, symbol string) (Quote, error) {
 	// Build the request URL for the v8 chart endpoint.
 	// The range and interval parameters are required but we only use the meta field.
-	reqURL := fmt.Sprintf("%s/%s?range=1d&interval=1d", baseURL, symbol)
+	// URL-escape the symbol to handle special characters (e.g., "=" in FX pairs like USDCAD=X).
+	reqURL := fmt.Sprintf("%s/%s?range=1d&interval=1d", baseURL, url.PathEscape(symbol))
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
 	if err != nil {
 		return Quote{}, fmt.Errorf("creating request for %s: %w", symbol, err)
@@ -133,7 +136,8 @@ func (c *client) getQuote(ctx context.Context, symbol string) (Quote, error) {
 		return Quote{}, fmt.Errorf("no market price returned for symbol %q", symbol)
 	}
 	// Convert the float64 price from the API to a Decimal proto.
-	priceStr := fmt.Sprintf("%f", meta.RegularMarketPrice)
+	// Use %g to preserve precision for small values (e.g., FX rates like JPYUSD ≈ 0.0066).
+	priceStr := fmt.Sprintf("%g", meta.RegularMarketPrice)
 	priceDecimal, err := mathpb.NewDecimal(priceStr)
 	if err != nil {
 		return Quote{}, fmt.Errorf("parsing price for %s: %w", symbol, err)
@@ -172,8 +176,6 @@ type chartMeta struct {
 	RegularMarketPrice float64 `json:"regularMarketPrice"`
 	// Currency is the currency of the price (e.g., "USD").
 	Currency string `json:"currency"`
-	// Symbol is the canonical symbol returned by Yahoo.
-	Symbol string `json:"symbol"`
 }
 
 // chartError is the error object in a Yahoo Finance chart response.
diff --git a/plans/iterative-churning-ullman.md b/plans/iterative-churning-ullman.md
diff --git a/plans/jazzy-riding-origami.md b/plans/jazzy-riding-origami.md
