🔔 ETHUSDT Smart Alert Bot

Real-time crypto market monitoring on Apify. Track Binance trading pairs for Volume Spikes, Price Drops, and Trailing Stop-loss Breaches – with instant Telegram notifications.

---

🎯 What does this Actor do?

This Actor connects to the Binance public API (no API key required) and monitors any supported trading pair (default: ETHUSDT) for three configurable market conditions:

Alert Type	Description
📊 Volume Spike	Fires when the 24-hour trading volume surges above a configurable threshold compared to the previous run's volume.
🔻 Price Drop	Fires when the 24-hour price change percentage drops below a negative threshold (e.g., -5%).
🛑 Trailing Stop-loss Breach	Tracks the highest recorded price (high watermark) across runs. Fires when the price retraces from the peak by more than the configured trailing stop distance.

When a condition is met, the bot:

1. Sends a formatted Telegram message with all relevant details.
2. Pushes a JSON record to the Apify Dataset for logging and export (CSV/JSON/Excel).

Key Features

• ✅ Stateful across runs – Remembers the high watermark and previous volume via Apify Key-Value Store.
• ✅ Zero API keys – Uses Binance's public endpoint (no authentication needed).
• ✅ Lightweight – Direct API calls via Axios, no browser or headless Chrome required.
• ✅ Dry Run mode – Test your configuration without sending Telegram messages.
• ✅ Schedule-ready – Designed to run on a cron schedule (e.g., every 5 minutes).

---

📥 Input Configuration

Field	Type	Default	Required	Description
tradingPair	string	ETHUSDT	No	Binance trading pair symbol
alertType	enum	All	No	Volume Spike, Price Drop, Trailing Stop-loss Breach, or All
thresholdPercentage	number	5	No	% change to trigger Volume Spike / Price Drop
trailingStopDistance	number	3	No	% drop from peak to trigger Trailing Stop-loss
telegramBotToken	string	—	Yes*	Telegram Bot API token
telegramChatId	string	—	Yes*	Telegram chat/group/channel ID
enableDryRun	boolean	false	No	Skip Telegram delivery (for testing)

*Required when enableDryRun is false.

Example Input (JSON)

{
    "tradingPair": "ETHUSDT",
    "alertType": "All",
    "thresholdPercentage": 5,
    "trailingStopDistance": 3,
    "telegramBotToken": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
    "telegramChatId": "-1001234567890",
    "enableDryRun": false
}

---

📤 Output

Dataset Record Schema

Every triggered alert pushes a record to the default Apify Dataset. You can download the full log as JSON, CSV, or Excel from the Actor Run page.

{
    "timestamp": "2026-04-30T14:30:00.000Z",
    "pair": "ETHUSDT",
    "currentPrice": 1842.55,
    "triggerReason": "Volume Spike",
    "priceChangePct24h": 2.34,
    "volume24h": 125430.12,
    "volumeChangePct": 8.72,
    "highWatermark": 1900.00,
    "thresholdPct": 5
}

Telegram Message Example

📊 ALERT – VOLUME SPIKE

Pair:        ETHUSDT
Price:       $1,842.55
24h Change:  +2.34%
24h Volume:  125.43K
Threshold:   5%

🕒 2026-04-30T14:30:00.000Z

---

🤖 How to get your Telegram Bot Token

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the instructions.
3. BotFather will give you a token like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ.
4. Copy this token and paste it in the telegramBotToken input field.

How to find your Chat ID

1. Start a conversation with your new bot (send any message).
2. Open this URL in your browser (replace <TOKEN> with your bot token):

   https://api.telegram.org/bot<TOKEN>/getUpdates
   

3. Look for "chat":{"id": 123456789, ...} in the JSON response.
4. Copy the numeric id and paste it in the telegramChatId input field.

Tip: For group chats, add the bot to the group, send a message mentioning the bot, and repeat step 2. Group IDs are negative numbers (e.g., -1001234567890).

---

⏰ Recommended Schedule

For optimal monitoring, schedule this Actor to run on a short interval:

Use Case	Cron Expression	Frequency
Active trading	*/5 * * * *	Every 5 minutes
Swing trading	*/30 * * * *	Every 30 minutes
Daily check	0 */4 * * *	Every 4 hours
Low-cost monitoring	0 0 * * *	Once a day

Cost note: Each run uses only ~32 MB RAM and completes in < 5 seconds (API call only, no browser). At the 5-minute interval, monthly cost is approximately $1–2 on the Apify platform.

---

🏗️ Architecture

┌──────────────────────────────┐
│         Apify Scheduler      │
│      (cron: */5 * * * *)     │
└──────────┬───────────────────┘
           │ triggers
           ▼
┌──────────────────────────────┐
│     ETHUSDT Smart Alert Bot  │
│                              │
│  1. Load state (KV Store)    │
│  2. GET /api/v3/ticker/24hr  │──► Binance API
│  3. Evaluate conditions      │
│  4. Push alerts → Dataset    │──► Apify Dataset (CSV/JSON)
│  5. Send alerts → Telegram   │──► Telegram Bot API
│  6. Save state (KV Store)    │
└──────────────────────────────┘

State Persistence

The Actor uses the Apify Key-Value Store to persist state across runs:

Key	Description
highWatermark	Highest price recorded since last Trailing Stop breach
previousVolume24h	24h volume from the previous run (for spike comparison)
lastPrice	Last observed price
lastCheckedAt	ISO timestamp of the last successful check

---

🔧 Local Development

# Clone the repo
git clone <repo-url>
cd ethusdt-smart-alert-bot

# Install dependencies
npm install

# Create local input
mkdir -p storage/key_value_stores/default
cat > storage/key_value_stores/default/INPUT.json << 'EOF'
{
    "tradingPair": "ETHUSDT",
    "alertType": "All",
    "thresholdPercentage": 2,
    "trailingStopDistance": 3,
    "enableDryRun": true
}
EOF

# Run locally
npm start

---

📜 Changelog

v1.0.0

• Initial release.
• Volume Spike, Price Drop, and Trailing Stop-loss Breach detection.
• Telegram HTML alerts.
• Apify Dataset logging.
• Stateful Key-Value Store persistence.

---

📄 License

ISC © CryptoDevLabs