🚀 Crypto Top 10 Analyzer (AutoSuggestStock)

A small Python app that fetches live cryptocurrency market data from CoinMarketCap, scores assets using liquidity and momentum factors, and shows the top 10 in a simple GUI. Falls back to CLI mode automatically if the GUI cannot start (e.g., on headless servers).

✨ Features

• ⚡ Live data: Uses CoinMarketCap (PRO key if available, otherwise a public endpoint used by their website)
• 🧮 Scoring model: Combines market cap, volume, 24h and 7d momentum via normalized z-scores
• 🏆 Top 10 table: Ranks assets and displays key stats
• 🖥️ GUI + CLI: Tkinter/ttk desktop UI with automatic CLI fallback
• ⏱️ Real-time tracking: Optional live tracker with stats and projection

📊 What “Score” means (simple)

• Score is a single number that ranks coins based on liquidity and momentum. Higher is better.
• It blends four factors: volume (most weight), 7‑day change, 24‑hour change, and market cap.

🧰 Requirements

• Python: 3.10+
• System packages for GUI (if you want the desktop app):
  • macOS: Tk ships with the official Python installer
  • Ubuntu/Debian: sudo apt-get install python3-tk
  • Fedora: sudo dnf install python3-tkinter
  • Windows: Works with standard Python; GUI requires a desktop session

Python dependencies are listed in requirements.txt and installed via pip.

🛠️ Installation

# optional but recommended
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate

pip install -r requirements.txt

▶️ Running

🖥️ GUI (preferred where available)

python app.py

If the GUI cannot start (e.g., missing Tk or headless), the app will log the issue and switch to CLI mode automatically.

🧾 CLI (explicit)

# Unix/macOS
LIMIT=300 CONVERT=USD python app.py

# Windows (PowerShell)
$env:LIMIT=300; $env:CONVERT=USD; python app.py

# Windows (cmd)
set LIMIT=300 && set CONVERT=USD && python app.py

🔑 API key options

• In-app (recommended): In the GUI, toggle "Use API key", paste your key, and click "Save Key". It persists in config.json next to app.py.
• Environment variable: Set CMC_API_KEY to use the PRO API without saving to disk.
• LIMIT: Number of assets to pull before filtering (default: 300)
• CONVERT: Quote currency, one of USD|EUR|GBP (default: USD)

🧪 Example CLI output

Top 10 Coins:
 1. Bitcoin (BTC) | Score 2.31 | Price $68.2K | Mcap $1.34T | Vol $27.5B | 24h 1.23% | 7d 4.56%
 2. ...

🧠 How it works

• Data source: Tries CoinMarketCap PRO (/v1/cryptocurrency/listings/latest) if CMC_API_KEY is set; otherwise falls back to a public endpoint consumed by coinmarketcap.com
• Filtering: Removes illiquid/micro-cap assets (default thresholds: market cap > $100M and volume 24h > $5M)
• Scoring: Computes z-scores for log(market cap), log(volume), 7d % change, 24h % change and combines them with weights:
  • volume 0.35, 7d momentum 0.30, 24h momentum 0.20, market cap 0.15
• Presentation: Shows the top 10 by composite score in a table

⏱️ Tracking

Real-time tracking lets you monitor the displayed list with live updates and simple projections.

▶️ Start/stop

• Click Analyze first. After results load, a Track button appears next to Analyze.
• Click Track to start; the button toggles to Stop. Click Stop to end tracking.

👀 What it shows

• A status line below the table updates every 30s with:
  • 📈 Avg Δ since start: Average percent change across displayed coins, from the moment tracking began
  • 🏅 Best/Worst: Top gainers/decliners since tracking began
  • 🔮 Next 5m proj (avg): Short-term projection based on a simple regression over recent samples
  • 🏦 Source: When using USD with a Binance match, you’ll see: source: Binance USDT

🌐 Data sources

• When Convert=USD, the tracker attempts to overlay live prices from Binance USDT pairs (e.g., BTCUSDT, ETHUSDT).
• If a symbol is not available on Binance or Convert ≠ USD, it falls back to the latest analysis snapshot.

💡 Behavior and tips

• The tracker respects the current toggles:
  • 🗂️ Show all: Tracks all ranked coins if enabled; otherwise tracks the top 10.
  • 🧱 Filter: Applies the same liquidity filter as the analysis step.
• ⏳ Since-start baseline: Statistics are computed relative to the price at the moment you pressed Track.
• 🔎 Precision: The table updates as new prices arrive; small moves are displayed with higher precision.
• 🌐 Connectivity: Network errors are logged in the log pane; the tracker will retry on the next interval.

📁 Project layout

• app.py: Main app (data fetch, scoring, GUI, CLI)
• requirements.txt: Python dependencies

🛟 Troubleshooting

• GUI fails to open on Linux/WSL: Ensure Tk is installed (e.g., sudo apt-get install python3-tk). On WSL without an X server, run via CLI or execute the app with Windows Python instead of WSL Python.
• Rate limit or data errors: Set CMC_API_KEY to use the PRO API, or try again later.
• SSL/network issues: Corporate proxies or SSL interception can cause failures; configure your proxy environment variables if needed.
• Confirming PRO usage: The log shows "Data source: CoinMarketCap PRO" when your key is used; otherwise it shows "PUBLIC".

⚠️ Disclaimer

This software is for educational and research purposes only and does not constitute financial advice. Use at your own risk.