Integrations
Telegram Bot
TradeClaw ships with a production-ready Telegram bot. Subscribers receive formatted signal alerts the moment they are generated — with entry, TP levels, SL, and a confidence badge. Setup takes under five minutes.
BotFather Setup
Create a bot
Open Telegram and message @BotFather. Send /newbot and follow the prompts to choose a name and username.
Copy the token
BotFather will reply with a token like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Copy it — this is your TELEGRAM_BOT_TOKEN.
Set the webhook URL
After deploying TradeClaw, point Telegram to your instance so it can receive updates.
curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook" \
-H "Content-Type: application/json" \
-d '{"url":"https://your-instance.com/api/telegram/webhook","allowed_updates":["message"]}'Only message updates are needed — the bot handles commands (/start, /subscribe, /signals, …) and broadcasts to the public channel. There are no gated groups and no join approvals.
Environment Variables
| Variable | Required | Description |
|---|---|---|
| TELEGRAM_BOT_TOKEN | Required | Token from @BotFather. Format: 1234567890:ABC... |
| TELEGRAM_WEBHOOK_URL | Required | Full URL to your /api/telegram/webhook endpoint |
| TELEGRAM_ADMIN_CHAT_ID | Optional | Chat ID that receives error notifications |
TELEGRAM_BOT_TOKEN=110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
TELEGRAM_WEBHOOK_URL=https://your-instance.com/api/telegram/webhook
TELEGRAM_ADMIN_CHAT_ID=123456789Bot Commands
The bot responds to the following commands. Send them in any private chat or group where the bot is a member.
/startInitialize the bot and display a welcome message with quick-start instructions.
/subscribeSubscribe to signal alerts. You will receive a message for every new signal that meets your filter criteria.
/unsubscribeStop receiving signal alerts. Your filter settings are preserved.
/signalsFetch the last 10 active signals and display them inline.
/pairsList all supported trading pairs with their current direction and confidence.
/settingsView and update your subscriber filter (pairs, minimum confidence, direction).
/helpShow the full command reference and support link.
Subscriber Filtering
Each subscriber can configure filters so they only receive relevant alerts. Filters are set via /settings or by calling the API directly.
Pair filter
Receive alerts only for specific symbols (e.g. XAUUSD, BTCUSD). Defaults to all pairs.
Min confidence
Only receive signals above a threshold (e.g. 75). Range 0–100. Defaults to 65.
Direction filter
Only BUY, only SELL, or both. Defaults to both.
Timeframe filter
Specific timeframes only (M15, H1, H4, D1). Defaults to all.
API Endpoints
/api/telegram/webhookTelegram update receiver — set this as your bot webhook URL.
/api/telegram/sendSend a message to a specific chat ID.
chatId, text, parseMode
/api/telegram/statusCheck bot connection and webhook registration status.
Signal Broadcasting
When a new signal is generated, TradeClaw calls an internal broadcaster that iterates all active subscribers, applies their filters, and sends a formatted message to matching chat IDs.
// Example message sent to each subscriber
*🟢 BUY Signal — XAUUSD*
📊 Timeframe: H1
💪 Confidence: 87%
💰 Entry: 2345\.50
🎯 TP1: 2360\.00
🎯 TP2: 2374\.50
🎯 TP3: 2389\.00
🛑 SL: 2331\.00
_Generated at 14:30 UTC_Rate Limit
The Telegram Bot API allows up to 30 messages per second. TradeClaw queues broadcasts and dispatches them within this limit. Channels with large subscriber counts batch sends automatically.
Channel Auto-Broadcast
TradeClaw can automatically post the top 3 signals to a public or private Telegram channel every 4 hours. This is powered by a Vercel Cron job and requires two additional environment variables.
| Variable | Required | Description |
|---|---|---|
| TELEGRAM_CHANNEL_ID | Required | Channel username (@mychannel) or numeric ID (-100...) |
| CRON_SECRET | Optional | Bearer token for cron auth — Vercel sets this automatically |
Create a Telegram channel
Create a public or private channel. Add your bot as an administrator with permission to post messages.
Get the channel ID
For public channels, use @yourchannel. For private channels, forward a message to @userinfobot to get the numeric ID (starts with -100).
Set the environment variable
Add TELEGRAM_CHANNEL_ID to your .env file. The cron job will pick it up automatically.
TELEGRAM_CHANNEL_ID=@your_channel_name
# or for private channels:
# TELEGRAM_CHANNEL_ID=-1001234567890/api/telegram/broadcastTrigger an immediate broadcast of top 3 signals to the configured channel.
/api/telegram/broadcastCheck broadcast status: last time, next scheduled time, total count.
/api/cron/telegramVercel Cron endpoint — called every 4 hours automatically.
Vercel Cron Schedule
The broadcast runs on the schedule 0 */4 * * * (every 4 hours at minute 0). You can also trigger it manually from the /telegram settings page or by calling POST /api/telegram/broadcast.