A Telegram bot that brings on-chain analytics to your fingertips. Simply send a token's contract address along with the chain, and the bot delivers visualizations and metrics straight to your chat — powered by Bubblemaps.
- 📍 Bubble Map Screenshot — Instantly generates a map of token holder clusters.
- 📊 Analytics Dashboard — Market cap, price, volume, and more.
- 🧠 Decentralization Score — See how evenly a token is distributed.
- 💎 Top Holders Info — Know who holds what.
- 🌍 Supports multiple chains (via
[chain]argument) [Supported chains - eth, bsc, ftm, avax, cro, arbi, poly, base, sol, sonic]
- Language: TypeScript
- Server: Express.js
- Bot Framework: node-telegram-bot-api
- Infra: AWS EC2 (High performance deployment)
- Other: Puppeteer (for screenshots), Gemini API (for AI capabilities)
/start
Welcome message
/help
Show this help message
/tokendetail <token address>
Get token details
/analytics <chain> <token address>
Get basic token info, decentralisation score, top holders info and map link
/get2wpricechart <token address>
Get 2-week price and volume chart
/tokenbalances <wallet address>
Get token balances for a wallet address
/walletpnl <wallet address>
Get comprehensive PnL analysis for a wallet address
- Clone the Repo
git clone https://github.com/your-username/bubblemaps-telegrambot.git
cd bubblemaps-telegrambot- Install Dependencies
npm install- Set Up Environment Variables
Create a
.envfile in the root directory and fill it with:
BOT_TOKEN=your-telegram-bot-token
GEMINI_API_KEY=your-gemini-api-key- Build and Run the Bot
npm run build
npm run startBelow are example outputs for each supported command:
| Command | Output(s) |
|---|---|
/tokenbalances |
 |
/analytics |
  |
/walletpnl |
  |
/tokendetail |
  |
/get2wpricechart |
 |
We welcome PRs and contributions! Just follow these general rules:
- ✅ Follow conventional code style and naming.
- 🧪 Test your changes locally.
- 📄 Open an issue before big features.
🟢 Bot is live! Find it on Telegram at @Bubblemaps_orbot