xai-billing-alert

Telegram bot for x.ai (Grok API) balance monitoring and low-balance alerts.

x.ai has no built-in balance alerts. If your prepaid credits run out, Grok API requests get rejected silently — no email, no warning, nothing. This self-hosted Telegram bot watches your x.ai balance and pings you before that happens.

Features

• Real-time balance — shows your actual x.ai prepaid credit balance (not delayed by billing cycles)
• Automatic alerts — warns you when balance drops below a threshold you set
• Two alert levels — warning (below threshold) and critical ($0)
• Configurable — set check interval (default: 60 min) and threshold via Telegram commands
• Secure — deletes messages containing keys, stores data locally, uses read-only API scope
• Self-hosted — your management keys never leave your server
• Easy setup — 5 minutes to deploy with Docker or pm2

Quick Start

1. Create a Telegram bot

Message @BotFather on Telegram → /newbot → copy the bot token.

2. Get your x.ai Management Key

Go to console.x.ai → Settings → Management Keys → create a new key with the BillingRead scope.

Note: Management keys are separate from API keys. API keys are for Grok inference (chat, images), management keys are for billing and admin. You need a management key here.

3. Run the bot

git clone https://github.com/iamarsenibragimov/xai-billing-alert.git
cd xai-billing-alert
npm install
cp .env.example .env
# Edit .env and set TELEGRAM_BOT_TOKEN
npm run dev

4. Set up in Telegram

1. Open your bot → send /start
2. Paste your x.ai management key (the bot deletes the message immediately)
3. Send /monitor 10 to get alerts when balance drops below $10

Done!

Running in Production

Docker (recommended)

cp .env.example .env
# Edit .env and set TELEGRAM_BOT_TOKEN
docker compose up -d

docker compose logs -f       # view logs
docker compose restart       # restart
docker compose down          # stop

pm2

npm run build
pm2 start dist/index.js --name xai-billing-alert
pm2 save

Bot Commands

| Command | Description | |---|---| | /start | Welcome message and setup | | /balance | Check your current x.ai balance | | /monitor <amount> | Alert when balance drops below $amount | | /interval <minutes> | Set check interval (default: 60, min: 5) | | /stop | Stop automatic monitoring | | /status | Show current settings | | /setkey | Change your management key | | /forget | Delete all your data from the bot | | /help | Show available commands |

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | TELEGRAM_BOT_TOKEN | Yes | — | Bot token from @BotFather | | ALLOWED_USERS | No | (allow all) | Comma-separated Telegram user IDs | | DATA_DIR | No | ./data | Path to persistent storage |

To find your Telegram user ID, message @userinfobot.

How It Works

1. You give the bot your x.ai management key with the BillingRead scope
2. The bot validates the key via GET /auth/management-keys/validation
3. To get your real-time balance, it calls GET /v1/billing/teams/{teamId}/postpaid/invoice/preview on the x.ai Management API — this returns your prepaid credits and current period consumption
4. Every N minutes (configurable), it checks the balance
5. If balance drops below your threshold — you get a Telegram message
6. Alert cooldown: 6 hours between repeated alerts (resets if balance drops significantly)

Security

• Key deletion — the bot deletes messages containing management keys from chat
• Local storage — keys are stored in a local JSON file (data/config.json)
• Read-only access — the bot only calls GET endpoints on the x.ai Management API
• Self-hosted — you run it on your own server, keys never leave your infrastructure
• Access control — use ALLOWED_USERS to whitelist specific Telegram accounts
• Minimal scope — create your management key with BillingRead only

Tech Stack

• TypeScript + Node.js 18+
• grammY — Telegram bot framework
• Native fetch — zero HTTP client dependencies
• JSON file — simple persistence, no database needed

Development

npm run dev      # Run with hot reload
npm run build    # Compile TypeScript
npm start        # Run compiled version

Contributing

Contributions are welcome! Feel free to open issues and pull requests.

License

MIT