Crypto Price Monitor

Real-time cryptocurrency price tracking with intelligent alerts

A proactive OpenClaw agent that monitors cryptocurrency prices using CoinGecko's API and sends smart alerts when significant price movements occur. Perfect for traders, investors, and crypto enthusiasts who want to stay informed without constantly checking prices.

🎯 What It Does

Continuous monitoring — Checks prices every 5 minutes via scheduled heartbeat
Smart alerts — Only notifies on significant moves (configurable thresholds)
Multi-coin tracking — Monitor Bitcoin, Ethereum, and custom watchlists
Historical context — Shows 24h change, volume, and market cap
Rate-limit aware — Respects CoinGecko's free tier limits (50 req/min)
Beautiful formatting — Clean, emoji-rich price alerts

✨ Key Features

Proactive Heartbeat Monitoring

The agent wakes up every 5 minutes, checks your watchlist, and alerts you only when:

Price moves >5% in 5 minutes (significant movement)
Price crosses custom thresholds you've set
Major market events detected (>20% moves)

When nothing noteworthy happens, it stays silent with HEARTBEAT_OK.

Intelligent Alert Levels

🚨 URGENT — >20% price change (major event)
⚠️ IMPORTANT — 10-20% price change
💡 INTERESTING — 5-10% price change
✅ HEARTBEAT_OK — No significant movement

On-Demand Price Checks

Ask the agent anytime:

"What's the price of Bitcoin?"
"Show me ETH stats"
"Check my watchlist"
"Add Solana to my watchlist"

📋 Prerequisites

OpenClaw v0.20.0 or later
CoinGecko API (free tier works great — no key required for basic usage)
Telegram/Discord/Signal account for receiving alerts

🚀 Quick Start

1. Install the template

hatchery run @openclaw/crypto-price-monitor

2. Configure your watchlist

Edit the initial watchlist in memory/watchlist.json or just tell the agent:

Add Solana and Cardano to my watchlist

3. Set alert thresholds (optional)

Alert me when Bitcoin moves more than 3% in 5 minutes

The agent will remember your preferences in MEMORY.md.

4. Sit back and receive alerts

The agent monitors continuously and alerts you only when something significant happens.

🔧 Configuration

Environment Variables

No API keys required for basic usage! CoinGecko's free tier is accessed without authentication.

Optional:

# For higher rate limits (300 req/min)
COINGECKO_API_KEY=your_pro_api_key_here

# Set your timezone for time-aware alerts
USER_TIMEZONE=America/New_York

Watchlist Management

Your watchlist is stored in memory/watchlist.json:

{
  "coins": [
    {
      "id": "bitcoin",
      "symbol": "BTC",
      "alertThreshold": 5.0
    },
    {
      "id": "ethereum",
      "symbol": "ETH",
      "alertThreshold": 5.0
    }
  ]
}

You can edit this file directly or just talk to the agent naturally.

Heartbeat Schedule

By default, checks every 5 minutes. To adjust, modify the OpenClaw heartbeat configuration:

{
  "heartbeat": {
    "enabled": true,
    "interval": "*/5 * * * *"  // cron format: every 5 minutes
  }
}

💬 Example Conversations

Adding Coins to Your Watchlist

You: Add Solana and Polkadot to my watchlist

Agent: ✅ Added to your watchlist:
• Solana (SOL) — $98.45
• Polkadot (DOT) — $7.23

I'll monitor these for significant price movements.

On-Demand Price Check

You: What's Bitcoin doing?

Agent: ₿ Bitcoin (BTC)
💰 $52,340.50
📊 24h: +2.34% | Vol: $28.4B
📈 Market Cap: #1 ($1.03T)

Proactive Alert (Heartbeat)

Agent: 🚨 SIGNIFICANT PRICE MOVEMENT

₿ Bitcoin (BTC)
💰 $54,123.00 (+3.4% in 5 min)
📊 24h: +5.67%

This crossed your 3% alert threshold.

🏗️ Architecture

File Structure

workspace/
├── README.md                 # This file
├── hatchery.yaml            # Runtime config (Claude Sonnet, heartbeat enabled)
├── SOUL.md                  # Agent personality (analytical, calm)
├── AGENTS.md                # Behavioral instructions
├── MEMORY.md                # Long-term preferences and knowledge
├── IDENTITY.md              # Quick identity card
├── TOOLS.md                 # Setup and customization guide
├── HEARTBEAT.md             # Periodic monitoring checklist
├── skills/
│   └── coingecko/
│       ├── SKILL.md         # CoinGecko API instructions
│       └── fetch-price.sh   # Price fetching script
└── memory/
    ├── watchlist.json       # Your tracked coins
    └── heartbeat-state.json # Last check timestamps and values

How It Works

Heartbeat trigger — OpenClaw calls the agent every 5 minutes
Load state — Agent reads heartbeat-state.json for last known prices
Fetch prices — Calls CoinGecko API via skills/coingecko/fetch-price.sh
Compare & decide — Calculates % change, checks thresholds
Alert or silence — Sends alert if significant, otherwise HEARTBEAT_OK
Update state — Writes new prices to heartbeat-state.json

🛡️ Security & Privacy

Main session only — This agent is designed for personal use (operator only)
No DM/group sessions — Prevents unauthorized users from modifying your watchlist
API key protection — Never logs credentials to memory or transcripts
Read-only by default — Uses CoinGecko's public API (no trading capabilities)

📊 Rate Limits & Performance

CoinGecko Free Tier

50 requests/minute — More than enough for typical watchlists
With 10 coins checked every 5 minutes → 2 req/min average
No API key required for basic usage

CoinGecko Pro Tier (optional)

300 requests/minute — For large watchlists or more frequent checks
Set COINGECKO_API_KEY environment variable

Resource Usage

CPU: Minimal (curl + jq scripts)
Memory: ~50MB (agent overhead)
Network: ~10KB per price check

🎨 Customization Ideas

Adjust Alert Sensitivity

Edit HEARTBEAT.md to change thresholds:

- If price moved >3% (was 5%): IMPORTANT alert
- If price moved >15% (was 20%): URGENT alert

Add More Coins

CoinGecko supports 10,000+ coins. Find IDs at: https://api.coingecko.com/api/v3/coins/list

Multi-Timeframe Analysis

Modify skills/coingecko/fetch-price.sh to include 1h, 7d, 30d changes.

Export Price History

Add a skill to write daily price snapshots to memory/price-history/YYYY-MM-DD.json.

🐛 Troubleshooting

Agent isn't sending alerts

Check heartbeat is enabled in OpenClaw config
Verify watchlist.json has valid coin IDs
Ensure prices are actually moving enough to cross thresholds
Check logs: docker logs openclaw

"Rate limit exceeded" errors

You're checking too many coins too frequently
Add a Pro API key, or reduce check frequency to every 10 minutes

Coin not found

Verify the coin ID at https://api.coingecko.com/api/v3/coins/list
Use the exact id field (not symbol)
Example: Use "bitcoin" not "BTC"

📚 Learn More

📄 License

MIT License - Free to use and modify

🤝 Contributing

Found a bug or have an enhancement? Open an issue or PR on the Hatchery registry.

Built with OpenClaw — Self-hosted AI agents that actually work for you.

crypto-price-monitor

Quick Start

Template Contents

About