Multi-functional cryptocurrency tracking application with real-time monitoring, price alarms, and interactive shell - runs entirely in your terminal
- Interactive Shell - User-friendly terminal interface with TAB auto-completion, command history, and syntax highlighting
- Live Price Tracking - Real-time cryptocurrency prices with customizable auto-refresh intervals
- Multi-Currency Support - Display prices in USD, EUR, TRY, GBP, JPY, and 20+ fiat currencies
- Smart Alarms with Currency - Set price alerts in any currency (BTC>100000 USD, ETH<2000 EUR, BTC>3000000 TRY)
- Named Alarms - Give your alarms custom names for easy identification
- One-Time & Persistent Alarms - Choose between one-time triggers or repeatable alerts
- Custom Cryptocurrency Support - Add any coin from CoinGecko's 10,000+ coins
- Persistent Storage - SQLite database for alarm management with automatic schema migration
- Beautiful UI - Rich terminal interface with ASCII art, color-coded changes, and clean tables
- Rate Limiting - Built-in API rate limit protection with automatic throttling
- Auto-Retry - Automatic retry with exponential backoff for network failures
- 24h Change - See percentage changes and price trends at a glance
- Coin Search - Search CoinGecko's database directly from the terminal
- Command History - Navigate previous commands with arrow keys
- Clean Exit - Graceful shutdown with Ctrl+C during watch returns to prompt (not exit)
- Clone or download the project:
git clone https://github.com/CS0059/crypto-tracker.git
cd crypto-tracker- Install dependencies:
pip install -r requirements.txt- Start the interactive shell:
python crypto.pyNote: The data/ directory with configuration and database files will be automatically created on first run.
Simply run without arguments to enter the interactive shell:
python crypto.py
╔═════════════════════════════════════════════════════════╗
║ ║
║ ██████╗██████╗ ██╗ ██╗██████╗ ████████╗ ██████╗ ║
║ ██╔════╝██╔══██╗╚██╗ ██╔╝██╔══██╗╚══██╔══╝██╔═══██╗ ║
║ ██║ ██████╔╝ ╚████╔╝ ██████╔╝ ██║ ██║ ██║ ║
║ ██║ ██╔══██╗ ╚██╔╝ ██╔═══╝ ██║ ██║ ██║ ║
║ ╚██████╗██║ ██║ ██║ ██║ ██║ ╚██████╔╝ ║
║ ╚═════╝╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ║
║ ║
║ ████████╗██████╗ █████╗ ██████╗██╗ ██╗ ║
║ ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██║ ██╔╝ ║
║ ██║ ██████╔╝███████║██║ █████╔╝ ║
║ ██║ ██╔══██╗██╔══██║██║ ██╔═██╗ ║
║ ██║ ██║ ██║██║ ██║╚██████╗██║ ██╗ ║
║ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ║
║ ║
╚═════════════════════════════════════════════════════════╝
crypto-tracker> _- ✅ Auto-completion: Press
TABto complete commands, symbols, and flags - ✅ Command history: Use
↑and↓arrows to browse previous commands - ✅ Syntax highlighting: Commands are color-coded for better readability
- ✅ Persistent session: Stay in the app and run multiple commands
- ✅ Ctrl+C handling: Press Ctrl+C during
watchto return to prompt (not exit)
crypto-tracker> help # Show all commands with descriptions
crypto-tracker> health # Check API connectivity status
# Live Price Tracking
crypto-tracker> watch BTC # Track Bitcoin in real-time
crypto-tracker> watch BTC,ETH -c EUR -i 10 # Multi-currency with custom interval
crypto-tracker> watch BTC,ETH,BNB -c TRY # Turkish Lira support
# Quick Price Check
crypto-tracker> snapshot BTC # Get current BTC price
crypto-tracker> snapshot BTC,ETH,SOL -c EUR # Multiple coins in EUR
# Price Alarms (with Currency Support!)
crypto-tracker> alarm add "BTC>100000" # Alert when BTC crosses $100K (default USD)
crypto-tracker> alarm add "BTC>100000 USD" # Explicit USD currency
crypto-tracker> alarm add "ETH<2000 EUR" # Alert in Euros
crypto-tracker> alarm add "BTC>3000000 TRY" # Alert in Turkish Lira
crypto-tracker> alarm add "SOL>200" --once # One-time alarm (triggers once)
crypto-tracker> alarm add "BTC<40000" --name Alert # Named alarm for easy identification
crypto-tracker> alarm list # Show all active alarms
crypto-tracker> alarm list --all # Show all (including inactive)
crypto-tracker> alarm remove 1 # Remove alarm by ID
crypto-tracker> alarm clear --yes # Remove all alarms
crypto-tracker> alarm activate 1 # Reactivate deactivated alarm
# Custom Cryptocurrency Management
crypto-tracker> searchcoin pepe # Search CoinGecko for coin ID
crypto-tracker> addcoin PEPE pepe # Add PEPE to your coin list
crypto-tracker> listcoins # Show all supported coins (default + custom)
crypto-tracker> removecoin PEPE # Remove custom coin
# Utility Commands
crypto-tracker> clear # Clear terminal screen
crypto-tracker> history # Show command history
crypto-tracker> exit / quit # Exit application (or Ctrl+D)You can still run commands directly without entering interactive mode:
Track cryptocurrency prices in real-time:
# Watch Bitcoin
python crypto.py watch BTC
# Watch multiple cryptos
python crypto.py watch BTC,ETH,BNB
# With custom currency and interval
python crypto.py watch BTC -c EUR -i 10
# Watch with Turkish Lira
python crypto.py watch BTC,ETH -c TRYOptions:
- First argument: Crypto symbols (BTC or BTC,ETH,BNB)
-c, --currency: Display currency (default: USD)-i, --interval: Update interval in seconds (default: 5)-a, --alarm: Add price alarm--once: Alarms trigger only once--db: Database file for persistent alarms-v, --verbose: Verbose logging
Create price alerts in any supported currency:
# Simple alarms (uses default USD)
python crypto.py alarm add "BTC<40000"
python crypto.py alarm add "ETH>2500"
# Multi-currency alarms - NEW!
python crypto.py alarm add "BTC>100000 USD" # Alert in US Dollars
python crypto.py alarm add "ETH<2000 EUR" # Alert in Euros
python crypto.py alarm add "BTC>3000000 TRY" # Alert in Turkish Lira
python crypto.py alarm add "BNB>500 GBP" # Alert in British Pounds
# Named alarms for easy identification - NEW!
python crypto.py alarm add "BTC<30000" --name "BTC Dip Alert"
python crypto.py alarm add "ETH>5000 USD" --name "ETH Moon" --once
# One-time alarm (triggers once then auto-deactivates)
python crypto.py alarm add "BTC<30000" --once
# Custom database location (will be created in data/ directory)
python crypto.py alarm add "BTC<30000" --db data/my_alarms.dbAlarm Features:
- Multi-Currency: Set alarms in USD, EUR, TRY, GBP, JPY, and more!
- Named Alarms: Use
--nameto give your alarms descriptive names - One-Time Alerts: Use
--onceflag to trigger alarm only once - Persistent: Alarms survive app restarts (stored in SQLite)
- Reusable: Persistent alarms trigger multiple times until deactivated
Combine live tracking with alarms:
# Watch BTC with multiple alarms
python crypto.py watch BTC -a "BTC<30000" -a "BTC>50000"
# Watch with persistent storage in data/ directory
python crypto.py watch BTC -a "BTC<30000" --once --db data/alarms.dbView all configured alarms:
# Show active alarms
python crypto.py alarm list
# Show all alarms (including inactive)
python crypto.py alarm list --allDelete alarms by ID:
# Remove specific alarm
python crypto.py alarm remove 1
# Remove all alarms
python crypto.py alarm clear
# Remove all without confirmation
python crypto.py alarm clear --yes# Reactivate an inactive alarm
python crypto.py alarm activate 1Get current prices without live tracking:
# Get BTC price
python crypto.py snapshot BTC
# Multiple cryptos with custom currency
python crypto.py snapshot BTC,ETH,BNB -c EURCheck API connectivity:
python crypto.py healthpython crypto.py version# Watch Bitcoin
python crypto.py watch BTC
# Watch multiple with Turkish Lira
python crypto.py watch BTC,ETH,BNB -c TRY
# Fast updates (1 second)
python crypto.py watch BTC -i 1
# With alarms
python crypto.py watch BTC -a "BTC<100000" -a "BTC>110000"
# Quick price check
python crypto.py snapshot BTC,ETHThe tracker supports 50+ major cryptocurrencies including:
| Symbol | Name | Symbol | Name | Symbol | Name |
|---|---|---|---|---|---|
| BTC | Bitcoin | ETH | Ethereum | BNB | Binance Coin |
| XRP | Ripple | ADA | Cardano | DOGE | Dogecoin |
| SOL | Solana | DOT | Polkadot | MATIC | Polygon |
| LTC | Litecoin | AVAX | Avalanche | LINK | Chainlink |
| UNI | Uniswap | ATOM | Cosmos | XMR | Monero |
[See full list in core/utils.py]
USD, EUR, GBP, JPY, CNY, KRW, TRY, RUB, AUD, CAD, CHF, HKD, SGD, INR, BRL, ZAR, MXN, AED, SAR, IDR, THB, VND, PHP, MYR
Edit data/config.json to customize default settings:
{
"default_fiat": ["USD"],
"default_interval": 5,
"api": {
"coingecko": {
"base_url": "https://api.coingecko.com/api/v3",
"rate_limit_per_minute": 50,
"timeout": 10,
"retry_attempts": 3
}
},
"alarms": {
"default_once": false,
"beep_on_trigger": true
}
}Note: Configuration file is now located in the data/ directory for better organization.
crypto_tracker/
├── crypto.py # Main CLI entrypoint
├── requirements.txt # Python dependencies
├── pytest.ini # Pytest configuration
├── LICENSE # MIT License
├── README.md # This file
├── EXAMPLES.md # Detailed usage examples
├── .gitignore # Git ignore rules
├── core/ # Core application modules
│ ├── __init__.py # Package initialization
│ ├── alarms.py # Alarm system and notification logic
│ ├── api_client.py # CoinGecko & ExchangeRate API client
│ ├── coin_manager.py # Custom cryptocurrency management
│ ├── command_parser.py # Interactive shell command parser
│ ├── error_handler.py # Unified error handling and formatting
│ ├── shell.py # Interactive shell with TAB completion
│ ├── storage.py # SQLite database wrapper
│ ├── tracker.py # Live price tracking and display
│ └── utils.py # Helper functions and utilities
├── data/ # Data and configuration files (gitignored)
│ ├── config.json # Application configuration
│ ├── custom_coins.json # User-added custom cryptocurrencies
│ ├── custom_coins.json.example # Template for custom coins
│ ├── alarms.db # SQLite database for alarms
│ └── crypto_tracker.db # SQLite database for app data
└── tests/ # Test suite
├── __init__.py # Test package initialization
├── test_alarms.py # Alarm system tests
├── test_api_client.py # API client tests
├── test_integration.py # End-to-end integration tests
├── test_storage.py # Database storage tests
└── test_utils.py # Utility function tests
Key Directories:
core/: All application logic and modulesdata/: Configuration files and SQLite databases (auto-created)tests/: Comprehensive test suite with 87 tests (74 unit + 13 integration)
Run the comprehensive test suite with 87 tests:
# Run all tests (74 unit + 13 integration)
pytest
# Run only unit tests (skip network-dependent tests)
pytest -m "not integration"
# Run with coverage report
pytest --cov=core
# Run specific test file
pytest tests/test_alarms.py
# Skip integration tests (require network)
pytest -m "not integration"
# Verbose output with detailed assertions
pytest -v
# Run integration tests separately
pytest tests/test_integration.py -vTest Statistics:
- ✅ 87 Total Tests: 74 unit tests + 13 integration tests
- ✅ 100% Pass Rate: All tests passing
- ✅ Coverage: Core modules fully tested
- ✅ CI Ready: Pytest configuration included
- Cryptocurrency Prices: CoinGecko API (Free, no API key required)
- Fiat Exchange Rates: ExchangeRate-API (Free, no API key required)
Rate Limits:
- CoinGecko: 50 requests/minute (free tier)
- Built-in rate limiter prevents exceeding limits
- Auto-retry with exponential backoff on failures
Cryptocurrency Prices
┏━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Symbol ┃ USD ┃ 24h % ┃ EUR ┃ 24h % ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ BTC │ 50,234.56 │ +5.23% │ 42,699.38 │ +4.87% │
│ ETH │ 3,012.45 │ -2.15% │ 2,560.59 │ -2.48% │
│ BNB │ 345.67 │ +1.05% │ 293.82 │ +0.72% │
└────────┴───────────────┴────────────┴───────────────┴────────────┘
🚨 ALARM TRIGGERED
ALARM — BTC price 29,900.00 USD < 30,000.00
Last update: 14:23:45 | Interval: 5s | Active alarms: 2
You can now add any cryptocurrency from CoinGecko's 10,000+ coins without editing code:
# Interactive mode (recommended)
crypto-tracker> searchcoin pepe # Search for coin ID
crypto-tracker> addcoin PEPE pepe # Add PEPE to your list
crypto-tracker> listcoins # View all coins (default + custom)
crypto-tracker> watch PEPE -c USD # Start tracking PEPE
crypto-tracker> removecoin PEPE # Remove custom coin
# Direct mode
python crypto.py searchcoin pepe
python crypto.py addcoin PEPE pepe
python crypto.py listcoinsCustom coins are:
- ✅ Stored in
data/custom_coins.jsonfile - ✅ Automatically loaded on app start
- ✅ Available in TAB auto-completion after adding
- ✅ Usable in
watch,snapshot, andalarmcommands - ✅ Persisted across sessions
Finding CoinGecko IDs:
- Use
searchcoin <name>command (recommended) - Or visit: https://api.coingecko.com/api/v3/coins/list
Alarm rules now support currencies and two operators:
<: Trigger when price drops below threshold>: Trigger when price rises above threshold
Format: SYMBOL<VALUE [CURRENCY] or SYMBOL>VALUE [CURRENCY]
Examples:
BTC>100000- Alert when Bitcoin crosses $100K (default USD)BTC>100000 USD- Explicit USDETH<2000 EUR- Alert when Ethereum drops below €2,000BTC>3000000 TRY- Alert when Bitcoin crosses ₺3,000,000SOL>200 GBP- Alert when Solana crosses £200
Data Storage:
- All databases and user files are in the
data/directory - The
data/directory is gitignored (except.examplefiles) - Safe to delete
data/*.dbfiles to reset all alarms and settings
- ✅ No API Keys Required: Both APIs are free and public
- ✅ No Personal Data: No user information collected or transmitted
- ✅ Local Storage Only: All data stored in local SQLite databases
- ✅ No Tracking: No analytics, telemetry, or external data sharing
- ✅ Gitignored Data: User data files automatically excluded from version control
- ✅ Open Source: Full code transparency and auditability
The tracker includes comprehensive error handling:
- Network Errors: Automatic retry with exponential backoff
- API Rate Limits: Built-in rate limiter with wait times
- Invalid Symbols: Validation and warning messages
- Offline Mode: Uses cached data when API is unavailable
- CoinGecko - Cryptocurrency data API
- Rich - Beautiful terminal formatting
- Typer - CLI framework
- Prompt Toolkit - Interactive shell features
MIT License - See LICENSE file for details
Happy Tracking!