🔔 Crypto Sentinel

Real-time cryptocurrency price monitoring and alert system. Track any token, set price thresholds, and get notified instantly via console, email, or webhook.

---

✨ Features

• 📊 Live Price Tracking — Monitor any crypto token via the free CoinGecko API (no API key needed)
• 🔔 Configurable Alerts — Price above/below thresholds, percentage change detection
• 📡 Multiple Alert Channels — Console output, SMTP email, HTTP webhooks
• ⚡ Async Engine — Efficient multi-token monitoring with asyncio
• 🖥️ Clean CLI — Colorful terminal output with formatted price tables
• 🔧 Modular Design — Use as a library or standalone CLI tool

🚀 Quick Start

Installation

git clone https://github.com/sofia-willow/crypto-sentinel.git
cd crypto-sentinel
pip install -e .

Or install dependencies directly:

pip install -r requirements.txt

One-Shot Price Check

python -m sentinel price btc eth sol

Watch Prices with Alerts

python -m sentinel watch btc eth sol \
  --alert-above btc:90000 \
  --alert-below eth:1500 \
  --interval 30

📖 Usage

CLI Commands

watch — Real-time monitoring

python -m sentinel watch <tokens...> [options]

Options:
  --alert-above TOKEN:PRICE   Alert when price exceeds threshold
  --alert-below TOKEN:PRICE   Alert when price drops below threshold
  --interval SECONDS           Poll interval (default: 30)
  --currency CURRENCY          Quote currency (default: usd)
  --webhook URL                Webhook URL for alert delivery
  -v, --verbose                Enable debug logging

price — One-shot price check

python -m sentinel price btc eth --currency eur

As a Python Library

import asyncio
from sentinel.config import AlertType, SentinelConfig
from sentinel.monitor import PriceMonitor

async def main():
    config = SentinelConfig(
        tokens=["btc", "eth", "sol"],
        poll_interval=30.0,
    )
    config.add_alert("btc", AlertType.ABOVE, 90_000)
    config.add_alert("eth", AlertType.BELOW, 1_500)

    monitor = PriceMonitor(config=config)
    await monitor.run()

asyncio.run(main())

⚙️ Configuration

Supported Tokens

Use common ticker symbols (btc, eth, sol, doge, etc.) or CoinGecko IDs directly (bitcoin, ethereum, etc.). Built-in aliases map 15+ popular tokens automatically.

Alert Types

Type	Description	Example
ABOVE	Triggers when price ≥ threshold	BTC > $90,000
BELOW	Triggers when price ≤ threshold	ETH < $1,500
PERCENT_CHANGE	Triggers on 24h % change	SOL moves > 10%

Alert Channels

• Console — Colored terminal output (default)
• Email — SMTP delivery (configure host, credentials, recipients)
• Webhook — HTTP POST with JSON payload to any URL

JSON Configuration

Save and load configs from JSON:

config.save("my_alerts.json")
config = SentinelConfig.load("my_alerts.json")

🏗️ Architecture

sentinel/
├── __init__.py      # Package metadata
├── __main__.py      # python -m sentinel entry point
├── cli.py           # Argument parsing and CLI commands
├── config.py        # Configuration dataclasses and serialization
├── providers.py     # CoinGecko API client with rate limiting
├── alerts.py        # Alert evaluation, events, and delivery handlers
└── monitor.py       # Core async monitoring loop

Data flow: CLI → Config → Monitor → Provider (CoinGecko) → AlertDispatcher → Handlers

The monitor polls the provider at a configurable interval, evaluates alert rules against fresh prices, and dispatches triggered alerts to all configured channels.

🧪 Running Tests

python -m pytest tests/ -v

Or with unittest:

python -m unittest discover tests/ -v

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-thing)
3. Commit your changes (git commit -m 'Add amazing thing')
4. Push to the branch (git push origin feature/amazing-thing)
5. Open a Pull Request

Please ensure:

• Type hints on all functions
• Docstrings on public methods
• Tests for new functionality
• Code passes existing tests

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ☕ by Sofia Willow