patan4ik/kraken-portfolio-tracker

Purpose and Entrypoints

Kraken Portfolio Tracker is a Python 3.11+ CLI application for fetching Kraken account data, persisting it locally, and generating offline portfolio and ledger analysis. Primary entrypoints are start.py for setup/basic refresh and update.py for validated incremental ledger updates plus downstream recomputation. Report modules can also be invoked directly under src/.

Kraken Access and Credential Boundary

src/api.py encapsulates interaction with the external Kraken API for live balances, prices, and ledger retrieval. Credentials are resolved separately by src/keys.py, supporting system keyring, local key file, or environment variables. src/config.py centralizes runtime locations/settings, keeping API secrets and provider access outside analytical modules.

Ledger Ingestion and Durable Cache

src/ledger_loader.py incrementally downloads Kraken ledger pages/date ranges and maintains the raw local ledger cache. src/storage.py is the persistence boundary: SQLite holds normalized/full ledger payloads in balances_history/ledger.db, while JSON and CSV files support caching and exports. The intended steady-state reporting path is SQLite, not live API calls.

Balance Snapshot Pipeline

src/balances.py obtains current balances and prices, aggregates available and staked holdings, and writes daily portfolio snapshots/history. This live-data path feeds reconciliation and complements the historical ledger database; it is distinct from ledger-derived cost-basis calculation.

Update Orchestration and Validation

update.py plans missing ledger date ranges, supports dry runs and paging/rate-delay controls, then coordinates ingestion, balance refresh, summary generation, and reconciliation. src/validators.py performs preflight validation of database/schema/API-key conditions before mutation. start.py provides the simpler initial workflow, key setup, snapshot refresh, and optional ledger update.

Portfolio Analytics and Reconciliation

src/portfolio_summary.py recomputes FIFO/average cost basis from the complete stored ledger each run, normalizing Kraken wallet suffixes and excluding internal transfers. It also derives EMA/trend-based forecasts. src/balance_reconciliation.py compares ledger-derived holdings with the current balance snapshot and writes tolerance-based mismatch results. Core outputs are materialized as local CSV artifacts rather than served over a network.

Report Generation

SQLite-backed reporting is partitioned by analysis use case: EUR spend aggregation in src/ledger_eur_report.py, acquisitions in src/ledger_asset_report.py, and disposals/proceeds/fees in src/ledger_sell_report.py. src/portfolio_summary_report.py converts computed portfolio metrics into enriched sell-target, trend, risk, and signal CSV output.

Runtime and Delivery

The runtime is local Python with SQLite, filesystem CSV/JSON caches, optional OS credential keyring, and the Kraken API as the sole stated external service. GitHub Actions workflows under .github/workflows/ provide CI. Windows distribution packages start.py and update.py as PyInstaller executables; no web server or hosted application infrastructure is indicated.