API Reference

Command Line Interface

GSwarm provides a comprehensive command-line interface focused on Telegram monitoring for Gensyn AI blockchain activity.

Main Command

gswarm

The main command to start the GSwarm Telegram monitoring service.

gswarm [flags]

Command Options

Telegram Monitoring Flags

Utility Commands

Environment Variables

All command-line flags can be set via environment variables with the GSWARM_ prefix:

# Telegram configuration
export GSWARM_TELEGRAM_CONFIG_PATH=/path/to/telegram-config.json
export GSWARM_UPDATE_TELEGRAM_CONFIG=false

Configuration File Format

GSwarm uses JSON configuration files for Telegram setup:

{
  "botToken": "your_bot_token_here",
  "chatID": 123456789,
  "eoaAddress": "0x1234567890abcdef..."
}

Configuration File Fields

Usage Examples

Basic Usage

# Interactive setup (default)
gswarm
 
# Use custom config path
gswarm --telegram-config-path /path/to/config.json
 
# Force update Telegram config
gswarm --update-telegram-config
 
# Show version
gswarm version

Environment Variable Usage

# Set config path via environment variable
export GSWARM_TELEGRAM_CONFIG_PATH=/custom/path/config.json
gswarm
 
# Force config update via environment variable
export GSWARM_UPDATE_TELEGRAM_CONFIG=true
gswarm

Interactive Setup Flow

When run without configuration, GSwarm will guide you through setup:

1. Telegram Bot Token: Prompts for bot token from @BotFather
2. Telegram Chat ID: Prompts for chat ID (personal or group)
3. EOA Address: Prompts for Ethereum address to monitor
4. Configuration Save: Saves configuration to local file
5. Welcome Message: Sends test message to Telegram
6. Peer ID Detection: Automatically detects associated peer IDs
7. Monitoring Start: Begins continuous monitoring loop

File Structure

GSwarm creates and manages the following file structure:

~/.gswarm/
├── telegram-config.json      # Telegram configuration
└── telegram_previous_data.json # Previous blockchain data for change detection

telegram-config.json

Contains your Telegram bot configuration and EOA address:

{
  "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
  "chatID": 123456789,
  "eoaAddress": "0x1234567890abcdef1234567890abcdef12345678"
}

telegram_previous_data.json

Stores previous blockchain data for change detection:

{
  "lastCheck": "2025-01-01T12:00:00Z",
  "totalVotes": 1456,
  "totalRewards": "0.75",
  "peerData": {
    "QmZkyXja166VBTMU76xLR17XKAny9kAkFgx4fNpoceQ8LT": {
      "votes": 22,
      "rewards": 3075
    }
  }
}

Monitoring Behavior

Check Interval

• Default: Every 5 minutes
• Change Detection: Only sends notifications when values change
• Error Handling: Retries on network errors with exponential backoff

Notification Types

1. Welcome Message: Sent on first run to confirm setup
2. Vote Changes: When vote count increases or decreases
3. Reward Changes: When accumulated rewards change
4. Balance Changes: When wallet balance changes
5. Peer ID Updates: When new peer IDs are detected

Message Format

Notifications are sent as HTML-formatted messages with:

• Change indicators (📈 for increases, 📉 for decreases)
• Per-peer breakdown
• Timestamps
• Total summaries

Error Handling

Common Error Scenarios

1. Invalid Bot Token

   • Error: "Bot token invalid"
   • Solution: Verify token with @BotFather

2. Chat ID Not Found

   • Error: "Chat ID not found"
   • Solution: Send message to bot and check getUpdates

3. Network Errors

   • Error: "Failed to fetch blockchain data"
   • Solution: Check internet connection and retry

4. Invalid EOA Address

   • Error: "Invalid Ethereum address"
   • Solution: Verify address format and validity

Retry Logic

• Network Errors: Exponential backoff (5s, 10s, 20s, 40s...)
• API Rate Limits: Respects Telegram API rate limits
• Configuration Errors: Prompts for re-entry

Security Considerations

Data Storage

• Local Storage: All configuration stored locally
• No Cloud Storage: No data transmitted to external services
• File Permissions: Config files should have restricted permissions

API Access

• Telegram Bot API: Only sends messages to configured chat
• Blockchain Queries: Read-only access to blockchain data
• No Private Keys: Never requires or stores private keys

Development Commands

Building from Source

# Clone repository
git clone https://github.com/Deep-Commit/gswarm.git
cd gswarm
 
# Build for current platform
make build
 
# Build for all platforms
make build-all
 
# Install to system
make install

Testing

# Run tests
make test
 
# Run tests with coverage
make test-coverage
 
# Format code
make fmt
 
# Lint code
make lint

Version Information

Check Version

gswarm --version
gswarm version

Version Output Format

gswarm version 1.0.0

Build Information

When built from source, version includes:

• Git commit hash
• Build timestamp
• Go version used
• Target platform

Help System

General Help

gswarm --help

Command-Specific Help

gswarm help version

Help Output Format

GSwarm - Gensyn Telegram Monitoring Service

Usage:
  gswarm [flags]

Flags:
  --telegram-config-path string   Path to telegram-config.json file (default "telegram-config.json")
  --update-telegram-config        Force update of Telegram config via CLI prompts
  --version                       Show version information
  --help                          Show help information

Integration Examples

Systemd Service

Create /etc/systemd/system/gswarm.service:

[Unit]
Description=GSwarm Telegram Monitoring Service
After=network.target
 
[Service]
Type=simple
User=gswarm
WorkingDirectory=/home/gswarm
ExecStart=/usr/local/bin/gswarm
Restart=always
RestartSec=10
Environment=GSWARM_TELEGRAM_CONFIG_PATH=/home/gswarm/config.json
 
[Install]
WantedBy=multi-user.target

Docker Container

FROM golang:1.24-alpine
 
# Install GSwarm
RUN go install github.com/Deep-Commit/gswarm/cmd/gswarm@latest
 
# Create config directory
RUN mkdir -p /app/config
 
# Set working directory
WORKDIR /app
 
# Copy configuration
COPY telegram-config.json config/
 
# Run GSwarm
CMD ["gswarm", "--telegram-config-path", "/app/config/telegram-config.json"]

Cron Job

Add to crontab for periodic monitoring:

# Check every 5 minutes
*/5 * * * * /usr/local/bin/gswarm --telegram-config-path /path/to/config.json