fomo-guard 0.1.0
CLI tool to help crypto newcomers avoid FOMO-driven decisions by analyzing price, social, and on-chain signals
License: MIT
Requires Python: >=3.10
Keywords: analysis, bitcoin, cli, crypto, cryptocurrency, defi, ethereum, fomo, trading, web3

# FOMO Guard

[![PyPI version](https://badge.fury.io/py/fomo-guard.svg)](https://badge.fury.io/py/fomo-guard)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install fomo-guard
```

## Quick Start

### Check FOMO Score

```bash
# 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

```bash
# 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:

```bash
# 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

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

### Start API Server

```bash
# 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`:

```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

```bash
# 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](LICENSE) for details.

## Contributing

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