Skip to content

Telegram Bot

Control Arbiter-Bot from your phone with the Telegram interface. Monitor positions, manage the arbitrage engine, and track copy trades - all from Telegram.

Prerequisites

  1. Telegram account - Download Telegram if you don't have it
  2. BotFather bot token - Create a bot via @BotFather
  3. Running Arbiter engine - The bot connects to the engine via gRPC

Setup

1. Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts
  3. Copy the bot token (looks like 123456789:ABCdefGHI...)

2. Configure Environment

# Required
export TELEGRAM_BOT_TOKEN="your-bot-token-from-botfather"

# gRPC connection to Arbiter engine
export GRPC_HOST="localhost"  # Default
export GRPC_PORT="50051"      # Default

# Optional: Restrict access to specific Telegram user IDs
export TELEGRAM_ALLOWED_USERS="123456789,987654321"

3. Install and Run

# Navigate to telegram-bot directory
cd telegram-bot

# Install dependencies
pip install -e .

# Run the bot
arbiter-bot

Or with Docker:

docker run -d \
  -e TELEGRAM_BOT_TOKEN="your-token" \
  -e GRPC_HOST="arbiter-engine" \
  -e GRPC_PORT="50051" \
  arbiter-bot

Commands

Dashboard

Command Description
/start Initialize bot and show welcome message
/home Dashboard with balances, P&L, and quick actions

The /home command displays:

  • Total balance across exchanges
  • Arbitrage engine status (on/off)
  • Today's trading performance
  • Quick action buttons for common tasks

Positions

Command Description
/positions View all open positions with P&L

Shows each position with:

  • Market ID and exchange
  • Side (long/short) and size
  • Entry price vs current price
  • Unrealized P&L ($ and %)

Wallet

Command Description
/wallet Detailed balance view by exchange

Displays:

  • Available balance (ready to trade)
  • Locked balance (in open orders)
  • Total balance per exchange
  • Funding options

Arbitrage Control

Command Description
/arb Show arbitrage engine status
/arb status Detailed status with config
/arb start Enable the arbitrage engine
/arb stop Disable the arbitrage engine

The status view shows:

  • Engine state (on/off)
  • Min spread and max position configuration
  • Active opportunities detected
  • Today's trade count and P&L

Copy Trading

Command Description
/copy Show copy trading help
/copy list List active copy trades
/copy add <wallet> Add new copy trade
/copy add <wallet> <alloc%> <max$> Add with custom allocation
/copy remove <id> Remove a copy trade

Examples:

/copy add 0x1234...abcd
# Adds copy trade with defaults: 10% allocation, $100 max position

/copy add 0x1234...abcd 15 500
# Adds copy trade: 15% allocation, $500 max position

/copy remove ct_abc123
# Removes the copy trade with ID ct_abc123

Quick Actions

The /home dashboard includes inline buttons for common actions:

Button Action
Positions View open positions
Wallet View balances
Start/Stop Arb Toggle arbitrage engine
Copy Trades View copy trade list

Configuration

Environment Variables

Variable Default Description
TELEGRAM_BOT_TOKEN (required) Bot token from BotFather
GRPC_HOST localhost Arbiter engine host
GRPC_PORT 50051 Arbiter engine gRPC port
TELEGRAM_ALLOWED_USERS (empty) Comma-separated user IDs to allow
LOG_LEVEL INFO Logging level

Restricting Access

By default, anyone can interact with your bot. To restrict access:

  1. Get your Telegram user ID (send a message to @userinfobot)
  2. Set the allowed users:
export TELEGRAM_ALLOWED_USERS="123456789"

Multiple users can be allowed:

export TELEGRAM_ALLOWED_USERS="123456789,987654321,555555555"

Architecture

The Telegram bot is a Python service that communicates with the Rust trading engine via gRPC:

┌─────────────────────────────────────────────────────────┐
│                    Your Phone                            │
│                   (Telegram App)                         │
└───────────────────────┬─────────────────────────────────┘
                        │ Telegram API
                        ▼
┌─────────────────────────────────────────────────────────┐
│              Telegram Bot (Python)                       │
│  • python-telegram-bot framework                         │
│  • Command handlers                                      │
│  • Inline keyboard callbacks                             │
└───────────────────────┬─────────────────────────────────┘
                        │ gRPC
                        ▼
┌─────────────────────────────────────────────────────────┐
│              Arbiter Engine (Rust)                       │
│  • TradingService                                        │
│  • StrategyService                                       │
│  • UserService                                           │
└─────────────────────────────────────────────────────────┘

Troubleshooting

"Backend not connected"

The bot can't reach the Arbiter engine. Check:

  1. Is the engine running? cargo run --manifest-path arbiter-engine/Cargo.toml
  2. Are GRPC_HOST and GRPC_PORT correct?
  3. Is there a firewall blocking the connection?

Bot doesn't respond

  1. Check the bot token is correct
  2. Verify the bot is running (arbiter-bot command)
  3. Check logs for errors: LOG_LEVEL=DEBUG arbiter-bot

"Unauthorized" errors

If you set TELEGRAM_ALLOWED_USERS, make sure your user ID is in the list.

Rate limiting

The Arbiter engine enforces rate limits. If you see rate limit errors:

  1. Wait a few seconds before retrying
  2. Reduce frequency of commands
  3. Check your subscription tier limits

Development

# Install with dev dependencies
cd telegram-bot
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Type checking
mypy src/

Next Steps