aaaaqwq/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):

{
  "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:

# 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

{
  "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

# 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