CryptoFolio - Personal Crypto Portfolio Tracker

A Python-based cryptocurrency portfolio tracker that fetches live token prices via CoinGecko API and calculates portfolio returns.

Overview

This tool helps you track your cryptocurrency investments by:

• Fetching real-time prices from CoinGecko API
• Calculating current portfolio value
• Computing profit/loss for each holding
• Displaying overall portfolio performance

Features

• Live Price Tracking: Real-time cryptocurrency prices via CoinGecko API
• Portfolio Analysis: Calculate returns, profit/loss, and ROI
• Multi-Asset Support: Track multiple cryptocurrencies in one portfolio
• CLI Interface: Professional command-line interface with argparse
• CSV Export: Export portfolio data to CSV for further analysis
• JSON-Based Storage: Easy to edit portfolio holdings
• Input Validation: Validates portfolio data structure and values
• Retry Logic: Exponential backoff for transient API failures
• Logging System: Proper logging with configurable verbosity
• Type Hints: Full type annotations throughout

Tech Stack

• Language: Python 3.8+
• API: CoinGecko API (free tier)
• Libraries:
  • requests - HTTP requests to CoinGecko API
  • pandas - Data manipulation and display
  • pyarrow - Enhanced pandas performance and future compatibility

Project Structure

cryptofolio/
├── crypto_tracker.py        # Main script
├── portfolio.json           # Portfolio data (gitignored)
├── portfolio.example.json   # Example portfolio template
├── requirements.txt         # Python dependencies (pinned versions)
├── pyproject.toml          # Modern Python packaging configuration
├── README.md               # Project overview
├── USAGE.md                # Detailed usage instructions
├── CHANGELOG.md            # Version history
├── CONTRIBUTING.md         # Contribution guidelines
├── LICENSE                 # MIT License
└── .gitignore              # Git ignore rules

Quick Start

1. Clone the repository:

   git clone https://github.com/winthrop1/cryptofolio.git
   cd cryptofolio

2. Install dependencies:

   pip install -r requirements.txt

3. Create your portfolio:

   cp portfolio.example.json portfolio.json
   # Edit portfolio.json with your holdings

4. Run the tracker:

   # Basic usage
   python crypto_tracker.py
   
   # With custom portfolio file
   python crypto_tracker.py -f my_portfolio.json
   
   # With verbose logging
   python crypto_tracker.py -v
   
   # Export to CSV
   python crypto_tracker.py --csv output.csv
   
   # Show help
   python crypto_tracker.py --help

Sample Output

================================================================================
CRYPTO PORTFOLIO TRACKER
================================================================================

Symbol  Amount  Purchase Price  Current Price  Initial Value  Current Value  Profit/Loss  Return %
BTC     0.5     $30,000.00     $45,000.00     $15,000.00    $22,500.00     $7,500.00    50.00%
ETH     2.0     $1,800.00      $2,500.00      $3,600.00     $5,000.00      $1,400.00    38.89%
ADA     1000    $0.50          $0.65          $500.00       $650.00        $150.00      30.00%

--------------------------------------------------------------------------------
TOTAL PORTFOLIO VALUE:    $28,150.00
TOTAL INITIAL INVESTMENT: $19,100.00
TOTAL PROFIT/LOSS:        $9,050.00
TOTAL RETURN:             47.38%
================================================================================

API Information

This tool uses the CoinGecko API (free tier):

• No API key required
• Rate limit: ~50 calls/minute
• Provides real-time cryptocurrency prices

Learning Objectives

This project demonstrates:

• API integration and HTTP requests
• JSON data handling
• Financial calculations (ROI, P&L)
• Data presentation with pandas
• Clean code structure and documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Future Improvements

Potential enhancements:

• Historical price tracking and charts
• Price alerts and notifications
• Multiple portfolio support
• Transaction history tracking
• Web dashboard interface
• Database integration (PostgreSQL/MongoDB)
• Tax reporting and cost basis tracking
• Support for more exchanges beyond CoinGecko

License

MIT License - see LICENSE file for details.

Acknowledgments

• CoinGecko API for cryptocurrency price data
• Built as a portfolio project to demonstrate Python development best practices

---

Note: This is a portfolio/educational project. Always verify cryptocurrency prices from multiple sources before making financial decisions.