crypto-tracker

# Crypto Tracker

Track cryptocurrency prices, set price/percentage alerts, and search coins using the free CoinGecko API (no API key required).

## Quick Commands

### Check Prices
```bash
# Single coin
uv run {baseDir}/scripts/crypto.py price bitcoin

# Multiple coins
uv run {baseDir}/scripts/crypto.py price bitcoin ethereum solana

# With more details (market cap, volume)
uv run {baseDir}/scripts/crypto.py price bitcoin --detailed
```

### Search Coins
```bash
# Find coin ID by name/symbol
uv run {baseDir}/scripts/crypto.py search doge
uv run {baseDir}/scripts/crypto.py search cardano
```

### Manage Alerts

```bash
# Set price threshold alert
uv run {baseDir}/scripts/crypto.py alert <user_id> bitcoin above 100000
uv run {baseDir}/scripts/crypto.py alert <user_id> ethereum below 3000

# Set percentage change alert (24h)
uv run {baseDir}/scripts/crypto.py alert <user_id> bitcoin change 5    # ±5%
uv run {baseDir}/scripts/crypto.py alert <user_id> solana drop 10      # -10%
uv run {baseDir}/scripts/crypto.py alert <user_id> ethereum rise 15    # +15%

# List user's alerts
uv run {baseDir}/scripts/crypto.py alerts <user_id>

# Remove an alert
uv run {baseDir}/scripts/crypto.py alert-rm <alert_id>

# Check all alerts (for cron/heartbeat)
uv run {baseDir}/scripts/crypto.py check-alerts
```

## Coin Aliases

Common symbols are automatically resolved:
- `btc` → bitcoin
- `eth` → ethereum  
- `sol` → solana
- `doge` → dogecoin
- `ada` → cardano
- `xrp` → ripple
- `dot` → polkadot
- `matic` → polygon
- `link` → chainlink
- `avax` → avalanche-2
- `ltc` → litecoin

## Alert Types

| Type | Example | Triggers When |
|------|---------|---------------|
| `above` | `alert user btc above 100000` | Price >= $100,000 |
| `below` | `alert user eth below 3000` | Price <= $3,000 |
| `change` | `alert user btc change 5` | 24h change >= ±5% |
| `drop` | `alert user sol drop 10` | 24h change <= -10% |
| `rise` | `alert user eth rise 15` | 24h change >= +15% |

## Cron Integration

Check alerts periodically (e.g., every 15 minutes):
```bash
uv run {baseDir}/scripts/crypto.py check-alerts --json-output
```

Returns triggered alerts with user IDs for notification.

## Data Storage

Alerts stored in `{baseDir}/data/alerts.json` with:
- Per-user alert tracking
- Cooldown between repeat notifications (default: 1 hour)
- Last triggered timestamp

## Notes

- CoinGecko free tier: ~10-30 requests/minute (no API key needed)
- 15,000+ coins supported
- Use `--json-output` flag for machine-readable output