🔐 CryptoVault API — Personal Crypto Portfolio Tracker

A production-ready REST API for real-time crypto portfolio tracking. JWT authentication, live prices via CoinGecko, PnL analytics, and full CRUD for portfolios, holdings & transactions — built with FastAPI + PostgreSQL.

---

🔍 What is This?

CryptoVault API is a production-ready personal crypto portfolio tracker REST API built entirely in Python. It provides secure JWT authentication, full CRUD for portfolios and holdings, transaction history logging, real-time prices from CoinGecko, and PnL analytics — all via a clean, predictable REST surface.

This is the second major project of the Web3 Python Toolkit by @rizalcodes.

---

✨ Features

#	Feature	Description
1	🔐 JWT Authentication	Secure register, login, access & refresh tokens via python-jose
2	📁 Portfolio Management	Create and manage multiple crypto portfolios per user
3	💎 Holdings Tracker	Track crypto assets with quantity and average buy price
4	📊 Transaction History	Log every buy/sell with auto-calculated total value
5	💰 Live Prices	Real-time prices, 24h change, market cap via CoinGecko API
6	📈 PnL Analytics	Full portfolio analytics — invested vs current value, profit/loss per holding

---

🚀 Quick Start

1. Clone the repo

git clone https://github.com/rizalcodes/cryptovault-api.git
cd cryptovault-api

2. Create virtual environment

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

Create a .env file in the root directory:

DATABASE_URL=postgresql://username:password@localhost:5432/cryptovault
SECRET_KEY=your-super-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

5. Run the API

uvicorn main:app --reload

6. Open docs

http://127.0.0.1:8000/docs

---

📡 API Endpoints

🔐 Authentication

Method	Endpoint	Description
POST	/auth/register	Register new user
POST	/auth/login	Login + get JWT tokens
GET	/auth/me	Get current user profile

📁 Portfolios

Method	Endpoint	Description
POST	/portfolios/	Create new portfolio
GET	/portfolios/	List all portfolios
GET	/portfolios/{id}	Get single portfolio
PUT	/portfolios/{id}	Update portfolio
DELETE	/portfolios/{id}	Delete portfolio

💎 Holdings

Method	Endpoint	Description
POST	/portfolios/{id}/holdings	Add holding to portfolio
GET	/portfolios/{id}/holdings	List all holdings
GET	/portfolios/{id}/holdings/{holding_id}	Get single holding
PUT	/portfolios/{id}/holdings/{holding_id}	Update holding
DELETE	/portfolios/{id}/holdings/{holding_id}	Delete holding

📊 Transactions

Method	Endpoint	Description
POST	/transactions/	Log new transaction
GET	/transactions/	List all transactions
GET	/transactions/{id}	Get single transaction
GET	/transactions/holding/{id}	Transactions by holding
DELETE	/transactions/{id}	Delete transaction

💰 Live Prices

Method	Endpoint	Description
GET	/prices/{coin_id}	Live price for single coin
GET	/prices/?coins=bitcoin,ethereum	Live prices for multiple coins

📈 Analytics

Method	Endpoint	Description
GET	/analytics/{portfolio_id}	Full PnL analytics for portfolio

---

📊 Analytics Response Example

{
    "portfolio_id": 1,
    "portfolio_name": "My Crypto Portfolio",
    "total_invested": 30000.0,
    "current_value": 32546.5,
    "total_pnl": 2546.5,
    "total_pnl_percentage": 8.49,
    "holdings": [
        {
            "coin_id": "bitcoin",
            "coin_symbol": "BTC",
            "coin_name": "Bitcoin",
            "quantity": 0.5,
            "average_buy_price": 60000.0,
            "current_price": 65093.0,
            "total_invested": 30000.0,
            "current_value": 32546.5,
            "pnl": 2546.5,
            "pnl_percentage": 8.49
        }
    ]
}

---

🏗️ Project Structure

cryptovault-api/
├── app/
│   ├── models/
│   │   ├── user.py          → User model
│   │   ├── portfolio.py     → Portfolio model
│   │   ├── holding.py       → Holding model
│   │   └── transaction.py   → Transaction model
│   ├── routers/
│   │   ├── auth.py          → JWT auth endpoints
│   │   ├── portfolios.py    → Portfolio CRUD
│   │   ├── holdings.py      → Holdings CRUD
│   │   ├── transactions.py  → Transaction history
│   │   ├── prices.py        → CoinGecko live prices
│   │   └── analytics.py     → PnL analytics
│   ├── schemas/
│   │   ├── user.py          → User schemas
│   │   ├── portfolio.py     → Portfolio schemas
│   │   ├── holding.py       → Holding schemas
│   │   └── transaction.py   → Transaction schemas
│   ├── utils/
│   │   └── auth.py          → JWT utilities
│   └── database.py          → DB connection & session
├── main.py                  → FastAPI app entry point
├── requirements.txt         → Dependencies
├── CLAUDE.md                → AI context file
└── .env                     → Environment variables

---

📡 Data Sources

Source	Used For	Auth
CoinGecko API	Live prices, market data, 24h change	Free
PostgreSQL 16	User data, portfolios, holdings, transactions	Local/VPS

---

🔧 Requirements

fastapi
uvicorn
sqlalchemy
psycopg2-binary
python-jose[cryptography]
bcrypt
pydantic[email]
python-dotenv
requests
alembic

---

⚙️ Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string
SECRET_KEY	JWT signing secret key
ALGORITHM	JWT algorithm (HS256)
ACCESS_TOKEN_EXPIRE_MINUTES	Access token expiry
REFRESH_TOKEN_EXPIRE_DAYS	Refresh token expiry

---

🏗️ Tech Stack

Technology	Version	Purpose
FastAPI	Latest	REST API framework
PostgreSQL	16	Primary database
SQLAlchemy	Latest	ORM
python-jose	Latest	JWT tokens
bcrypt	Latest	Password hashing
Pydantic	V2	Data validation
CoinGecko API	Free	Live crypto prices
Alembic	Latest	DB migrations

---

⚠️ Disclaimer

This API is for personal portfolio tracking and educational purposes only. Nothing here constitutes financial advice. Always do your own research before making any investment decisions.

---

👤 Author

RIZAL — @rizalcodes

Building Web3 tools with Python 🐍⛓️ Follow on X: @rizalcodes_

---

📄 License

MIT License — free to use, modify, and distribute.