Skill: flotapponnier/mobula-alerts (version 1.0.0)

--- name: mobula-alerts displayName: Mobula - Smart Alerts & Monitoring description: 24/7 autonomous monitoring for crypto portfolios, whales, and market conditions. Multi-condition alerts via OpenClaw heartbeat. version: 1.0.0 author: Mobula category: crypto tags: - crypto - alerts - monitoring - automation - heartbeat requiredEnvVars: - MOBULA_API_KEY homepage: https://mobula.io docs: https://docs.mobula.io repository: https://github.com/Flotapponnier/Crypto-date-openclaw --- # Mobula - Smart Alerts & Monitoring 24/7 autonomous crypto monitoring using OpenClaw's heartbeat system. Set conditions once, let your agent monitor continuously and alert you on Telegram/WhatsApp/Discord. ## Quick Start **1. Get your free API key** (no credit card required) - Go to [mobula.io](https://mobula.io) and sign up - Free tier: 100 requests/minute - Copy your API key from the dashboard **2. Set your API key** ```bash export MOBULA_API_KEY="your_api_key_here" ``` **3. Set up monitoring** Ask your agent: - "Alert me if BTC moves more than 5% in 1 hour" - "Monitor my wallet and alert if any token drops 15%" - "Watch these whale wallets and alert on large buys" - "Find new tokens on Base matching my criteria every 6 hours" - "Send me a market brief every morning at 7am" --- ## Security ✅ **Read-only access** - No trading, no transactions ✅ **No private keys** - Only public blockchain data ✅ **Open source** - [View code on GitHub](https://github.com/Flotapponnier/Crypto-date-openclaw) ✅ **VirusTotal verified** - Benign scan results --- ## How It Works Unlike ChatGPT/Claude chat, your OpenClaw agent runs continuously. The heartbeat system (~30min intervals) allows your agent to: 1. **Check conditions** you've set (price thresholds, portfolio changes, whale movements) 2. **Fetch data** from Mobula API when needed 3. **Analyze** using multi-condition logic (not just "price > X") 4. **Alert** you on Telegram/WhatsApp/Discord only when conditions are met This skill provides **monitoring patterns** using Mobula endpoints. Combine with **mobula-prices** and **mobula-wallet** skills for complete functionality. --- ## Monitoring Patterns ### Pattern 1: Portfolio Guardian Monitor your wallet 24/7 for concentration risks and drops. **Setup:** > "Monitor my wallet 0x... and alert me on Telegram if any token drops more than 15% or my allocation exceeds 40% on one asset. Daily summary at 9am." **How it works:** Every heartbeat (~30min): 1. Fetch portfolio via `mobula_wallet_portfolio` 2. Calculate allocation percentages 3. Check conditions: - Any token >40% of portfolio → suggest rebalancing - Any token down >15% in 24h → alert with context - Total portfolio changed >10% → notify 4. Store previous values in memory to detect changes 5. Send daily summary at user's preferred time **Example alert:** ``` ⚠️ Portfolio Alert Your ETH allocation is now 47% (was 38% yesterday). Consider rebalancing to reduce concentration risk. Current holdings: - ETH: $12,340 (47%) - BRETT: $8,200 (31%) up 12% 24h - DEGEN: $5,890 (22%) down 3% 24h ``` --- ### Pattern 2: Whale Watching Track smart money and get alerted when whales move. **Setup:** > "Watch wallets 0xabc, 0xdef, 0x123. Alert if any buy/sell more than $50K. If multiple whales buy the same token within 6h, priority alert with full analysis." **How it works:** Every heartbeat: 1. Check transactions via `mobula_wallet_transactions` 2. If new significant transaction (>$50K): - Get token details via `mobula_market_data` - Check recent trades via `mobula_market_trades` - Cross-check if other tracked whales bought same token 3. If multiple whales buying → **priority alert** **Example alert:** ``` 🚨 Whale Alert - HIGH PRIORITY Wallet 0x742d... bought $150K of BRETT on Base (2h ago) Token: BRETT | Price: $0.089 (up 23% 24h) Mcap: $2.3M | Volume: $1.2M (8x normal) Cross-signal: 2 other tracked whales also bought BRETT: - 0x888... bought $80K (4h ago) - 0x111... bought $120K (1h ago) ⚠️ Possible coordinated accumulation. ``` --- ### Pattern 3: Token Scout (Autonomous Discovery) Agent autonomously finds new tokens matching your criteria. **Setup:** > "Find tokens on Base/Arbitrum every 6h: mcap under $5M, liquidity over $100K, volume up 50%+ 24h, verified contract. Send top 3 with analysis." **How it works:** Every 4-6 hours on heartbeat: 1. User defines criteria (stored in memory): - Chains: Base, Arbitrum - Market cap: <$5M - Liquidity: >$100K - Volume change 24h: >+50% 2. Search/filter tokens via `mobula_market_data` 3. For each match: - Get 7-day history via `mobula_market_history` - Check metadata via `mobula_metadata` - Calculate risk score 4. Send top 3 with analysis **Example alert:** ``` 🔍 Token Scout - 3 New Matches 1. BOOP on Base - Price: $0.0042 (up 156% 24h, up 340% 7d) - Mcap: $2.1M | Liquidity: $280K - Volume: $890K (12x average) - Contract: Verified ✅ - Risk: Medium 2. ZORP on Arbitrum - Price: $0.0089 (up 78% 24h) - Mcap: $3.4M | Liquidity: $450K - Whale buy: $60K (3h ago) - Risk: Medium-High 3. [...] ``` --- ### Pattern 4: Smart Price Alerts Contextual alerts with multi-condition logic (not just "price > X"). **Setup:** > "Alert me if BTC moves more than 5% in 1 hour, BUT only if volume is 2x above 24h average. Real moves, not noise." **How it works:** Every heartbeat: 1. Get current price and volume via `mobula_market_data` 2. Compare to price from 1 hour ago (stored in memory) 3. Check if volume condition met 4. Only alert if **BOTH** conditions true **Other smart alert examples:** - "Alert if ETH breaks $4K after consolidating $3,800-$3,950 for 3+ days" - "Alert if any of my watchlist tokens pump >20% with volume >5x average" - "Alert if BTC drops >3% but ETH is green (divergence signal)" --- ### Pattern 5: Market Brief Automated morning/evening market overviews. **Setup:** > "Send market overview at 7am and 7pm on Telegram. Include BTC, ETH, SOL, and any top 100 token that moved more than 10%." **How it works:** Every scheduled time (7am, 7pm): 1. Check major tokens (BTC, ETH, SOL, BNB) via `mobula_market_multi` 2. Identify major moves (>5% in 24h) 3. Check volume leaders 4. Provide concise overview **Example brief:** ``` 📊 Crypto Market Brief - Feb 20, 7:00 AM Majors: - BTC: $67,234 (up 2.1% 24h) - ETH: $3,456 (up 4.3% 24h) - SOL: $123.45 (down 1.2% 24h) Big Movers (24h): - PEPE: up 23% - ARB: up 15% - AVAX: down 12% Sentiment: Cautiously bullish. ETH leading, memes pumping. ``` --- ## Setting Up Heartbeat Monitoring **Step 1: Tell your agent what to monitor** Be specific about: - What to track (wallets, tokens, conditions) - When to alert (thresholds, multi-condition logic) - How often to check (30min, 1h, 6h) - Where to alert (Telegram, Discord, WhatsApp) **Step 2: Agent stores config in memory** Your agent remembers: - Monitoring tasks - Previous values (for change detection) - Alert preferences - Scheduling **Step 3: Agent monitors on heartbeat** Every heartbeat interval: - Fetches only necessary data (respects rate limits) - Compares to previous values - Evaluates conditions - Sends alerts when triggered --- ## Combining Endpoints for Rich Analysis ### Full Token Analysis User asks: "Should I buy this token?" 1. `mobula_market_data` → current price, mcap, volume, liquidity 2. `mobula_market_history` → 7d and 30d trend 3. `mobula_market_trades` → recent activity (accumulation or distribution?) 4. `mobula_metadata` → project info, socials, verification **Response format:** ``` TOKEN Analysis Price: $0.042 (down 8% 24h, up 156% 7d) - Near 7d high, down from $0.051 - Still up 400% from 30d low Fundamentals: - Mcap: $2.1M (small cap, high risk/reward) - Liquidity: $280K (decent for size) - Volume: $1.2M 24h (healthy) On-chain: - Recent trades show buying pressure (3:1 buy/sell ratio) - 2 large buys ($50K+) in last 2h Project: - Contract verified ✅ - Active Twitter (12K followers) Risk: Small cap, high volatility. Don't ape more than you can lose. ``` --- ## Authentication All requests require your API key in the `Authorization` header: ``` Authorization: ${MOBULA_API_KEY} ``` **If authentication fails (401/403):** - Verify: `echo $MOBULA_API_KEY` - Regenerate at [mobula.io](https://mobula.io) if expired - Check rate limits (100 req/min free tier) --- ## Rate Limits & Best Practices ### Respect Rate Limits - **Free tier:** 100 requests/minute - Use `mobula_market_multi` for batch queries - Cache data in memory (metadata doesn't change often) ### Efficient Heartbeat Usage - Don't call every endpoint on every heartbeat - Only fetch what's needed based on active monitoring - Batch requests when possible - Store previous values to detect changes --- ## Error Handling **API Key Issues:** - "I need a Mobula API key. Get one free at https://mobula.io then set it: `export MOBULA_API_KEY='your_key'`" - "Invalid API key. Check it at https://mobula.io" - "Rate limit hit. Upgrade at https://mobula.io or retry later" **Monitoring Setup:** - "What conditions should I monitor for?" - "How often should I check? (30min, 1h, 6h)" - "Where should I send alerts? (Telegram, Discord, WhatsApp)" --- ## When to Use This Skill **✅ USE WHEN the user:** - Wants to set up alerts or monitoring - Asks for 24/7 tracking - Wants autonomous discovery - Needs scheduled reports or briefs - Mentions "alert me when", "monitor", "track", "watch" **❌ DON'T USE WHEN:** - User wants one-time price check (use mobula-prices) - User wants to check portfolio once (use mobula-wallet) --- ## Related Skills - **mobula-prices** - Token prices and market data (required for alerts) - **mobula-wallet** - Portfolio tracking (required for wallet monitoring) --- ## Ready-to-Use Templates Copy these templates to `~/openclaw/heartbeat/`: - **[`heartbeat-portfolio-guardian.md`](../../examples/heartbeat-portfolio-guardian.md)** - **[`heartbeat-whale-tracker.md`](../../examples/heartbeat-whale-tracker.md)** - **[`heartbeat-token-scout.md`](../../examples/heartbeat-token-scout.md)** - **[`heartbeat-market-brief.md`](../../examples/heartbeat-market-brief.md)** --- ## Resources - **Get API Key:** [mobula.io](https://mobula.io) - **API Docs:** [docs.mobula.io](https://docs.mobula.io) - **GitHub:** [Mobula OpenClaw Skills](https://github.com/Flotapponnier/Crypto-date-openclaw) - **Support:** Open issue on GitHub --- ## Version History **1.0.0** (2024-03-25): Initial release - Portfolio guardian pattern - Whale watching pattern - Autonomous token scout - Smart price alerts - Market brief automation - Heartbeat optimization tips

path: README.md
content: # Mobula Alerts - 24/7 Smart Crypto Monitoring

> 24/7 autonomous monitoring for crypto portfolios, whales, and market conditions. Multi-condition alerts via OpenClaw heartbeat.

[![ClawHub](https://img.shields.io/badge/ClawHub-Install-blue)](https://clawhub.ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What This Skill Does

**mobula-alerts** transforms your OpenClaw agent into a 24/7 crypto monitoring system. Set conditions once, and your agent continuously monitors prices, portfolios, whales, and market conditions — alerting you only when something important happens.

### Key Features

✅ **Portfolio Guardian** - Alert on concentration risks, drops, allocation changes
✅ **Whale Watching** - Track smart money movements across wallets
✅ **Token Scout** - Autonomously discover new tokens matching your criteria
✅ **Smart Alerts** - Multi-condition logic (price + volume + on-chain signals)
✅ **Market Briefs** - Automated morning/evening summaries

### Perfect For

- Portfolio managers wanting 24/7 risk monitoring
- Traders tracking whale movements
- Alpha hunters discovering new tokens
- Anyone wanting proactive (not reactive) crypto monitoring

---

## How This Is Different

**ChatGPT/Claude chat:**
- You ask → it answers
- You need to remember to check
- No continuous monitoring

**OpenClaw + mobula-alerts:**
- Set conditions once → agent monitors 24/7
- Agent alerts you on Telegram/Discord/WhatsApp
- No prompting needed, it works autonomously

**Example:**
```
You: "Alert me if BTC moves >5% in 1h with volume 2x above average"

Agent: [Monitors every 30min via heartbeat]
        [Only alerts when BOTH conditions met]
        [You do other things while it watches]
```

---

## Quick Start (5 minutes)

### 1. Install All Required Skills

This skill orchestrates monitoring using data from:
- **[mobula-prices](../mobula-prices/)** - For price and market data
- **[mobula-wallet](../mobula-wallet/)** - For portfolio tracking

Install all 3:
```
Tell your agent: "Install mobula-prices, mobula-wallet, and mobula-alerts from ClawHub"
```

### 2. Get Your Free API Key

1. Go to [mobula.io](https://mobula.io)
2. Sign up (takes 30 seconds)
3. Copy your API key from the dashboard

**Free tier includes:**
- 100 requests/minute
- No credit card required
- Sufficient for most monitoring tasks

### 3. Set Your API Key

```bash
export MOBULA_API_KEY="your_api_key_here"
```

**Make it permanent:**
```bash
echo 'export MOBULA_API_KEY="your_key"' >> ~/.zshrc
source ~/.zshrc
```

### 4. Set Up Your First Alert

Ask your agent:
```
"Alert me if BTC moves more than 5% in 1 hour"
```

Your agent will:
1. Acknowledge the monitoring task
2. Store the condition in memory
3. Check every heartbeat (~30min)
4. Alert you only when the condition is met

---

## Monitoring Patterns

### Pattern 1: Portfolio Guardian

**What it does:** Monitors your wallet 24/7 for concentration risks and significant drops.

**Setup:**
```
"Monitor my wallet 0x... and alert me on Telegram if:
- Any token drops more than 15%
- My allocation exceeds 40% on one asset
- Total portfolio value changes by more than 10%

Send me a daily summary at 9am."
```

**How it works:**
- Every heartbeat (~30min):
  - Fetches your portfolio
  - Calculates allocation percentages
  - Compares to previous values
  - Alerts on threshold breaches

**Example alert:**
```
⚠️ Portfolio Alert

Your ETH allocation is now 47% (was 38% yesterday).
Consider rebalancing to reduce concentration risk.

Current holdings:
- ETH: $12,340 (47%)
- BRETT: $8,200 (31%) up 12% 24h
- DEGEN: $5,890 (22%) down 3% 24h
```

---

### Pattern 2: Whale Watching

**What it does:** Tracks smart money movements and alerts on coordinated activity.

**Setup:**
```
"Watch these whale wallets: 0xabc, 0xdef, 0x123

Alert me if:
- Any wallet buys/sells more than $50K
- Multiple whales buy the same token within 6h (priority alert)
- Any whale dumps a token I'm holding
```

**How it works:**
- Every heartbeat:
  - Checks transactions for tracked wallets
  - If significant trade (>$50K):
    - Gets token details
    - Checks if other whales bought same token
    - Cross-references with your holdings

**Example alert:**
```
🚨 Whale Alert - HIGH PRIORITY

Wallet 0x742d... bought $150K of BRETT on Base (2h ago)

Token: BRETT | Price: $0.089 (up 23% 24h)
Mcap: $2.3M | Volume: $1.2M (8x normal)

Cross-signal: 2 other tracked whales also bought BRETT:
- 0x888... bought $80K (4h ago)
- 0x111... bought $120K (1h ago)

⚠️ Possible coordinated accumulation.
```

---

### Pattern 3: Token Scout

**What it does:** Autonomously discovers new tokens matching your criteria.

**Setup:**
```
"Find new tokens every 6 hours with these criteria:
- Chains: Base, Arbitrum
- Market cap: under $5M
- Liquidity: over $100K
- Volume: up 50%+ in 24h
- Contract: verified only

Send me top 3 matches with full analysis."
```

**How it works:**
- Every 6 hours (on heartbeat):
  - Searches tokens matching criteria
  - For each match:
    - Gets 7-day price history
    - Checks metadata and verification
    - Calculates risk score
  - Sends top 3 with analysis

**Example alert:**
```
🔍 Token Scout - 3 New Matches

1. BOOP on Base
   - Price: $0.0042 (up 156% 24h, up 340% 7d)
   - Mcap: $2.1M | Liquidity: $280K
   - Volume: $890K (12x average)
   - Contract: Verified ✅
   - Risk: Medium

2. ZORP on Arbitrum
   - Price: $0.0089 (up 78% 24h)
   - Mcap: $3.4M | Liquidity: $450K
   - Whale buy: $60K (3h ago)
   - Risk: Medium-High

3. [...]
```

---

### Pattern 4: Smart Price Alerts

**What it does:** Multi-condition alerts (not just "price > X").

**Setup:**
```
"Alert me if BTC moves more than 5% in 1 hour,
BUT only if volume is 2x above 24h average.
I want real moves, not noise."
```

**Other examples:**
```
"Alert if ETH breaks $4K after consolidating
between $3,800-$3,950 for 3+ days"

"Alert if any of my watchlist tokens pump >20%
with volume >5x average"

"Alert if BTC drops >3% but ETH is green
(divergence signal)"
```

**How it works:**
- Every heartbeat:
  - Fetches current data
  - Compares to stored previous values
  - Evaluates ALL conditions
  - Only alerts if ALL conditions true

---

### Pattern 5: Market Brief

**What it does:** Automated morning/evening market summaries.

**Setup:**
```
"Send market overview at 7am and 7pm on Telegram.

Include:
- BTC, ETH, SOL performance
- Any top 100 token that moved >10%
- Biggest volume gainers
- Overall sentiment analysis
```

**Example brief:**
```
📊 Crypto Market Brief - Feb 20, 7:00 AM

Majors:
- BTC: $67,234 (up 2.1% 24h)
- ETH: $3,456 (up 4.3% 24h)
- SOL: $123.45 (down 1.2% 24h)

Big Movers (24h):
- PEPE: up 23%
- ARB: up 15%
- AVAX: down 12%

Sentiment: Cautiously bullish. ETH leading, memes pumping.
```

---

## Ready-to-Use Templates

Copy these heartbeat templates to `~/openclaw/heartbeat/`:

**Available templates:**
- [Portfolio Guardian](../../examples/heartbeat-portfolio-guardian.md)
- [Whale Tracker](../../examples/heartbeat-whale-tracker.md)
- [Token Scout](../../examples/heartbeat-token-scout.md)
- [Market Brief](../../examples/heartbeat-market-brief.md)

**How to use:**
1. Copy template to `~/openclaw/heartbeat/`
2. Edit wallet addresses, criteria, timing
3. Agent executes automatically on schedule

---

## Security

✅ **Read-only access** - No trading, no transactions
✅ **No private keys** - Only public blockchain data
✅ **Open source** - [View code on GitHub](https://github.com/Flotapponnier/Crypto-date-openclaw)
✅ **VirusTotal verified** - Benign scan results

This skill only reads public data. It cannot:
- Execute trades
- Access wallets
- Sign transactions
- Transfer funds

---

## Rate Limits & Best Practices

**Free tier:** 100 requests/minute

**Optimization tips:**
- Set heartbeat to 30-60min intervals (not every minute)
- Use batch endpoints for multiple tokens
- Cache metadata (rarely changes)
- Only fetch data for active monitoring tasks

**Example efficient setup:**
- Portfolio checks: every 30min
- Whale watching: every 30min
- Token scout: every 6 hours
- Market brief: twice daily

---

## Troubleshooting

### Agent not monitoring

**Check:**
1. All 3 skills installed (mobula-prices, mobula-wallet, mobula-alerts)
2. API key set: `echo $MOBULA_API_KEY`
3. Agent restarted: `openclaw restart`
4. Monitoring task confirmed by agent

### Alerts not firing

**Possible causes:**
- Conditions not met (verify thresholds are reasonable)
- Rate limit hit (reduce monitoring frequency)
- Agent not running (check `openclaw status`)

### Too many alerts

**Adjust conditions:**
- Increase thresholds (5% → 10%)
- Add multi-condition logic (price + volume)
- Reduce monitoring frequency

---

## Related Skills

This skill requires:
- **[mobula-prices](../mobula-prices/)** - For price and market data
- **[mobula-wallet](../mobula-wallet/)** - For portfolio tracking

---

## Resources

- **Get API Key:** [mobula.io](https://mobula.io)
- **API Documentation:** [docs.mobula.io](https://docs.mobula.io)
- **Main Repository:** [GitHub](https://github.com/Flotapponnier/Crypto-date-openclaw)
- **Report Issues:** [GitHub Issues](https://github.com/Flotapponnier/Crypto-date-openclaw/issues)
- **Skill Documentation:** [SKILL.md](./SKILL.md)

---

## FAQ

**Q: How often does the agent check?**
A: Every heartbeat interval (default ~30min). You can adjust this in your agent settings.

**Q: Can I get instant alerts?**
A: Current heartbeat system checks every ~30min. For instant alerts, WebSocket support is on the roadmap.

**Q: Where do I receive alerts?**
A: Configure your agent to send alerts via Telegram, Discord, WhatsApp, or Slack.

**Q: How many monitoring tasks can I set?**
A: Unlimited, but stay within rate limits (100 req/min free tier). Each monitoring task may use 1-5 requests per heartbeat.

**Q: Can I monitor without being alerted?**
A: Yes. Set up daily/weekly summaries instead of real-time alerts.

---

## License

MIT License - See [LICENSE](../../LICENSE)

---

## Credits

- **Built by:** [Mobula](https://mobula.io)
- **For:** [OpenClaw](https://openclaw.ai)
- **Powered by:** OpenClaw heartbeat system


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)