Broker API pulls are an allowed source artefact for Portfolio holdings

Decision

Portfolio may source holdings/trades from a direct broker API pull (Kite Connect, Dhan, Upstox, Angel One) in addition to uploaded statements, provided every API pull is persisted as its own immutable, timestamped source artefact — raw response body, provider name, linked account, and fetch time — so each resulting ledger row still traces to a concrete source the way an uploaded PDF/CSV does today. Nothing about this proposal permits a user-typed figure anywhere: the artefact is machine-fetched, not hand-entered, so it is not "manual entry" in the sense no-manual-entry forbids. Scope is narrow and Portfolio-only — Tax, Expense, Inbox, and the CA marketplace are untouched. If adopted, this amends the "no broker API" bullet in portfolio-pillar and carves a documented, source-artefact-preserving exception into upload-only and no-manual-entry — it does not repeal either principle.

Why

Two independent threads converged on this in the same session:

1. Cost/feasibility research: Kite Connect's order/portfolio APIs are free since March 2025 (₹500/month only buys live market data, which Portfolio doesn't need); Dhan, Upstox, and Angel One APIs are free outright. A direct pull is a zero-marginal-cost data-quality upgrade over parsing broker PDFs/XLSX exports.
2. Product risk: parser failure rate (<4%) is a tracked V1 launch-gate KPI, and a real bug found this session (2026-08-07-broker-holdings-statement) shows how fragile broker-statement parsing can be in practice — one user's real ~₹25L portfolio was invisible on Portfolio until a misclassified document type was fixed. A verified API response removes an entire failure class (OCR/layout parsing errors) for the brokers it covers.

The current "no broker API" rule is stated only as a structural corollary of upload-only/no-manual-entry, whose actual documented rationale is source-artefact traceability for IT-scrutiny/DPDP audits and product-scope containment — not a broker-specific security, KYC, or cost concern (none of those are recorded anywhere in the wiki as reasons). This proposal targets that literal rationale: it keeps every ledger row backed by a concrete, immutable, inspectable source artefact; it just adds "API response snapshot" as a second artefact kind alongside "uploaded document."

Impact

If accepted, this touches:

• portfolio-pillar — amend the "Holdings come from parsed statements only... no broker API" bullet to reference this decision and describe the artefact-preserving exception.
• upload-only — note the narrow Portfolio-only carve-out; the core claim ("every fact traces to a source artefact") is preserved, not weakened.
• no-manual-entry — same: note that API-sourced data is machine-fetched, not user-typed, so it doesn't reintroduce the failure mode the ban exists to prevent.
• New packages/brokers package (not yet created) — one self-contained folder per broker (zerodha/, dhan/, upstox/, angel-one/), each with its own client/mapper/index, following the exact convention packages/parser already uses for its 36 independent per-format folders (self-contained folder, own index.ts barrel, aggregated by one root barrel — no precedent in this repo for splitting integrations of this shape across multiple packages/* workspaces).
• New source-artefact type in packages/shared schemas, parallel to "uploaded document," to store the raw API response + provider + account + fetch timestamp.
• A new Inbox-adjacent ingestion path in apps/functions/src/portfolio for API-sourced snapshots (mapping broker SDK responses into portfolio_holdings/portfolio_positions, reusing the plural mapper pattern from 2026-08-07-broker-holdings-statement).
• Not addressed by this proposal: which brokers to launch with, UI for linking a broker account, credential storage/rotation, and whether this ships in V2 or V3 — all deferred to a follow-up /plan-change once this decision is accepted.

Status

Active. portfolio-pillar, upload-only, no-manual-entry, and read-only-review have been amended to reference this exception. (read-only-review was missed in the initial amendment pass and fixed on the same day — its "no broker API" implication is about never acting on a broker, so a read-only holdings pull doesn't cross that line, same reasoning as the other three.)

Sources

• No .context/raw/ file exists for this — it originates from a chat session researching open-source finance-app prior art (Securo, Firefly III, Ghostfolio) and Indian broker API pricing, not a raw document. Session context only.
• Prior related decision: 2026-05-30-v1-upload-only
• Related decision showing broker-statement fragility: 2026-08-07-broker-holdings-statement