Build a Telegram alert for traders climbing the fomo leaderboard

The fastest-moving traders on a leaderboard are often the most interesting ones to watch. This tutorial builds a bot that checks the 24-hour fomo leaderboard, finds traders who jumped at least ten places, and posts them to a Telegram chat with their verified wallet.

It uses one API call per check, and the free plan is enough to try it.

What you need

• An API key, and Python 3.9+ with requests.
• A Telegram bot token from @BotFather and the chat id to post to.

How it works

Every leaderboard row carries previousRank, the trader’s rank in the capture before. So the bot does not need to store history: one call tells it who climbed. It only has to remember which capture it has already processed, so it does not post the same move twice.

The bot

import os, time, requests

API = "https://provadata.com"
KEY = os.environ["API_KEY"]
TG = f"https://api.telegram.org/bot{os.environ['TG_TOKEN']}/sendMessage"
CHAT = os.environ["TG_CHAT_ID"]

MIN_JUMP = 10
EVERY = 20 * 60  # seconds

api = requests.Session()
api.headers["Authorization"] = f"Bearer {KEY}"

def climbers(board):
    for t in board["traders"]:
        prev = t["previousRank"]
        if prev is None or prev - t["rank"] < MIN_JUMP:
            continue
        proven = [w for w in t["walletList"] if w["status"] == "verified"]
        if not proven:
            continue  # only alert on traders whose wallet is proven
        yield t, prev, proven[0]["address"]

def post(text):
    requests.post(TG, json={"chat_id": CHAT, "text": text, "disable_web_page_preview": True}, timeout=20)

last_capture = None
while True:
    r = api.get(f"{API}/v2/leaderboard/24h", timeout=30)
    if r.ok:
        board = r.json()
        if board["capturedAt"] != last_capture:
            last_capture = board["capturedAt"]
            for t, prev, wallet in climbers(board):
                pnl = t["pnlUsd"]
                pnl_text = "PnL unknown" if pnl is None else f"PnL ${pnl:,.0f}"
                post(f"@{t['handle']} climbed {prev} → {t['rank']} on the 24h board. {pnl_text}.\nWallet: {wallet}")
    elif r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "60")))
        continue
    time.sleep(EVERY)

Budget

One leaderboard call is 100 credits. Checking every 20 minutes is 72 calls a day, about 216,000 credits a month, which fits the Starter plan’s 2,500,000. The free plan’s 25,000 cover 250 checks a month: enough to try the bot, or to run it a few times a day with a larger EVERY. Failed calls cost nothing, so outages do not eat your budget.

Ideas to extend it

• Watch the 7d board too, with a smaller jump threshold.
• Alert on newcomers: previousRank is None and a rank inside the top 20.
• Feed the verified address into your own on-chain listener to see the trader’s next buy as it happens.