DEV Community

Cover image for Build a Crypto Whale Alert Telegram Bot in Python (Under 50 Lines)
DeepBlueAlpha
DeepBlueAlpha

Posted on Originally published at deepbluealpha.io

Build a Crypto Whale Alert Telegram Bot in Python (Under 50 Lines)

#python #telegram #cryptocurrency #tutorial

Every serious crypto trader wants to know when whales move. The problem: most whale tracking APIs charge $200+/month, and the free ones give you delayed, incomplete data.

Deep Blue Alpha tracks 20,000+ Ethereum whale wallets in real time. Their API gives you raw transaction data -- wallet address, token, direction, USD value, timestamp -- as JSON. In this tutorial, we will wire that data into a Telegram bot that pings you whenever a whale makes a move above your threshold.

The finished bot is under 50 lines of Python.

What we are building

A Python script that:

  1. Polls the DBA transactions endpoint every 60 seconds
  2. Filters for trades above a USD threshold (e.g., $100K)
  3. Sends a formatted alert to your Telegram chat

No frameworks, no dependencies beyond requests and python-telegram-bot. Runs on any machine with Python 3.8+.

Prerequisites

Step 1: Create your Telegram bot

Open Telegram, message @BotFather, and send /newbot. Pick a name and username. BotFather gives you a token like 7123456789:AAH.... Save it.

Next, get your chat ID. Message your new bot, then run:

curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Enter fullscreen mode Exit fullscreen mode

Find "chat":{"id": 123456789} in the response. That number is your CHAT_ID.

Step 2: Install dependencies 

pip install requests
Enter fullscreen mode Exit fullscreen mode

That is the only dependency. We will use raw HTTP for Telegram (no SDK needed for sending messages).

Step 3: Understand the API

The DBA API lives at https://deepbluealpha.io/api/v1. Authentication is via an X-API-Key header. Every response follows this shape:

{
  "data": { ... },
  "meta": {
    "tier": "whale",
    "endpoint": "/api/v1/transactions",
    "generated_at": "2026-09-16T14:00:00+00:00"
  }
}
Enter fullscreen mode Exit fullscreen mode

The endpoint we care about is GET /api/v1/transactions. It returns recent whale trades, newest first:

{
  "data": {
    "transactions": [
      {
        "id": 1891204,
        "tx_hash": "0xabc...def",
        "wallet": "0x1234...5678",
        "token": "LINK",
        "direction": "BUY",
        "action": "SWAP_BUY",
        "usd_value": 487221.50,
        "timestamp": "2026-09-16T13:42:18"
      }
    ],
    "next_before_id": 1891180
  }
}
Enter fullscreen mode Exit fullscreen mode

Each transaction has a direction (BUY or SELL), a token symbol, and the usd_value of the trade. The next_before_id field lets you paginate backward through history.

Step 4: The complete bot

Create a file called whale_bot.py:

import time
import requests

# ── Config ──────────────────────────────────────────────
DBA_API_KEY = "dba_your_key_here"
TG_BOT_TOKEN = "7123456789:AAH_your_token_here"
TG_CHAT_ID = "123456789"
MIN_USD = 100_000          # alert threshold
POLL_INTERVAL = 60         # seconds between polls

API_URL = "https://deepbluealpha.io/api/v1/transactions"
TG_URL = f"https://api.telegram.org/bot{TG_BOT_TOKEN}/sendMessage"

seen_ids = set()

def fetch_trades():
    """Pull the latest whale transactions from DBA."""
    headers = {"X-API-Key": DBA_API_KEY}
    resp = requests.get(API_URL, headers=headers, params={"limit": 50})
    resp.raise_for_status()
    return resp.json()["data"]["transactions"]

def send_alert(tx):
    """Send a Telegram message for one whale trade."""
    arrow = "⬆️" if tx["direction"] == "BUY" else "⬇️"
    msg = (
        f"{arrow} *Whale {tx['direction']}*\n"
        f"Token: `{tx['token']}`\n"
        f"Value: ${tx['usd_value']:,.0f}\n"
        f"Action: {tx.get('action', 'N/A')}\n"
        f"Wallet: `{tx['wallet'][:10]}...`\n"
        f"[View on DBA](https://deepbluealpha.io/feed)"
    )
    requests.post(TG_URL, json={
        "chat_id": TG_CHAT_ID,
        "text": msg,
        "parse_mode": "Markdown",
        "disable_web_page_preview": True,
    })

def main():
    print(f"Whale bot running. Alerting on trades >= ${MIN_USD:,}")
    while True:
        try:
            trades = fetch_trades()
            for tx in trades:
                if tx["id"] not in seen_ids and tx["usd_value"] >= MIN_USD:
                    send_alert(tx)
                seen_ids.add(tx["id"])
            # keep memory bounded
            if len(seen_ids) > 5000:
                seen_ids.clear()
        except Exception as e:
            print(f"Error: {e}")
        time.sleep(POLL_INTERVAL)

if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

That is 47 lines. Run it:

python3 whale_bot.py
Enter fullscreen mode Exit fullscreen mode

Every 60 seconds, it fetches the latest 50 whale transactions, filters for trades at or above your threshold, and sends a Telegram message for each new one.

Step 5: Keep it running

For a quick background process:

nohup python3 whale_bot.py > whale_bot.log 2>&1 &
Enter fullscreen mode Exit fullscreen mode

For something more durable, create a systemd service (Linux):

# /etc/systemd/system/whale-bot.service
[Unit]
Description=DBA Whale Alert Bot
After=network.target

[Service]
ExecStart=/usr/bin/python3 /path/to/whale_bot.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

Then sudo systemctl enable --now whale-bot.

What you could add next

  • Token filter -- only alert on specific tokens (add a WATCH_TOKENS = {"LINK", "AAVE", "UNI"} set and check membership)
  • Volume spike detection -- hit /api/v1/top-tokens?tf=1H and alert when a token's hourly net flow crosses a threshold
  • Multiple chats -- broadcast to a Telegram channel instead of a private chat (use the channel's @handle as the chat ID)
  • Conviction scores -- use /api/v1/token/{symbol}/flow to add 24h/7d/30d context to each alert

The full API documentation lists all available endpoints.

Wrapping up

The whale flow API at deepbluealpha.io tracks 20,000+ Ethereum wallets in real time. The bot above is one way to consume it -- you could just as easily pipe the data into a spreadsheet, a Discord webhook, or a quant model. The transactions endpoint gives you the raw material; what you build with it is up to you.

Whale flow data is observational, not predictive. This tutorial is for educational purposes only. Not financial advice. DYOR.

Deep Blue Alpha is an Ethereum whale intelligence platform tracking 10,000+ whale wallets in real time. This article is for informational purposes only and does not constitute financial advice. NFA/DYOR.

Track whale activity for free at deepbluealpha.io

Top comments (0)