Telegram Bot Setup Guide

NeuraTrade’s Telegram bot provides real-time notifications, trading status updates, and interactive command-based control of your autonomous trading system.

Overview

The Telegram service integrates with NeuraTrade’s backend API to deliver:

Real-time notifications for trading events, risk alerts, and system status
Interactive commands to control trading modes, check balances, and monitor positions
Autonomous mode controls to start/pause trading and view AI reasoning
Quest progress tracking for gamified trading achievements
Wallet management for balance checks and position monitoring

Prerequisites

Active Telegram account
Running NeuraTrade backend (see Native Deployment)
Access to create Telegram bots via @BotFather

Step 1: Create Telegram Bot

Create your bot using Telegram’s official BotFather.

Open BotFather

Open Telegram and search for @BotFather or click the link to start a chat.

Create new bot

Send the /newbot command:

/newbot

BotFather will ask for a name and username for your bot.

Set bot name

Choose a display name (can contain spaces):

NeuraTrade Bot

Set bot username

Choose a unique username (must end in ‘bot’):

neuratrade_yourname_bot

The username must be unique across all Telegram bots. If taken, try adding numbers or your name.

Save bot token

BotFather will respond with your bot token:

Done! Congratulations on your new bot...

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

Keep this token secret! Anyone with this token can control your bot. Never commit it to version control.

Save this token - you’ll need it for configuration.

Step 2: Configure Bot Settings

Optimize your bot’s appearance and behavior.

Set Bot Description

/setdescription @neuratrade_yourname_bot

Example description:

Autonomous trading assistant powered by NeuraTrade. 
Monitor your portfolio, control trading modes, and receive real-time alerts.

Set Bot About Text

/setabouttext @neuratrade_yourname_bot

Example:

NeuraTrade AI Trading Bot - Your 24/7 trading companion

Set Bot Profile Picture

/setuserpic @neuratrade_yourname_bot

Then upload a 512x512 PNG image (the NeuraTrade logo works great!). The Telegram service automatically registers commands with Telegram when it starts. You can also set them manually:

/setcommands @neuratrade_yourname_bot

Then paste this command list:

start - Initialize bot and show welcome message
help - Show available commands and usage
menu - Display interactive menu
status - Show autonomous trading status
wallet - View account balance and positions
performance - Show trading performance metrics
monitor - View real-time monitoring dashboard
liquidate - Emergency liquidate position
liquidate_all - Emergency liquidate all positions
begin - Start autonomous trading mode
pause - Pause autonomous trading
settings - Configure bot preferences
ai - AI model and reasoning controls

The bot automatically updates the command menu when started in polling mode. The commands above are registered via the grammY framework.

Step 3: Configure NeuraTrade

Add your bot token to NeuraTrade’s configuration.

Environment Variable Method

Export the token as an environment variable:

export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890"

Add to your shell profile for persistence:

# NeuraTrade Telegram Bot
export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890"

Config File Method

Edit ~/.neuratrade/config.json:

{
  "telegram": {
    "bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890",
    "use_polling": true,
    "port": 3002
  },
  "services": {
    "telegram": {
      "enabled": true,
      "bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890",
      "api_base_url": "http://localhost:8080",
      "use_polling": true,
      "port": 3002
    }
  }
}

The config file supports both root-level telegram and nested services.telegram for backwards compatibility.

Step 4: Choose Deployment Mode

NeuraTrade supports two Telegram bot deployment modes.

Polling Mode (Recommended for Development)

Polling mode is simpler and works behind firewalls/NAT. Configuration:

export TELEGRAM_USE_POLLING=true

Or in config.json:

{
  "telegram": {
    "use_polling": true
  }
}

Advantages:

No public IP or domain required
Works behind NAT/firewalls
Easier local development
Simpler setup

Disadvantages:

Higher latency (1-2 second polling interval)
More resource usage (constant polling)
Not recommended for production at scale

How it works: The Telegram service continuously polls Telegram’s API for new updates:

bot.start({
  onStart: (botInfo) => {
    logger.info("Bot polling started", {
      botId: botInfo.id,
      username: botInfo.username
    });
  }
});

Reference: services/telegram-service/index.ts:194

Webhook Mode (Recommended for Production)

Webhook mode is more efficient and has lower latency. Requirements:

Public domain with HTTPS
Valid SSL certificate
Reverse proxy (nginx/Caddy)

Configuration:

export TELEGRAM_USE_POLLING=false
export TELEGRAM_WEBHOOK_URL="https://yourdomain.com/telegram/webhook"
export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

Or in config.json:

{
  "telegram": {
    "use_polling": false,
    "webhook_url": "https://yourdomain.com/telegram/webhook",
    "webhook_secret": "your-random-secret-here"
  }
}

Advantages:

Lower latency (instant updates)
More efficient (no polling)
Better for production scale
Lower resource usage

Disadvantages:

Requires public domain + HTTPS
More complex setup
Certificate management

How it works: Telegram sends updates directly to your webhook endpoint:

app.post(config.webhookPath, async (c) => {
  // Verify webhook secret
  if (config.webhookSecret) {
    const provided = c.req.header("X-Telegram-Bot-Api-Secret-Token");
    if (!provided || provided !== config.webhookSecret) {
      return c.json({ error: "Unauthorized" }, 401);
    }
  }
  
  const update = await c.req.json();
  await bot.handleUpdate(update);
  return c.json({ ok: true });
});

Reference: services/telegram-service/index.ts:121

nginx Configuration Example

For webhook mode with nginx reverse proxy:

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    
    location /telegram/webhook {
        proxy_pass http://127.0.0.1:3002/telegram/webhook;
        proxy_http_version 1.1;
        proxy_set_header X-Telegram-Bot-Api-Secret-Token $http_x_telegram_bot_api_secret_token;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Step 5: Start Telegram Service

Start the service and verify bot connectivity.

Via Gateway CLI

neuratrade gateway start

The gateway starts the Telegram service automatically and monitors its health.

Standalone Mode (Development)

For development, you can run the Telegram service directly:

cd services/telegram-service
bun run index.ts

Expected Output:

Telegram service started {
  port: 3002,
  hostname: "0.0.0.0",
  mode: "polling"
}
Starting bot in polling mode
Webhook deleted successfully
Starting polling...
Bot polling started successfully {
  botId: 1234567890,
  username: "neuratrade_yourname_bot"
}

Verify Service Health

curl http://localhost:3002/health

Response:

{
  "status": "healthy",
  "service": "telegram-service",
  "bot_active": true
}

If TELEGRAM_BOT_TOKEN is not configured, the service returns:

{
  "status": "degraded",
  "service": "telegram-service",
  "error": "TELEGRAM_BOT_TOKEN not configured",
  "bot_active": false
}

The service runs in degraded mode (health endpoint only) until the token is configured.

Step 6: Bind Your Chat ID

Link your Telegram account to NeuraTrade for personalized notifications.

Get your chat ID

Start a conversation with your bot:

Search for your bot username in Telegram
Click “Start” or send /start
Your chat ID will be in the welcome message

Alternatively, use @userinfobot:

Send any message to @userinfobot
It replies with your user ID (this is your chat ID)

Generate binding code

Generate a one-time authentication code:

neuratrade generate-auth-code

Or via API:

curl -X POST http://localhost:8080/api/v1/telegram/generate-binding-code \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -d '{"user_id": "operator"}'

Response:

{
  "success": true,
  "message": "Binding code generated successfully",
  "user_id": "operator",
  "expires_at": "2026-03-03T11:00:00Z"
}

The code is printed in the backend logs or returned in the response.

Bind via CLI

Use the CLI to bind your chat:

neuratrade operator bind --auth-code ABC123XYZ --chat-id 123456789

Output:

✅ Operator binding successful!
Saved chat ID to /home/user/.neuratrade/config.json

Test binding

Send a command to your bot:

/status

If bound correctly, you’ll receive your trading status.

Binding codes expire after 15 minutes for security. Generate a new code if expired.

Step 7: Test Bot Commands

Verify your bot responds to commands.

Basic Commands

/start
/help
/menu
/status

Initializes the bot and shows welcome message:

/start

Bot Response:

Welcome to NeuraTrade! 🤖

Your autonomous trading assistant is ready.
Use /help to see available commands.

Shows available commands:

/help

Lists all commands with descriptions.

Displays interactive menu with buttons:

/menu

Shows inline keyboard with quick actions.

Shows autonomous trading status:

/status

Bot Response:

📊 Autonomous Trading Status

Mode: PAUSED
Uptime: 2h 15m
Active Positions: 0
24h PnL: +$0.00

Use /begin to start trading.

Trading Commands

/wallet
/begin
/pause

View account balance:

/wallet

Response:

💰 Wallet Balance

Total: $10,000.00 USDT
Available: $10,000.00
In Orders: $0.00

Positions: 0 open

Start autonomous trading:

/begin

Runs readiness checks before starting:

⏳ Running readiness checks...

✅ Exchange connectivity
✅ API permissions
✅ Balance requirements
✅ Risk limits configured

🚀 Autonomous trading started!

Pause trading:

/pause

Response:

⏸️ Autonomous trading paused.

Open positions remain active.
Use /begin to resume.

Monitoring Commands

/performance

Shows trading performance metrics:

📈 Performance Report

Total Trades: 42
Win Rate: 65.5%
Profit Factor: 1.8

24h PnL: +$125.50 (+1.26%)
7d PnL: +$890.00 (+9.12%)
30d PnL: +$3,245.00 (+48.2%)

Best Trade: +$89.50
Worst Trade: -$32.00

Troubleshooting

Bot Not Responding

Invalid bot token

Test your token:

curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe

If invalid:

{
  "ok": false,
  "error_code": 401,
  "description": "Unauthorized"
}

Generate a new token from @BotFather:

/token @neuratrade_yourname_bot

Service not running

Check service status:

neuratrade gateway status

Look for:

✅ Telegram Service: Running (PID: 12347)

Check logs:

tail -f ~/.neuratrade/logs/telegram.log

Polling vs Webhook conflict

If webhook is set but you’re using polling mode:

# Delete webhook
curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook

# Restart service
neuratrade gateway stop
neuratrade gateway start

Commands Return Errors

Chat ID not bound

Bind your chat ID:

neuratrade operator bind --auth-code CODE --chat-id YOUR_CHAT_ID

Backend API unreachable

Verify backend is running:

curl http://localhost:8080/health

Check TELEGRAM_API_BASE_URL:

echo $TELEGRAM_API_BASE_URL
# Should be: http://localhost:8080

Permission errors

Check ADMIN_API_KEY is set:

echo $ADMIN_API_KEY

Telegram service needs this to call internal backend endpoints.

Webhook Issues

Webhook not receiving updates

Check webhook status:

curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo

Look for:

{
  "ok": true,
  "result": {
    "url": "https://yourdomain.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "last_error_date": 0
  }
}

If pending_update_count is growing, Telegram can’t reach your webhook.

SSL certificate errors

Verify your SSL certificate:

curl -v https://yourdomain.com/telegram/webhook

Telegram requires:

Valid SSL certificate (Let’s Encrypt works)
Certificate chain must be complete
No self-signed certificates

Webhook secret mismatch

The service checks X-Telegram-Bot-Api-Secret-Token header.If failing, check your secret:

echo $TELEGRAM_WEBHOOK_SECRET

Update webhook with correct secret:

curl -X POST https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook \
  -d "url=https://yourdomain.com/telegram/webhook" \
  -d "secret_token=$TELEGRAM_WEBHOOK_SECRET"

Configuration Reference

Complete Telegram configuration options:

~/.neuratrade/config.json

{
  "telegram": {
    "enabled": true,
    "bot_token": "YOUR_BOT_TOKEN",
    "use_polling": true,
    "port": 3002,
    "webhook_url": "https://yourdomain.com/telegram/webhook",
    "webhook_path": "/telegram/webhook",
    "webhook_secret": "your-secret",
    "api_base_url": "http://localhost:8080",
    "chat_id": "123456789"
  },
  "services": {
    "telegram": {
      "enabled": true,
      "bot_token": "YOUR_BOT_TOKEN",
      "use_polling": true,
      "port": 3002,
      "api_base_url": "http://localhost:8080"
    }
  }
}

Environment Variables

Variable	Default	Description
`TELEGRAM_BOT_TOKEN`	-	Required. Bot token from @BotFather
`TELEGRAM_USE_POLLING`	`true`	Use polling mode (vs webhook)
`TELEGRAM_PORT`	`3002`	Service HTTP port
`TELEGRAM_WEBHOOK_URL`	-	Public webhook URL (webhook mode only)
`TELEGRAM_WEBHOOK_PATH`	`/telegram/webhook`	Webhook endpoint path
`TELEGRAM_WEBHOOK_SECRET`	-	Secret token for webhook validation
`TELEGRAM_API_BASE_URL`	`http://localhost:8080`	Backend API URL
`ADMIN_API_KEY`	-	Admin API key for internal endpoints
`BIND_HOST`	`0.0.0.0`	Service bind address

Source Code Reference

Key implementation files:

services/telegram-service/index.ts:1 - Main service entry point
services/telegram-service/config.ts:140 - Configuration loader
services/telegram-service/src/commands/ - Command handlers
services/telegram-service/bot-handlers.ts - Bot event handlers
services/telegram-service/index.ts:56 - Health endpoint
services/telegram-service/index.ts:121 - Webhook handler

Next Steps

Gateway CLI

Learn gateway commands

Monitoring

Monitor system health

Autonomous Trading

Start autonomous trading

API Reference

Telegram API endpoints

Get Started

Core Features

Configuration

Guides

​Telegram Bot Setup Guide

​Overview

​Prerequisites

​Step 1: Create Telegram Bot

​Step 2: Configure Bot Settings

​Set Bot Description

​Set Bot About Text

​Set Bot Profile Picture

​Configure Commands Menu

​Step 3: Configure NeuraTrade

​Environment Variable Method

​Config File Method

​Step 4: Choose Deployment Mode

​Polling Mode (Recommended for Development)

​Webhook Mode (Recommended for Production)

​nginx Configuration Example

​Step 5: Start Telegram Service

​Via Gateway CLI

​Standalone Mode (Development)

​Verify Service Health

​Step 6: Bind Your Chat ID

​Step 7: Test Bot Commands

​Basic Commands

​Trading Commands

​Monitoring Commands

​Troubleshooting

​Bot Not Responding

​Commands Return Errors

​Webhook Issues

​Configuration Reference

​Environment Variables

​Source Code Reference

​Next Steps

Gateway CLI

Monitoring

Autonomous Trading

API Reference

Build docs developers (and LLMs) love

Telegram Bot Setup Guide

Overview

Prerequisites

Step 1: Create Telegram Bot

Step 2: Configure Bot Settings

Set Bot Description

Set Bot About Text

Set Bot Profile Picture

Configure Commands Menu

Step 3: Configure NeuraTrade

Environment Variable Method

Config File Method

Step 4: Choose Deployment Mode

Polling Mode (Recommended for Development)

Webhook Mode (Recommended for Production)

nginx Configuration Example

Step 5: Start Telegram Service

Via Gateway CLI

Standalone Mode (Development)

Verify Service Health

Step 6: Bind Your Chat ID

Step 7: Test Bot Commands

Basic Commands

Trading Commands

Monitoring Commands

Troubleshooting

Bot Not Responding

Commands Return Errors

Webhook Issues

Configuration Reference

Environment Variables

Source Code Reference

Next Steps