Crypto Coin Screener MVP

A minimal yet robust MVP to analyze altcoins (excluding BTC and ETH) and filter out obvious scams using pragmatic heuristics.

Features

• Data Fetching: Pull top-N coins from CoinGecko (excluding BTC/ETH) with retry logic and caching
• Red-Flag Filters: Conservative heuristics to reject likely scams:
  • Age < 180 days
  • Market cap < $50M
  • Poor liquidity (volume/mcap < 0.005)
  • Suspicious supply dynamics
  • Extreme price moves with thin volume
• Composite Scoring: 0-100 score based on:
  • Market Quality (35%): volume, liquidity
  • Fundamentals (25%): market cap, supply transparency
  • Behavioural (20%): price stability, volume consistency
  • Dev/Community (20%): placeholder for future GitHub/social metrics
• Interactive UI: Streamlit dashboard with:
  • Adjustable filter thresholds
  • Results table with pass/fail reasons
  • Charts (top 20 scores, market cap vs volume scatter)
  • Detailed coin breakdowns
  • CSV export
• Data Persistence: Snapshot storage in DuckDB for historical tracking

Tech Stack

• Python 3.11+
• Streamlit - Interactive web UI
• pandas, numpy - Data manipulation
• pydantic - Configuration management
• pycoingecko - CoinGecko API client
• requests-cache - HTTP request caching
• scikit-learn - Percentile normalization
• plotly - Interactive charts
• duckdb - Embedded analytics database
• loguru - Logging

Project Structure

crypto-screener/
├── app.py                    # Streamlit application entry point
├── requirements.txt          # Python dependencies
├── .env.example             # Environment configuration template
├── README.md                # This file
├── samples/                 # Sample CSV exports
├── src/
│   ├── config.py           # Pydantic settings
│   ├── datasources/
│   │   ├── coingecko.py   # CoinGecko API client with retry
│   │   └── exchanges.py   # CCXT stub for future
│   ├── features/
│   │   └── derive.py      # Feature engineering
│   ├── rules/
│   │   ├── filters.py     # Red-flag filter rules
│   │   └── scoring.py     # Composite scoring system
│   ├── storage/
│   │   ├── cache.py       # Request caching setup
│   │   └── db.py          # DuckDB persistence
│   └── utils/
│       ├── logging.py     # Loguru configuration
│       └── typing.py      # Type definitions

Setup

Prerequisites

• Python 3.11 or higher
• pip

Installation

1. Clone/navigate to the project directory:

   cd crypto-screener

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment (optional):

   cp .env.example .env
   # Edit .env to customize settings

Usage

Run the application:

streamlit run app.py

The app will open in your browser at http://localhost:8501.

Using the UI:

1. Sidebar Settings: Adjust filter thresholds and top-N coins
2. Recompute: Click to refresh data with new parameters
3. Results Table: View all coins or filter to survivors only
4. Export CSV: Download survivors with scores and metrics
5. Charts: Explore top scorers and market cap vs volume distributions
6. Detail Expanders: Click to see component scores for top 10 coins

Configuration Options:

Default values can be changed in .env:

TOP_N=200                      # Number of coins to fetch
AGE_DAYS_MIN=180              # Minimum age requirement
MCAP_MIN_USD=50000000         # Minimum market cap ($50M)
VOL_MCAP_MIN=0.005            # Minimum volume/mcap ratio
EXTREME_MOVE_THRESHOLD=2.5    # Price move threshold (2.5x = 250%)
LOW_VOLUME_THRESHOLD=10000000 # Low volume threshold ($10M)
CACHE_EXPIRE_MINUTES=10       # Request cache duration
DB_PATH=./screener_data.duckdb
LOG_LEVEL=INFO

Architecture

Data Pipeline:

1. Fetch - CoinGecko API with exponential backoff retry
2. Features - Derive age, liquidity, volatility, supply metrics
3. Filters - Apply 5 red-flag rules with explicit reasons
4. Scoring - Percentile-normalize features and compute weighted score
5. Storage - Save snapshot to DuckDB
6. Display - Render in Streamlit with interactive controls

Filter Rules:

Each rule returns (passed: bool, reason: str):

• Age: Rejects coins < 180 days old
• Market Cap: Rejects coins < $50M market cap
• Liquidity: Rejects low volume/mcap ratio
• Supply Sanity: Flags suspicious tokenomics (high circulation in young coins)
• Extreme Moves: Rejects extreme price swings with thin volume

Scoring Components:

• Market Quality (35 pts): Volume percentile (20) + liquidity ratio (15)
• Fundamentals (25 pts): Market cap rank (15) + supply transparency (10)
• Behavioural (20 pts): Price stability (10) + volume consistency (10)
• Dev/Community (20 pts): Neutral placeholder (future: GitHub stars, commits, social)

Development

Adding Tests:

Simple pytest examples:

# test_filters.py
from src.rules.filters import rule_age
from src.config import Settings
import pandas as pd

def test_rule_age():
    cfg = Settings()
    row = pd.Series({"age_days": 200})
    passed, reason = rule_age(row, cfg)
    assert passed is True

Run tests:

pytest

Extending Data Sources:

1. Edit src/datasources/exchanges.py to implement CCXT integration
2. Update src/features/derive.py to add new computed features
3. Add new rules in src/rules/filters.py with the same signature
4. Adjust weights in src/rules/scoring.py

Caching

• HTTP requests cached for 10 minutes via requests-cache
• Streamlit @st.cache_data caches pipeline results for 10 minutes
• Manual cache clear: Delete coingecko_cache.sqlite

Troubleshooting

Rate Limiting:

CoinGecko free tier has rate limits. The client includes retry with exponential backoff.

Missing Data:

Some coins may lack total_supply or ath_date. Defaults are applied conservatively.

Performance:

For 200+ coins, initial fetch takes ~5-10 seconds. Subsequent runs use cache.

Deployment

Streamlit Cloud

See DEPLOYMENT.md for complete deployment instructions.

Quick deploy:

1. Push to GitHub
2. Connect to Streamlit Cloud (point to app.py)
3. Database auto-prunes on startup to stay under 1GB

Built-in Database Management:

The app automatically prunes old snapshots on startup:

• Triggers when total size approaches 900MB
• Keeps last 14 days of snapshots
• Always preserves at least 5 most recent snapshots
• Vacuums database to reclaim space

No manual intervention needed for Streamlit Cloud deployments!

Manual Pruning (Optional):

For local development or manual cleanup, use the standalone script:

# Check size
python prune_database.py

# Prune old data (dry-run)
python prune_database.py --dry-run --keep-days 7

# Force pruning
python prune_database.py --force --keep-days 14

Future Enhancements

• Integrate CCXT for exchange count and order book depth
• Add GitHub API for dev activity metrics
• Implement social sentiment (Twitter/Reddit)
• Historical backtesting of filter effectiveness
• DEX liquidity via The Graph
• On-chain metrics (holder distribution, etc.)
• Alert system for new coins passing filters

License

MIT

Contributing

This is an MVP for personal use. Feel free to fork and extend.

Disclaimer

This tool is for educational purposes only. Not financial advice. Always DYOR (Do Your Own Research) before investing in any cryptocurrency.