Sai Telegram Bot

A Telegram bot for monitoring Sai trading data, including trades and oracle prices.

Features

• View open and closed trades for any wallet address
• Check oracle prices for all supported tokens
• Get real-time price updates for specific tokens
• Interactive pagination for browsing prices
• Formatted display with emojis and trade details

Prerequisites

Before you begin, make sure you have:

• Python 3.9 or higher installed
• Git installed
• A Telegram account

Getting Started

1. Clone and Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/sai-telegram-bot.git
cd sai-telegram-bot

# Create virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Get Your Bot Token from BotFather

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts:
   • Bot name: "Sai Trading Bot" (or your choice)
   • Username: Must end in "bot" (e.g., "sai_trading_bot")
3. Copy the API token BotFather gives you (looks like 1234567890:ABCdefGHI...)

Optional: Customize your bot appearance

Use these BotFather commands to customize your bot:

• /setdescription - Set a description for your bot's profile
• /setabouttext - Set the "About" text
• /setuserpic - Upload a profile picture
• /setcommands - Set the command list (copy the commands below):

start - Welcome message and help
help - Show available commands
trades - View trades for a wallet address
prices - Show all token prices
price - Get price for a specific token

3. Configure and Run

# Create your .env file
cp env.example .env

# Edit .env and add your bot token:
# TELEGRAM_BOT_TOKEN=your_token_here

# Run the bot
python -m bot.main

That's it! Open Telegram and message your bot with /start.

python -m bot.main

You should see:

INFO:__main__:🚀 Bot is starting...

The bot is now running! Open Telegram, find your bot, and send /start to begin using it.

Available Commands

Once your bot is running, you can use these commands in Telegram:

• /start - Welcome message with command list
• /help - Show help information
• /trades <address> - View all trades for a wallet address
• /trades <address> open - View only open trades
• /trades <address> closed - View only closed trades
• /trades <address> btc - View trades for a specific token
• /prices - Show all oracle prices (paginated)
• /price <symbol> - Get price for a specific token (e.g., /price BTC)

Examples

/trades nibiru1abc123def456
/trades nibiru1abc123def456 open
/trades nibiru1abc123def456 btc
/price BTC
/price ETH
/prices

Project Structure

sai-telegram-bot/
├── bot/
│   ├── __init__.py       # Package initialization
│   ├── main.py           # Main bot logic and command handlers
│   └── graphql.py        # GraphQL client for Sai data
├── venv/                 # Virtual environment (created by you)
├── .env                  # Environment variables (create from env.example)
├── env.example           # Example environment configuration
├── requirements.txt      # Python dependencies
└── README.md            # This file

Development

Dependencies

• python-telegram-bot - Telegram Bot API wrapper
• requests - HTTP library for GraphQL queries
• python-dotenv - Load environment variables from .env
• pytz - Timezone handling

Stopping the Bot

Press Ctrl+C in the terminal where the bot is running.

Restarting the Bot

If you make changes to the code:

1. Stop the bot (Ctrl+C)
2. Make sure your virtual environment is activated
3. Run python -m bot.main again

Deployment

For deploying from scratch or setting up a production environment, follow the official Sai Telegram Bot Guide. The guide includes:

• Step-by-step instructions for building a bot from the ground up
• Production deployment best practices
• Advanced configuration options
• Integration with Sai's GraphQL API

This README provides quick start instructions, but the official guide offers comprehensive details for custom implementations and deployment scenarios.

Troubleshooting

"TELEGRAM_BOT_TOKEN not found in .env!"

Make sure you:

• Created the .env file from env.example
• Added your bot token from BotFather
• The token is on the line TELEGRAM_BOT_TOKEN=your_actual_token_here

"Module not found" errors

Make sure you:

• Activated the virtual environment (source venv/bin/activate)
• Installed all dependencies (pip install -r requirements.txt)

Bot doesn't respond

Make sure:

• The bot is running (check the terminal)
• You're messaging the correct bot username
• The bot token in .env is correct

Connection errors

Check:

• Your internet connection
• The Sai GraphQL endpoint is accessible: https://sai-keeper.nibiru.fi/query

Contributing

Contributions are welcome! Please feel free to fork or submit a Pull Request.

License

This project is open source and available under the MIT License.

Support

If you encounter any issues or have questions:

1. Check the troubleshooting section above
2. Review the bot logs in the terminal
3. Verify your configuration in .env

Acknowledgments

• Built with python-telegram-bot
• Connects to Sai (Nibiru DeFi) GraphQL API
• Based on the Sai Telegram Bot Guide