💼 Portfolio Tracker

Real-time Ethereum portfolio tracker — ETH balance, ERC-20 tokens, NFT holdings & DeFi positions delivered via Telegram bot.

---

✨ Features

• 🔷 ETH Balance — real-time ETH holdings + USD value
• 🪙 ERC-20 Tokens — detect all token holdings with USD valuation
• 🖼️ NFT Holdings — track all NFTs owned by a wallet
• 🏦 DeFi Positions — Aave V3 lending/borrowing positions
• 👀 Watchlist — monitor multiple wallets with auto-refresh
• 🤖 Telegram Bot — interactive dashboard via 6 commands
• 📊 Portfolio Breakdown — ETH vs tokens vs DeFi vs NFTs

---

🚀 Quick Start

1. Install dependencies

pip install web3 requests

2. Set environment variables

# Windows PowerShell
$env:ETHERSCAN_API_KEY = "your_etherscan_api_key"
$env:INFURA_URL        = "https://mainnet.infura.io/v3/your_infura_key"
$env:TELEGRAM_TOKEN    = "your_telegram_bot_token"
$env:TELEGRAM_CHAT_ID  = "your_chat_id"

# Linux / Mac
export ETHERSCAN_API_KEY="your_etherscan_api_key"
export INFURA_URL="https://mainnet.infura.io/v3/your_infura_key"
export TELEGRAM_TOKEN="your_telegram_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

3. Run as Telegram Bot

python portfolio_tracker.py

4. Quick Analyze (one-time)

python portfolio_tracker.py analyze 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

---

🤖 Telegram Commands

Command	Description
/start	Welcome & instructions
/track <address>	Full portfolio analysis
/watch <address>	Add wallet to watchlist
/watchlist	View all watched wallets
/unwatch <address>	Remove from watchlist
/refresh	Refresh all watchlist wallets
/txs <address>	Recent transactions

Example

/track 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
/watch 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
/watchlist
/refresh

---

📊 Sample Output

💼 PORTFOLIO TRACKER
━━━━━━━━━━━━━━━━━━━━━━
👛 0xd8dA...6045
⏰ 2026-05-19T14:06:23

💰 Total Value: $12,112.08
━━━━━━━━━━━━━━━━━━━━━━
🔷 ETH
• Balance : 5.676722 ETH
• Price   : $2,133.64
• Value   : $12,112.08

🪙 Top Tokens
• USDC: 1,500.0 (~$1,500.00)
• WETH: 2.5 (~$5,334.10)

🖼️ NFTs (7079 total)
• Goldie #438
• Crownless King #5

━━━━━━━━━━━━━━━━━━━━━━
📊 Breakdown
• ETH    : $12,112.08
• Tokens : $6,834.10 (256 tokens)
• NFTs   : 7079 items

---

🏗️ Architecture

portfolio_tracker.py
├── PriceClient          → CoinGecko API (ETH + token prices)
├── EtherscanClient      → Etherscan V2 API (balances, tokens, NFTs, TXs)
├── Web3Client           → Web3.py RPC (direct blockchain connection)
├── DeFiTracker          → Aave V3 positions
├── PortfolioAnalyzer    → Core engine (combines all data sources)
├── TelegramReporter     → Format & send dashboard to Telegram
└── PortfolioBot         → Telegram bot with interactive commands

---

🔧 API Keys

Service	Get Key	Free Tier
Etherscan	etherscan.io/apis	5 req/sec
Infura	infura.io	100K req/day
CoinGecko	coingecko.com/api	Free
Telegram Bot	@BotFather	Free

---

👤 Author

Rizal — @rizalcodes

Building Web3 tools with Python 🐍⛓️

---

📄 License

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