A production Telegram bot running on Cloudflare Workers + TypeScript. It provides 1xBet affiliate cash support, guided deposit and withdrawal flows, and scheduled free sports tips.
Secrets: Keep credentials, payment details, and affiliate values in Cloudflare Secrets or GitHub Actions secrets. Never commit real tokens, API keys, phone numbers, bank details, or webhook secrets.
- Features
- Tech stack
- Project structure
- Prerequisites
- Quick start
- Configuration
- Telegram webhook
- Local development and tests
- Free tips system
- Public and protected routes
- Scheduled jobs
- Deployment and CI/CD
- Security
- Troubleshooting
- License
- Contact
- Telegram webhook bot built with grammY.
- Languages: Sinhala (SI), English (EN), and Tamil (TA) across both the Telegram bot and localized web pages (
/,/en/,/ta/). - Public commands:
/start,/menu,/tips,/scores,/odds,/roi,/deposit,/confirm_deposit,/withdraw,/register,/referrals,/history,/dashboard,/ticket,/safety,/id,/language,/help,/cancel. - Free sports tips with configurable feeds, quality thresholds, freshness limits, publishing caps, and dynamic sport filter tabs.
- 1,000-Credit Odds API Governance (
src/oddsCreditManager.ts): Tracks two 500-credit keys (ODDS_API_KEY+ODDS_API_KEY_2) together across feature buckets (tips: 519,scores: 160,odds_refresh: 160,on_demand: 80,reserve: 81) with automatic800 / 900 / 950 / 1,000protection tiers and one-time Admin Telegram alerts. - Live Scores (
src/liveScores.ts): Hourly:37updates for active posted tip matches and cached/scoresbot & web views (live_score_cache). - Best Odds Finder & Value Alerts (
src/bestOdds.ts): Zero-credit extraction from/oddspayloads intoodds_snapshots, line-movement tracking, deduplicatedvalue_odds_alertsto Telegram,/oddscommand, and public web comparison tab. - Results & Performance Tracker (
src/tipsPerformance.ts): D1-only (0-credit) Win Rate, Net Units, and ROI tracker across Today / 7D / 30D / All Time + automated nightly 23:37 SL channel summary,/roicommand, web tab, and Admin view. - Team & player icon resolution (
src/teamIcons.ts) combining static crests/flags, D1team_icon_cache, TheSportsDB lookup, and SVG fallback badges. - Automated tip settlement with WON / LOST / VOID outcomes, exponential backoff retries, and audited admin overrides.
- Deposit and withdrawal workflows with magic-byte validated R2 receipt storage and authenticated admin receipt proxy.
- Mobile-responsive protected admin dashboard (
/admin) with D3/SVG trends, R2 analytics, attribution funnel, live Odds API credit budget monitor, ROI breakdown, support tickets, and a Telegram BotFather Setup Kit supporting live 640×360 JPEG photo upload & reset in R2. - Security hardening: D1-backed failure-only admin brute-force protection, HMAC-signed
HttpOnly; SameSite=Strictadmin sessions, strict nonce CSP,X-Frame-Options: DENY+frame-ancestors 'none', timing-safe credential checks, and parameterized D1 queries. - Vitest tests plus ESLint and TypeScript checks.
| Layer | Technology |
|---|---|
| Production runtime | Cloudflare Workers |
| Production entry point | src/worker.ts |
| Local Node preview | src/index.ts (not used for production) |
| Language | TypeScript |
| Telegram framework | grammY |
| Database | Cloudflare D1 |
| Object storage | Cloudflare R2 |
| Odds provider | The Odds API v4 |
| Tests | Vitest |
| Lint and type checks | ESLint, TypeScript |
| Deployment tooling | Wrangler 4.157.0 (pinned in package.json) |
| CI/CD | GitHub Actions |
.
├── .github/ # CI/CD, CodeQL, Dependabot workflows
├── data/ # Local preview data directory (database files are gitignored)
├── docs/ # Architecture, operations, security, and free-tips documentation
├── migrations/ # Forward-only Cloudflare D1 SQL migrations
├── public/ # Static landing-page and SEO assets
├── scripts/ # Env scan, secure Cloudflare secret setup, tips-provider check
├── src/
│ ├── worker.ts # Production Worker entry point (fetch and scheduled handlers)
│ ├── index.ts # Local Node preview server
│ ├── bot.ts # Telegram bot setup and handlers
│ ├── cashier.ts # Deposit and withdrawal transaction processing
│ ├── fraud.ts # Rate limits and fraud rule evaluation
│ ├── tips.ts # Free-tip selection, publishing, and controlled odds refresh
│ ├── oddsCreditManager.ts # 1,000-credit monthly budget, bucket caps & 800/900/950/1000 guardrails
│ ├── bestOdds.ts # Zero-credit Best Odds Finder snapshots & deduplicated Value Odds Alerts
│ ├── liveScores.ts # Active-tip live score updater, Telegram notifications & /scores cache
│ ├── tipsPerformance.ts # D1-only Win Rate & ROI analytics and nightly Sri Lanka recap
│ ├── tipsSettlement.ts # Tip result evaluation and settlement
│ ├── publicTips.ts # Public tips, Best Odds, Live Scores & ROI landing-page feed
│ ├── teamIcons.ts # Team/player logo cache (D1 + TheSportsDB + SVG fallback)
│ ├── apiRoutes.ts # HTTP API routing, BotFather photo upload/reset, and admin endpoints
│ ├── adminPage.ts # Responsive Admin Dashboard HTML and client controls
│ ├── adminChart.ts # SVG financial trends chart renderer
│ ├── landingPage.ts # Public landing page HTML
│ ├── seoContentPages.ts # Localized SEO guide pages
│ ├── privacyPage.ts # Privacy policy HTML
│ ├── db.ts # D1 data access
│ ├── storage.ts # R2 / S3 object storage access
│ └── ... # Other Worker modules
├── tests/ # Vitest test suite
├── deploy.sh # Deployment script used by CI
├── package-lock.json # Deterministic npm lockfile for CI & audit
├── validate-migrations.mjs # Migration validation
├── wrangler.toml # Worker name, bindings, vars, assets, and cron triggers
├── .env.example # Local configuration placeholders
├── CONTRIBUTING.md
├── LICENSE # MIT
└── SECURITY.md
- Node.js 22 or newer. Confirm the exact version used in
.github/workflows/ci-cd.ymland match it locally. - A Cloudflare account with a Worker, a D1 database (
fastxbetcash_bot-db), and an R2 bucket (chat-media). - A Telegram bot token from @BotFather.
- An API key from The Odds API for the tips system.
- Repository access if you work with the CI/CD workflow.
Set up a local development environment in a few minutes:
git clone https://github.com/Lakmal2078/Tele-bot-cloudflared-main.git
cd Tele-bot-cloudflared-main
npm ci
cp .env.example .env # then fill in placeholder values for local testing
npm run check # lint, typecheck, and tests
npm run dev # start the local preview serverDo not commit .env. It is listed in .gitignore.
| Variable | Purpose | Current value |
|---|---|---|
BOT_MODE |
Runtime mode | production |
USE_POLLING |
Use polling instead of webhooks | false |
PUBLIC_BASE_URL |
Canonical public HTTPS origin for SEO and webhook URLs | Worker URL |
BOT_USERNAME |
Telegram bot username | fast_1xbetcash_bot |
CHANNEL_URL / CHANNEL_USERNAME |
Public tips channel | @fast_xbet_official_tips |
MIN_TRANSACTION_LKR / MAX_TRANSACTION_LKR |
Transaction limits | 1000 / 500000 |
R2_BUCKET_NAME |
R2 bucket | chat-media |
TIPS_SPORTS |
Sports feeds to scan | See Free tips system |
TIPS_ODDS_REGIONS |
Bookmaker regions | eu |
TIPS_MIN_ODDS / TIPS_MAX_ODDS |
Odds window | 1.30 / 3.00 |
TIPS_HOURS_AHEAD |
Look-ahead window for events | 72 |
TIPS_PER_SLOT |
Tips published per slot | 3 |
TIPS_MAX_FEEDS |
Maximum paid feed requests per run | 3 |
TIPS_MIN_CONSENSUS |
Minimum no-vig consensus probability | 0.45 |
TIPS_MIN_VALUE |
Minimum positive expected value | 0.001 |
TIPS_MIN_BOOKMAKERS |
Minimum bookmakers for Tier 1 | 1 |
TIPS_MAX_STALE_HOURS |
Maximum odds age | 24 |
Affiliate and payment contact values (XBET_LINK, XBET_PROMO_CODE, *_NUMBER) are intentionally empty in wrangler.toml. Set them with wrangler secret put or per-environment configuration.
Set sensitive values with wrangler secret put or npm run secrets:cf (non-echoing interactive setup with secure secret generation):
| Secret | Purpose |
|---|---|
BOT_TOKEN |
Telegram bot token |
WEBHOOK_SECRET |
Telegram secret_token checked on every webhook request (min 16 chars) |
ADMIN_IDS |
Comma-separated numeric Telegram user IDs with admin access |
ADMIN_API_SECRET |
Protects /admin login and admin API routes (min 24 chars) |
ADMIN_CHANNEL_ID |
Channel for admin notifications |
ODDS_API_KEY |
Primary The Odds API key (or comma-separated key list) |
ODDS_API_KEY_2 |
Optional backup The Odds API key for automatic monthly quota failover |
SECURITY_CODE_PEPPER |
HMAC pepper for withdrawal security codes (min 16 chars; required for withdrawals) |
R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_PUBLIC_DOMAIN |
R2 access (Node preview and media delivery) |
TIPS_CHANNEL_ID |
Channel ID for free tips publishing |
BANK_DETAILS, BOC_DETAILS, PEOPLES_DETAILS, SAMPATH_DETAILS, LOLC_DETAILS |
Bank deposit details |
EZCASH_NUMBER, MCASH_NUMBER, FRIMI_NUMBER, IPAY_NUMBER, WHATSAPP_NUMBER |
Payment and contact numbers |
XBET_LINK, XBET_PROMO_CODE |
Affiliate values |
See .env.example for the full list of local placeholders.
Replace the placeholders with your values. Never paste a real token into a public issue or document.
curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<PUBLIC_BASE_URL>/webhook&secret_token=<WEBHOOK_SECRET>"
curl "https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo"The Worker rejects webhook requests with a missing or wrong secret before any bot processing.
npm run dev # tsx watch on the local Node preview (src/index.ts)
npm run build # bundle to dist/server.cjs
npm start # run the built preview serverQuality checks:
npm run lint # ESLint and TypeScript
npm test # Vitest suite
npm run validate:migrations # Validate sequential D1 SQL migrations
npm run audit:deps # Production dependency vulnerability audit
npm run check # lint + testsTo check that the Worker bundle builds without deploying:
npx wrangler deploy --dry-run --outdir /tmp/wrangler-checkDo not run production deployment or remote D1 commands to validate local changes.
The Worker publishes free tips to the channel three times a day at 08:00, 12:00, and 18:00 Sri Lanka time (02:30, 06:30, and 12:30 UTC).
Configured sports (TIPS_SPORTS):
auto:soccer, auto:cricket, auto:basketball, auto:tennis, auto:mma, auto:icehockey
Quota budget & protection ladder (2 × 500-credit keys = 1,000/month, migration 0017_odds_credit_manager.sql):
- Feature bucket allocation: Scheduled Tips
519· Live Scores160· Extra Odds Refresh & Value Alerts160· On-Demand Commands (/scores,/odds)80· Safety Reserve81. - Automatic protection tiers:
800: One-time monthly Admin Telegram warning (WARN_800).900: Pauses extra backgroundodds_refresh& live-only score polling (RESTRICT_900).950: Pauses Value Odds Alerts and live/scores&/oddsrefreshes; serves D1 cache (CRITICAL_950).1,000: Hard-stops all paid Odds API calls until next UTC month (HARD_STOP_1000).
- Tip fetching (
TIPS_MAX_FEEDS=3): Auto-discovers up to 4 active leagues per sport category, pre-checks upcoming fixtures via the 0-credit/eventsendpoint, and fetches up to 3 active feeds per slot with early-stop once 3 diverse picks are found. - Hourly
:37pipeline & nightly recap: Runs tip settlement, caches score events intolive_score_cache, checks active tip scores cleanly, runs a D1-only nightly Sri Lanka Win Rate & ROI summary (23:37SL,0credits), and performs controlled best-odds refreshes when quota permits. - Automatic failover: Set both
ODDS_API_KEYandODDS_API_KEY_2(or comma-separated keys inODDS_API_KEY) so when the first 500-credit key hits0remaining / HTTP401, requests seamlessly rotate to the second key whileoddsCreditManagertracks both accounts together (with automatic shared-pool detection ifused + remaining > 550)./v4/sports,/v4/sports/{sport}/events,/api/tips/preview, and health checks remain 0 credits.
Selection and publishing pipeline:
- Sport discovery & pre-check: Validates active sports using the zero-credit
/v4/sportsendpoint (up to 4 leagues per category sorted by priority, excluding American/Australian football fromauto:soccer), then verifies upcoming matches with zero-credit/eventsbefore making any paid/oddscall. - Odds collection: Collects head-to-head decimal odds from verified feeds with early-stop once 3 diverse picks are found.
- Consensus and value: Removes bookmaker margin (no-vig) to estimate consensus probability and computes expected value against the best available price.
- Candidate selection in tiers:
- Tier 1 (strict): Requires minimum consensus, minimum value, odds in the configured window, and data no older than
TIPS_MAX_STALE_HOURS. - Tier 2 (quality fallback): Accepts any single verified bookmaker price with positive value.
- Tier 3 (wider odds): Widens the odds window to capture high-probability favourites.
- Tier 4 (deduplication fallback): Selects the best upcoming candidate even if it was scheduled before, so the channel stays active.
- Tier 1 (strict): Requires minimum consensus, minimum value, odds in the configured window, and data no older than
- Delivery: Posts formatted tips in Sinhala and English to
TIPS_CHANNEL_ID, falling back toCHANNEL_USERNAMEif the ID is not set. If all Odds API feeds fail, an immediate admin alert is dispatched and the error is recorded. - Settlement: Stores tip records and slot keys in D1. The maintenance cron runs score settlement hourly (
:37) after matches pass a 95-minute kickoff maturity window, updates D1, and edits channel posts with the final WIN, LOSS, or VOID outcome.
Further provider notes are in docs/free-tips.md.
| Method | Path | Description |
|---|---|---|
| GET, HEAD | /, /en/, /ta/ |
Localized landing pages (Sinhala default, English, Tamil) |
| GET, HEAD | /privacy, /privacy-policy, /legal/privacy |
Privacy policy |
| GET, HEAD | /robots.txt |
Robots policy generated from PUBLIC_BASE_URL |
| GET, HEAD | /sitemap.xml |
XML sitemap with hreflang alternates and SEO guides |
| GET, HEAD | /api/tips/preview |
Sanitized public tips feed |
| GET, HEAD | /api/status |
Lightweight public status |
| GET, HEAD | /health |
Configuration-oriented health response (see docs/OPERATIONS.md) |
| GET, HEAD | /bot-description-640x360.jpg, /api/bot/description-photo |
BotFather 640×360 description photo (Worker-first; serves custom R2 image when uploaded, else default asset) |
| GET, HEAD | /og-image.jpg, /og-image.png, /og-image.svg |
OpenGraph preview images |
| GET | /go/tip/:id |
Allowlisted tip click redirect & attribution logger |
| POST | /api/analytics/event |
Rate-limited web conversion beacon |
| Method | Path | Description |
|---|---|---|
| POST | /webhook |
Telegram webhook (requires X-Telegram-Bot-Api-Secret-Token) |
| POST | /admin/login, /admin/logout |
Exchanges ADMIN_API_SECRET for signed HttpOnly session cookie / clears cookie |
| GET, HEAD | /admin, /panel |
Protected Admin UI (login form when unauthenticated; full dashboard after sign-in) |
| POST | /api/tips/settle |
Admin trigger for tip settlement |
| GET | /api/admin/odds-budget |
Monthly Odds API 1,000-credit budget, per-bucket usage, dual-key stats, and ROI summary |
| POST | /api/admin/odds-refresh |
Admin-triggered best-odds refresh governed by canMakeOddsRequest (returns 429 if quota-gated) |
| POST | /api/admin/tips/settlement/override |
Manual historical tip settlement override (requires an authenticated admin session or ADMIN_API_SECRET via Authorization: Bearer / X-Admin-Secret; audit actor is recorded as shared-admin-secret) |
| POST, DELETE | /api/admin/bot/description-photo |
Upload (auto-cropped 640×360 JPEG/PNG/WebP) or reset custom BotFather description photo in R2 |
| GET, HEAD | /api/admin/dashboard, /api/admin/status |
Admin operations dashboard & status |
| GET, HEAD | /api/admin/trends, /api/admin/r2-analytics |
Financial trends & R2 storage analytics (includes Odds API credit & ROI summaries) |
| GET | /api/admin/receipts |
Authenticated proxy for private R2 deposit receipts |
| GET, POST | /api/admin/tickets, /api/admin/schedule |
Support ticket management & scheduled post drafts |
Unknown /api/* routes return a JSON 404.
All schedules are defined in wrangler.toml in UTC.
| Cron (UTC) | Sri Lanka time | Job |
|---|---|---|
0 2 * * * |
07:30 | R2 log cleanup |
30 2 * * * |
08:00 | Free tips, slot 1 |
30 6 * * * |
12:00 | Free tips, slot 2 |
30 12 * * * |
18:00 | Free tips, slot 3 |
*/5,7,22,37,52 * * * * |
Every 5 minutes | Tip settlement every 5 minutes; health checks additionally at :07, :22, :37, :52 |
Jobs must be safe to retry. A scheduled run can execute more than once.
Production deployment runs through GitHub Actions:
pull request → review
push to main → quality checks → migration validation → production deploy
Merging into main is a production deployment. Test changes on a branch first. Routine development should not run production deploy commands locally. The canonical CI command is npm run deploy:cf:ci.
Before a release, run:
npm ci
npm run lint
npm test
npm run validate:migrations
bash -n deploy.sh
npm audit --omit=dev --audit-level=highDatabase migrations are forward-only. A rollback must remain compatible with the current schema. For the full procedure, see docs/OPERATIONS.md.
- Keep Telegram tokens, webhook secrets, admin secrets, Odds API keys, payment details, affiliate values, and R2 credentials out of source control.
- Validate the Telegram webhook secret before processing any update.
- Use timing-safe SHA-256 +
timingSafeEqualcomparisons for credentials. - Protect
/adminand admin APIs with signedHttpOnly; SameSite=Strictsession cookies, optional IP allowlisting (ADMIN_IP_ALLOWLIST), and D1-backed failure-only brute-force rate limiting. - Enforce strict nonce-based CSP (no inline
onclickhandlers) and anti-clickjacking headers (X-Frame-Options: DENY,frame-ancestors 'none') on admin HTML pages. - Validate magic bytes and file size bounds on receipt and BotFather photo uploads before writing to R2.
- Use parameterized D1 queries only and keep D1 migrations forward-only and versioned.
- Rotate any credential that may have been exposed. See
docs/SECRETS_ROTATION.md. - Report vulnerabilities as described in
SECURITY.md.
Further reading: docs/ARCHITECTURE.md, docs/SECURITY_TOP10.md.
Webhook returns 401. The Cloudflare WEBHOOK_SECRET does not match the secret_token set on Telegram. Check the webhook status:
curl "https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo"The bot cannot post to the tips channel. Confirm the bot is an administrator of the channel with posting rights, and that TIPS_CHANNEL_ID or CHANNEL_USERNAME is correct.
Only fallback notices are published. Check the Odds API key and quota, the sports list, and the quality thresholds (TIPS_MIN_CONSENSUS, TIPS_MIN_VALUE, TIPS_MAX_STALE_HOURS).
Tips stay pending. Check the Worker logs and the five-minute settlement cron. A pending result can be correct if the event has not finished or the score data is not available yet.
Local preview database errors. The preview stores data in data/. Keep data/.gitkeep tracked and delete local database files if they become inconsistent.
MIT. See LICENSE.
- Email:
lakmalsujith25@gmail.com - Tips channel:
@fast_xbet_official_tips - Bot:
@fast_1xbetcash_bot