🧙 Binance Sage

A voice-based Binance trading assistant running as a Telegram bot, powered by Hermes Agent.

Send voice or text messages on Telegram to get market insights, check your portfolio, and manage your Binance account — all through natural conversation.

Features

• 🎙️ Voice Commands — Send voice messages on Telegram, get voice replies
• 📊 Portfolio Viewer — Check balances, USD values, and allocation (/binance-portfolio)
• 🧹 Dust Sweeper — Find and convert small balances to BNB (/binance-dust-sweeper)
• 📈 Market Analysis — Prices, trends, moving averages, RSI (/binance-market-analysis)
• 🤖 Conversational AI — Natural language interaction via Hermes Agent
• 🔒 Safety First — All account actions require explicit user confirmation

Architecture

You (Telegram) → Voice/Text Message
   → Hermes Gateway (on VPS)
   → STT: faster-whisper (free, local)
   → Hermes Agent + Binance Skills
   → TTS: Edge TTS (free)
   → Voice bubble reply on Telegram

Quick Start

Prerequisites

• Oracle Cloud VPS (or any Ubuntu/Debian server)
• Binance API keys (read + spot trading permissions)
• Telegram account
• Nous Research API key (or other LLM provider)

1. Create Telegram Bot

1. Open Telegram → message @BotFather → /newbot
2. Name: Binance Sage | Username: BinanceSageBot
3. Save the bot token

2. Get Your Telegram User ID

Message @userinfobot on Telegram — it replies with your numeric user ID.

3. Upload to VPS

# On your Mac — upload the project
scp -r ~/path/to/binance-sage ubuntu@YOUR_VPS_IP:~/binance-sage

4. Configure

# On the VPS
cd ~/binance-sage
cp .env.template .env
nano .env  # Fill in your actual keys

5. Deploy

bash deploy.sh

6. Start

hermes gateway start  # As a service (24/7)
# OR
hermes gateway        # In foreground (for testing)

7. Talk to Your Bot!

Open Telegram → message @BinanceSageBot → say hello!

Enable voice replies: /voice on

Skills

Skill	Command	Description
Portfolio	/binance-portfolio	Balances, USD values, allocation
Dust Sweep	/binance-dust-sweeper	Find & convert small balances to BNB
Market Analysis	/binance-market-analysis	Prices, trends, MA, RSI, insights

Project Structure

binance-sage/
├── SOUL.md              # Agent personality ("Binance Sage")
├── config.yaml          # Hermes voice config (STT + TTS)
├── .env.template        # Environment variables template
├── deploy.sh            # One-command VPS deployment
├── README.md            # This file
└── skills/
    └── crypto/
        ├── binance-portfolio/
        │   └── SKILL.md
        ├── binance-dust-sweeper/
        │   └── SKILL.md
        └── binance-market-analysis/
            └── SKILL.md

Security

• API Key Permissions: Only enable "Read" + "Enable Spot Trading" on your Binance API key. Never enable withdrawals.
• Telegram Allowlist: Only your Telegram user ID is authorized. Set TELEGRAM_ALLOWED_USERS in .env.
• Exec Approval: Hermes asks for confirmation before running dangerous commands.
• Dust Sweep Confirmation: The agent always lists assets and waits for your "yes" before converting.

License

MIT