027 Prd 681be534

PRD: Tracking Crypto Portfolio

Document Control

Executive Summary

The tracking-crypto-portfolio skill provides comprehensive cryptocurrency portfolio management with real-time valuations, performance analytics, and allocation insights. It enables users to track holdings across multiple wallets, exchanges, and chains with unified reporting.

Value Proposition: Consolidate multi-chain, multi-exchange crypto holdings into a single view with real-time valuations, P&L tracking, and allocation analysis.

Problem Statement

Current Pain Points

1. Fragmented Holdings: Assets spread across exchanges, wallets, and chains
2. Manual Tracking: Spreadsheets can't keep up with real-time prices
3. No Cost Basis: Hard to track acquisition costs and realize P&L
4. Allocation Drift: No visibility into portfolio concentration risks
5. Performance Blind Spots: Can't compare performance across assets

Impact of Not Solving

• Missed rebalancing opportunities
• Tax reporting nightmares
• Overexposure to single assets
• No clear view of actual returns
• Emotional decisions from lack of data

Target Users

Persona 1: Active Trader

• Name: Marcus
• Role: Day/swing trader
• Goals: Track positions across exchanges, monitor P&L in real-time
• Pain Points: Holdings on 5 exchanges, needs quick portfolio snapshot
• Usage: Multiple times daily, JSON export for trading bot integration

Persona 2: Long-Term Investor

• Name: Sarah
• Role: HODLer with diverse portfolio
• Goals: Track overall portfolio value, monitor allocation percentages
• Pain Points: Assets in cold wallets and exchanges, no unified view
• Usage: Weekly check-ins, detailed allocation reports

Persona 3: DeFi User

• Name: Alex
• Role: DeFi yield farmer
• Goals: Track LP positions, staking rewards, multi-chain holdings
• Pain Points: Assets across Ethereum, Arbitrum, Polygon, etc.
• Usage: Daily monitoring, export for yield calculations

User Stories

US-1: Portfolio Overview (Critical)

As a crypto investor I want to see my total portfolio value across all holdings So that I know my current net worth in crypto

Acceptance Criteria:

• Display total portfolio value in USD
• Show 24h and 7d change (absolute and percentage)
• List top holdings by value
• Complete in under 10 seconds

US-2: Holdings Breakdown (Critical)

As a portfolio manager I want to see each asset with quantity, value, and allocation So that I can monitor concentration risk

Acceptance Criteria:

• List all holdings with current prices
• Show allocation percentage per asset
• Highlight overweighted positions (>25% allocation)
• Sort by value, alphabetical, or allocation

US-3: Performance Tracking (Important)

As a trader I want to track P&L for each position So that I know which trades are profitable

Acceptance Criteria:

• Calculate unrealized P&L per holding
• Show cost basis vs current value
• Display percentage gain/loss
• Support FIFO/LIFO/average cost methods

US-4: Multi-Format Export (Important)

As a quant I want to export portfolio data in JSON format So that I can feed it into my analysis tools

Acceptance Criteria:

• JSON export with all holdings and metadata
• CSV export for spreadsheet analysis
• Include timestamps for time-series tracking
• Support custom field selection

US-5: Allocation Analysis (Nice-to-Have)

As an investor I want to see portfolio allocation by category So that I can ensure proper diversification

Acceptance Criteria:

• Group by asset type (L1, L2, DeFi, stables, etc.)
• Show pie chart or percentage breakdown
• Flag concentration risks
• Compare to target allocation

Functional Requirements

REQ-1: Holdings Management

• Add holdings manually (coin, quantity, cost basis)
• Import from JSON portfolio file
• Support for multiple portfolio files
• Track acquisition date for tax purposes

REQ-2: Real-Time Valuations

• Fetch current prices from CoinGecko API
• Calculate total value per holding
• Sum to portfolio total value
• Cache prices with configurable TTL

REQ-3: Performance Metrics

• Calculate 24h, 7d, 30d price changes
• Track unrealized P&L per position
• Support multiple cost basis methods
• Historical performance tracking (if data available)

REQ-4: Allocation Analysis

• Calculate allocation percentages
• Group by configurable categories
• Flag overweight positions
• Compare to benchmark allocations

REQ-5: Output Formatting

• Table format for terminal display
• JSON format for programmatic use
• CSV format for spreadsheet import
• Summary format for quick checks

Non-Goals

• Exchange Integration: No direct API connections to exchanges (manual entry only)
• Trading: No buy/sell execution capabilities
• Wallet Monitoring: No on-chain wallet tracking (use dedicated tools)
• Tax Calculations: Basic P&L only, not full tax reporting
• Historical Charts: Current snapshot only, not time-series visualization

Success Metrics

UX Flow

User: "show my crypto portfolio"
  │
  ├─► Load portfolio file (JSON)
  │
  ├─► Fetch current prices (CoinGecko)
  │
  ├─► Calculate valuations
  │
  ├─► Calculate allocations
  │
  ├─► Calculate P&L (if cost basis provided)
  │
  └─► Display formatted output

Integration Points

Dependencies

• market-price-tracker: For real-time price data (can work standalone)
• CoinGecko API for price fetching

Consumers

• crypto-tax-calculator: Portfolio data for tax reporting
• trading-strategy-backtester: Portfolio composition input

Data Sources

• CoinGecko API (free tier)
• User-provided portfolio JSON file

Constraints & Assumptions

Constraints

• CoinGecko free tier rate limits (~10-30 calls/minute)
• Manual portfolio entry (no exchange API sync)
• Single currency display (USD)

Assumptions

• User maintains portfolio file with accurate holdings
• Cost basis data optional but beneficial
• Network connectivity for price fetching

Risk Assessment

Examples

Example 1: Quick Portfolio Check

python portfolio_tracker.py --portfolio holdings.json

Shows portfolio summary with total value and top holdings.

Example 2: Detailed Holdings

python portfolio_tracker.py --portfolio holdings.json --detailed

Full breakdown with allocation percentages and P&L.

Example 3: JSON Export

python portfolio_tracker.py --portfolio holdings.json --format json --output portfolio.json

Export for analysis tools.

Portfolio File Format

{
  "name": "Main Portfolio",
  "holdings": [
    {
      "coin": "BTC",
      "quantity": 0.5,
      "cost_basis": 25000,
      "acquired": "2024-01-15"
    },
    {
      "coin": "ETH",
      "quantity": 10,
      "cost_basis": 2000,
      "acquired": "2024-02-01"
    }
  ]
}

Version History