FOMO Guard

Don't buy the top! CLI tool + API to help crypto newcomers avoid FOMO-driven decisions by analyzing price, social, and on-chain signals.

Features

• FOMO Score (1-100): Weighted composite score from price, social, and on-chain signals
• Multiple Data Sources: CoinGecko, Twitter, Reddit, LunarCrush, Glassnode, Etherscan
• Cooling Period System: Set reminders to prevent impulsive buying
• Historical Analysis: See what happened after past FOMO events
• REST API: Full FastAPI server for integration
• Built-in Caching: Respects API rate limits with intelligent caching
• Retry Logic: Automatic retries with exponential backoff

Installation

pip install fomo-guard

Quick Start

Check FOMO Score

# Basic check
fomo-guard check BTC

# Detailed analysis with indicator breakdown
fomo-guard check ETH --detailed

Example Output

FOMO Score for BTC: 72/100 !!!

┌─────────────────── ORANGE ───────────────────┐
│ High risk - strong FOMO signals detected     │
└──────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    Signal Analysis                       │
├──────────┬───────┬────────┬──────────┬─────────────────┤
│ Signal   │ Score │ Weight │ Risk     │ Status          │
├──────────┼───────┼────────┼──────────┼─────────────────┤
│ Price    │ 78    │ 40%    │ high     │ ATH proximity..│
│ Social   │ 65    │ 30%    │ high     │ Elevated activ.│
│ Onchain  │ -     │ 30%    │ -        │ No data        │
└──────────┴───────┴────────┴──────────┴─────────────────┘

Recommendation:
  High FOMO risk - strong warning signals from price.
  This could be a local top. Strongly consider waiting 24-48 hours.

Suggested wait time: 24 hours

Configure API Keys

# Set CoinGecko Pro API key (optional - free tier works)
fomo-guard config set coingecko YOUR_API_KEY

# Set social data providers
fomo-guard config set twitter YOUR_BEARER_TOKEN
fomo-guard config set lunarcrush YOUR_API_KEY

# Set on-chain providers
fomo-guard config set glassnode YOUR_API_KEY
fomo-guard config set etherscan YOUR_API_KEY

# List configured keys
fomo-guard config list

Cooling Period

When you feel the urge to buy, set a cooldown to prevent impulsive decisions:

# Set a cooldown (default: 24 hours)
fomo-guard cool BTC

# Custom duration
fomo-guard cool ETH --hours 48

# Check active cooldowns
fomo-guard cool --status

Historical Analysis

# View past FOMO events and their outcomes
fomo-guard history BTC --days 90

Start API Server

# Start the REST API
fomo-guard serve --port 8000

# Access endpoints:
# - API docs: http://localhost:8000/docs
# - Health check: http://localhost:8000/api/v1/health
# - Check coin: http://localhost:8000/api/v1/check/BTC

FOMO Score Interpretation

Score	Verdict	Meaning
0-30	GREEN	Low FOMO risk - reasonable entry conditions
31-60	YELLOW	Moderate risk - proceed with caution, consider DCA
61-80	ORANGE	High risk - strong FOMO indicators, consider waiting
81-100	RED	Extreme risk - likely buying the top!

Signal Analysis

FOMO Guard analyzes three categories of signals:

Price/Technical (40% weight)

• ATH proximity (how close to all-time high)
• RSI indicator (overbought > 70)
• 24h/7d price changes (pump detection)
• Volatility index

Social Sentiment (30% weight)

• Twitter mention velocity
• Reddit post/comment activity
• LunarCrush social metrics
• Sentiment polarity

On-chain (30% weight)

• Exchange inflows/outflows
• Whale transaction activity
• Supply in profit percentage
• Network activity metrics

API Endpoints

Endpoint	Method	Description
/api/v1/check/{symbol}	GET	Full FOMO analysis
/api/v1/score/{symbol}	GET	Score only
/api/v1/validate/{symbol}	GET	Validate coin exists
/api/v1/history/{symbol}	GET	Historical FOMO events
/api/v1/cool	POST	Register cooldown
/api/v1/cool/status	GET	Active cooldowns
/api/v1/cache/clear	POST	Clear response cache
/api/v1/health	GET	Health check

Configuration

Configuration is stored at ~/.config/fomo_guard/config.toml:

[api_keys]
coingecko = "your-pro-key"      # Optional - free tier works
coinmarketcap = "your-key"       # Alternative price source
twitter = "your-bearer-token"    # Social sentiment
reddit_client_id = "your-id"     # Social sentiment
reddit_client_secret = "secret"  # Social sentiment
lunarcrush = "your-key"          # Social metrics
glassnode = "your-key"           # On-chain data
etherscan = "your-key"           # ETH on-chain data

[settings]
default_cooldown_hours = 24
cache_ttl_minutes = 5

Supported Cryptocurrencies

FOMO Guard supports 50+ major cryptocurrencies including: BTC, ETH, SOL, BNB, XRP, ADA, DOGE, DOT, MATIC, SHIB, LTC, AVAX, LINK, UNI, ATOM, and many more.

For coins not in the built-in list, FOMO Guard will search CoinGecko automatically.

Development

# Clone the repository
git clone https://github.com/fomo-guard/fomo-guard.git
cd fomo-guard

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=fomo_guard

# Type checking
mypy fomo_guard

# Linting
ruff check fomo_guard

Disclaimer

FOMO Guard is an educational tool designed to help you make more informed decisions. It is NOT financial advice. Always do your own research (DYOR) and only invest what you can afford to lose. Cryptocurrency investments are highly volatile and risky.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.