tracking-crypto-portfolio

# Tracking Crypto Portfolio ## Overview This skill provides comprehensive cryptocurrency portfolio tracking with: - **Real-Time Valuations**: Current prices from CoinGecko - **Holdings Breakdown**: Quantity, value, and allocation per asset - **P&L Tracking**: Unrealized gains/losses with cost basis - **Allocation Analysis**: Category breakdown and concentration flags - **Multiple Export Formats**: Table, JSON, CSV **Key Capabilities:** - Track holdings across multiple assets - Calculate portfolio total value in USD - Identify overweight positions (concentration risk) - Export for analysis tools and tax reporting ## Prerequisites Before using this skill, ensure: 1. **Python 3.8+** is installed 2. **requests** library is available: `pip install requests` 3. Internet connectivity for CoinGecko API access 4. A portfolio JSON file with your holdings ### Portfolio File Format Create a portfolio file (e.g., `holdings.json`): ```json { "name": "My Portfolio", "holdings": [ {"coin": "BTC", "quantity": 0.5, "cost_basis": 25000}, {"coin": "ETH", "quantity": 10, "cost_basis": 2000}, {"coin": "SOL", "quantity": 100} ] } ``` Fields: - `coin`: Symbol (BTC, ETH, etc.) - **required** - `quantity`: Amount held - **required** - `cost_basis`: Average purchase price per coin (optional, for P&L) - `acquired`: Date acquired (optional, for records) ## Instructions ### Step 1: Assess User Intent Determine what portfolio information the user needs: - **Quick check**: Total value and top holdings - **Holdings list**: Full breakdown of all positions - **Detailed analysis**: Allocations, P&L, risk flags - **Export**: JSON or CSV for external tools ### Step 2: Execute Portfolio Tracking Run the tracker with appropriate options: ```bash # Quick portfolio summary python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json # Full holdings breakdown python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings # Detailed analysis with P&L and allocations python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed # Export to JSON python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_export.json # Export to CSV python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output portfolio.csv ``` ### Step 3: Present Results Format and explain the portfolio data: - Show total portfolio value prominently - Highlight 24h and 7d changes - Explain allocation percentages - Flag any concentration risks - For detailed mode, explain P&L calculations ### Command-Line Options | Option | Description | Default | |--------|-------------|---------| | `--portfolio` | Path to portfolio JSON file | Required | | `--holdings` | Show all holdings breakdown | false | | `--detailed` | Full analysis with P&L | false | | `--sort` | Sort by: value, allocation, name, change | value | | `--format` | Output format (table, json, csv) | table | | `--output` | Output file path | stdout | | `--threshold` | Allocation warning threshold | 25% | | `--verbose` | Enable verbose output | false | ### Allocation Thresholds By default, positions > 25% allocation are flagged: | Allocation | Risk Level | Action | |------------|------------|--------| | < 10% | Low | Normal position | | 10-25% | Medium | Monitor closely | | 25-50% | High | Consider rebalancing | | > 50% | Very High | Significant concentration risk | ## Output ### Table Format (Default) ``` ============================================================================== CRYPTO PORTFOLIO TRACKER Updated: 2026-01-14 15:30 ============================================================================== PORTFOLIO SUMMARY: My Portfolio ------------------------------------------------------------------------------ Total Value: $125,450.00 USD 24h Change: +$2,540.50 (+2.07%) 7d Change: +$8,125.00 (+6.92%) Holdings: 8 assets TOP HOLDINGS ------------------------------------------------------------------------------ Coin Quantity Price Value Alloc 24h BTC 0.500 $95,000.00 $47,500.00 37.9% +2.5% ETH 10.000 $3,200.00 $32,000.00 25.5% +1.8% SOL 100.000 $180.00 $18,000.00 14.4% +4.2% ⚠ CONCENTRATION WARNING: BTC (37.9%) exceeds 25% threshold ============================================================================== ``` ### JSON Format ```json { "portfolio_name": "My Portfolio", "total_value_usd": 125450.00, "change_24h": {"amount": 2540.50, "percent": 2.07}, "holdings": [ { "coin": "BTC", "quantity": 0.5, "price_usd": 95000, "value_usd": 47500, "allocation_pct": 37.9, "change_24h_pct": 2.5 } ], "meta": { "timestamp": "2026-01-14T15:30:00Z", "holdings_count": 8 } } ``` ## Error Handling See `{baseDir}/references/errors.md` for comprehensive error handling. | Error | Cause | Solution | |-------|-------|----------| | Portfolio file not found | Invalid path | Check file path exists | | Invalid JSON | Malformed file | Validate JSON syntax | | Coin not found | Unknown symbol | Check symbol spelling, use standard symbols | | API rate limited | Too many requests | Wait and retry, use caching | ## Examples See `{baseDir}/references/examples.md` for detailed examples. ### Quick Examples ```bash # Basic portfolio check python {baseDir}/scripts/portfolio_tracker.py --portfolio ~/crypto/holdings.json # Show all holdings sorted by allocation python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings --sort allocation # Detailed analysis with 15% threshold python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed --threshold 15 # Export for tax software python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output tax_export.csv # JSON export for trading bot python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_data.json ``` ## Resources - **CoinGecko API**: https://www.coingecko.com/en/api - Free crypto market data - **Portfolio Schema**: See PRD.md for complete portfolio file format - **Configuration**: See `{baseDir}/config/settings.yaml` for options - See `{baseDir}/references/examples.md` for integration examples