Solana Wallet Tracker Telegram Bot

A token-gated Telegram bot that tracks Solana wallet activity in real-time using Helius webhooks.

Features

• 🔐 Token-gated access - Users must hold a minimum amount of tokens to use the bot
• 🔗 Secure wallet verification - Users sign a message to prove wallet ownership
• 📊 Real-time tracking - Get instant notifications for wallet transactions via Helius webhooks
• 💰 SOL & Token transfers - Track both native SOL and SPL token movements
• 🏷️ Wallet labels - Add custom labels to tracked wallets
• 📱 Easy commands - Simple Telegram commands for all operations

Prerequisites

• Node.js 18+
• A Telegram Bot Token (from @BotFather)
• A Helius API Key (free at helius.dev)
• A server with a public URL for webhooks (Railway, Render, VPS, etc.)

Setup

1. Clone and Install

git clone <your-repo>
cd solana-wallet-tracker-bot
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your values:

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather

# Helius API
HELIUS_API_KEY=your_helius_api_key

# Webhook URL (your deployed server URL)
WEBHOOK_URL=https://your-domain.com/webhook
PORT=3000

# Token Gate Configuration
REQUIRED_TOKEN_MINT=7APLqd6CZDjWbX8An9fD28XADj7pfN6BGVhpESmepump
REQUIRED_TOKEN_AMOUNT=1000000

# Verification Page
VERIFY_PAGE_URL=https://your-domain.com/verify.html

3. Run Locally (for testing)

npm run dev

For local testing with webhooks, use ngrok:

ngrok http 3000

Then update WEBHOOK_URL and VERIFY_PAGE_URL with your ngrok URL.

4. Deploy to Railway

1. Push code to GitHub
2. Create new project in Railway
3. Connect your GitHub repo
4. Add environment variables in Railway dashboard
5. Deploy!

Your webhook URL will be: https://your-app.up.railway.app/webhook

Bot Commands

Command	Description
/start	Welcome message and instructions
/verify	Connect and verify your wallet
/status	Check your verification and balance status
/track [address] [label]	Start tracking a wallet
/untrack [address]	Stop tracking a wallet
/wallets	List all tracked wallets
/help	Show help message

How It Works

Token Gate Flow

1. User starts the bot
2. User runs /verify and gets a link to connect their wallet
3. User connects wallet (Phantom/Solflare) and signs a verification message
4. Bot checks if wallet holds the required token amount
5. If eligible, user can track wallets; otherwise, they're prompted to buy tokens

Wallet Tracking Flow

1. User runs /track <address> <optional_label>
2. Bot creates a Helius webhook for that address
3. When transactions occur, Helius sends data to /webhook
4. Bot parses the transaction and sends a formatted notification to the user

Configuration Options

Adjust Max Tracked Wallets

In src/index.js, change:

const MAX_TRACKED_WALLETS = 5; // Change to desired limit

Tiered Access (Optional)

You can modify requireVerification middleware to implement tiered access:

// Example: More tokens = more tracked wallets
const tiers = [
  { minTokens: 1000000, maxWallets: 3 },
  { minTokens: 5000000, maxWallets: 10 },
  { minTokens: 10000000, maxWallets: 25 },
];

File Structure

solana-wallet-tracker-bot/
├── src/
│   ├── index.js      # Main bot + Express server
│   ├── database.js   # SQLite database operations
│   ├── solana.js     # Solana/token utilities
│   └── helius.js     # Helius webhook management
├── public/
│   └── verify.html   # Wallet verification page
├── data/
│   └── bot.db        # SQLite database (auto-created)
├── .env.example
├── package.json
└── README.md

Troubleshooting

"Phantom not detected"

User needs to open the verification page in a browser with Phantom installed, or use the Phantom mobile app's browser.

Webhooks not working

• Ensure WEBHOOK_URL is publicly accessible
• Check Helius dashboard for webhook status
• Verify the endpoint returns 200 status

Balance check fails

• Verify HELIUS_API_KEY is valid
• Check REQUIRED_TOKEN_MINT is correct
• Ensure Helius RPC is accessible

License

MIT