EVM Guardrails Telegram Bot
What it does This Telegram bot analyzes ERC-20 tokens across Ethereum, Base, BSC, Arbitrum, and Polygon. It can also execute DEX trades with strict safety guardrails and a mandatory confirmation step.
Key features
- Token analysis: metadata (name, symbol, decimals, total supply), holder concentration (Top 10/Top 20).
- Holder reports: best-effort top holder table with balance and percent of supply.
- Wallet holder check: balance and percent of supply for a given address.
- Safer trading flow: quotes, simulation, confirmation, slippage caps, max spend cap, cooldown, token/router allowlists.
- AI explanations via CookMyBots AI Gateway for concise risk notes (no direct OpenAI calls).
- Long-term memory in MongoDB when MONGODB_URI is set; in-memory fallback if missing.
Architecture
- src/index.js: boot, env sanity logs, deleteWebhook, runner start with 409 backoff.
- src/bot.js: grammY bot, session middleware, command loader, catch-all routing safety.
- src/commands/*.js: command modules.
- src/lib/db.js: Mongo singleton.
- src/lib/memory.js: memory_messages storage + in-memory fallback.
- src/lib/ai.js: CookMyBots AI Gateway wrapper.
- src/services/evm/*.js: chain registry, providers, ERC-20 calls, holder scan.
- src/services/trading/*.js: allowlists, quoting, simulation, swap execution, pending orders.
Setup
-
Install dependencies npm install
-
Create .env Copy .env.sample to .env and fill at least:
- TELEGRAM_BOT_TOKEN
- COOKMYBOTS_AI_ENDPOINT
- COOKMYBOTS_AI_KEY
- (Optional) Add MongoDB
- MONGODB_URI If missing, the bot still runs but uses in-memory memory and logs a warning.
- (Optional) Configure chain RPCs Provide one or more of:
- EVM_RPC_ETHEREUM
- EVM_RPC_BASE
- EVM_RPC_BSC
- EVM_RPC_ARBITRUM
- EVM_RPC_POLYGON
Run
- Dev: npm run dev
- Start: npm start
Deployment (Render-style)
- Set the environment variables in the service.
- The bot runs in long-polling mode and clears webhooks on boot.
- If two instances overlap during deploy, the bot will handle Telegram 409 conflicts with backoff and keep running.
Public commands
- /start
- /help
- /reset
- /analyze <chain?> <token_address>
- /holders <token_address> [limit]
- /holder [token_address]
- /quote <chain?> <token_in> <token_out>
- /buy <chain?>
- /sell <chain?>
Trading notes Trading is disabled unless:
- TRADING_ENABLED=true
- TRADING_PRIVATE_KEY is set
- Tokens and routers are allowlisted via TRUSTED_TOKENS_JSON and TRUSTED_ROUTERS_JSON
This bot never logs private keys. It simulates swaps before execution and always requires inline confirmation.
Troubleshooting
- Bot not responding
- Confirm TELEGRAM_BOT_TOKEN is set.
- Check logs for 409 conflicts; the bot auto-retries.
- Chain not configured
- If the RPC env var for a chain is missing, commands for that chain will respond that it is not configured.
- Holder results are partial
- Full top-holder enumeration is not directly queryable from ERC-20. This bot uses best-effort Transfer log scanning within a bounded window and will label partial results.
Extending Add new commands under src/commands and they will be auto-registered by src/commands/loader.js.