🪙 CoinPrice Bot

Live crypto prices in USD / RUB / UZS, right inside Telegram.
Watchlist alerts · 100% free · Admin panel

📚 Full documentation: docs/wiki

---

📖 Table of Contents

• ✨ Features
• 💱 How prices work
• 🚀 Quick start
• ⚙️ Configuration
• 🐳 Docker
• 🧪 Tests
• 🗄️ Database
• 🔐 Security
• 📄 License

---

✨ Features

Feature	Description
🔍 Any coin/token	Look up thousands of coins — from BTC to the newest memecoins
💱 3 currencies	Every price shown in USD, RUB and UZS
🔔 Smart alerts	Subscribe to coins and get notified only when a price moves ≥ 0.01%
📝 Profiles	Phone-number onboarding, editable name and alert interval
🆓 Fully free	Unlimited lookups and intervals for everyone, no limits
🛠️ Admin panel	Paginated user list and per-user details

---

💱 How prices work

1. Multiple sources, one honest price. Each coin is fetched in parallel from Binance, Bybit, Coinbase, CoinGecko, DexScreener (+ CoinMarketCap if you add a key). Aggregated venues (CoinGecko/Coinbase/CMC) outrank single-exchange quotes; unverified DEX listings are last-resort only. Outliers are dropped automatically — so one glitching exchange can't show you a wrong price.
2. Unknown tickers resolve themselves. Popular coins use a built-in fast path; anything else is resolved live via CoinGecko search (exact symbol match, highest market-cap rank wins) and cached.
3. Real fiat rates. UZS comes from Uzbekistan's Central Bank, RUB from Russia's Central Bank (each with a backup source, refreshed every 10 minutes).
4. Not found? The bot suggests similar symbols — just check the exact ticker spelling.

⚠️ CoinGecko's free search API is rate-limited: a burst of many brand-new coins in a row may be throttled (the bot retries once, then skips that source for the moment). Repeats are served from cache.

---

🚀 Quick start

git clone https://github.com/hamroqulovv/coinprice.git
cd coinprice

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env            # fill in your values (see below)
python main.py

You should see 🤖 Bot started! in the logs — open your bot in Telegram and press Start.

---

⚙️ Configuration

All settings live in .env:

Variable	Required	What it is
BOT_TOKEN	✅	Telegram bot token from @BotFather
PRIMARY_ADMIN	✅	Your Telegram numeric ID (owner of the admin panel)
ADMINS	⬜	Extra admin IDs, comma-separated without spaces (same access as owner)
CHANNELS	⬜	Optional channel list
COINBASE_BASE_URL	⬜	Override, default https://api.coinbase.com/v2/prices
BINANCE_URL	⬜	Override, default https://api.binance.com/api/v3/ticker/price
COINGECKO_URL	⬜	Override, default https://api.coingecko.com/api/v3/simple/price
UZS_RATE_URL	⬜	Override, default https://cbu.uz/uz/arkhiv-kursov-valyut/json/
RUB_RATE_URL	⬜	Override, default https://www.cbr-xml-daily.ru/daily_json.js
ER_API_URL	⬜	Fallback fiat source, default https://open.er-api.com/v6/latest/USD
COINMARKETCAP_API_KEY / COINMARKETCAP_URL	⬜	Adds CoinMarketCap as an extra price source
COINGECKO_API_KEY	⬜	Free demo key from coingecko.com — raises rate limits so low-cap lookups throttle less

⬜ = optional, has a working built-in default.

---

🐳 Docker

docker compose up -d --build
docker compose logs -f

main.db is persisted through a host volume (see docker-compose.yml). Running on a plain VM instead? Use the systemd unit in deploy/crypto-bot.service. Step-by-step guides: DEPLOY.md · [DEPLOY_UZ.md](DEPLOY_UZ.md 🇺🇿) · DEPLOY_RENDER_SUPABASE.md (free Render + Supabase, $0)

---

🧪 Tests

pip install -r requirements.txt pytest
python -m pytest -q

Tests live in tests/ and run automatically on every push/PR via .github/workflows/tests.yml.

---

🗄️ Database

SQLite file main.db, created automatically on first start:

• Users — profile and usage counters
• CryptoPreferences — watchlist with UNIQUE(user_id, coin_symbol) and the last notified price (so restarts never re-spam old alerts)

---

🔐 Security

• Never commit .env or API keys — both are git-ignored.
• On ephemeral hosts (Heroku, Cloud Run) SQLite does not survive restarts — use an external database there.

---

📄 License

GNU General Public License v3.0 — see LICENSE.