---
title: Telegram Auction Bot
emoji: 🎴
colorFrom: pink
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 🎴 Telegram Auction Bot

A fun real-time bidding/auction bot for Telegram groups featuring Bollywood actresses!

## ✨ Features

- Dynamic number of players (configured by admin, default 1) type `bid start` to launch a session
- Each player gets **500 coins** session allowance to spend
- **5 actresses** auctioned per session (shuffled randomly)
- **15-second reset timer** — any new bid resets the clock (auction-house style!)
- Persistent leaderboard & player stats
- Admins can add custom actresses via bot commands

## 🚀 Setup

### 1. Create your bot

1. Open Telegram and message **@BotFather**
2. Send `/newbot` and follow the prompts
3. Copy the **API token** you receive

### 2. Install dependencies

```bash
npm install
```

### 3. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:
```
BOT_TOKEN=your_token_from_botfather
ADMIN_IDS=your_telegram_user_id
```

> To find your Telegram user ID, message **@userinfobot** on Telegram.

### 4. Run the bot

```bash
node index.js
```

### 5. Add bot to your group

- Add the bot to your Telegram group
- Give it permission to send messages
- Make sure **Group Privacy** is disabled (ask BotFather: `/setprivacy` → Disable) so the bot can read messages

---

## 💬 Commands

| Command | Who | Description |
|---|---|---|
| `bid start` | Everyone | Join / start a session |
| `150` (any number) | Participants | Place a bid |
| `/leaderboard` | Everyone | All-time top players |
| `/mystats` | Everyone | Your personal stats |
| `/listactresses` | Everyone | View all actresses |
| `/how` | Everyone | Simple guide on how to play |
| `/help` | Everyone | Show help |
| `/addactress` | Admin | Instructions to add an actress |
| `/submitactress ...` | Admin | Submit a new actress |
| `/cancelsession` | Admin | Cancel the current session |
| `/helpadmin` | Admin | Show admin help |

---

## 🏆 Coin System

- Each session: **500 coins** allowance per player
- Coins are tracked lifetime in the leaderboard and profile stats
- Bids are deducted from session allowance first, then from the player's global wallet.

---

## 🗂️ File Structure

```
telegram-bid-bot/
├── index.js         # Main bot logic
├── characters.js    # Default hardcoded actresses list
├── db.js            # JSON database helpers
├── db.json          # Auto-created on first run (persistent data)
├── .env             # Your bot token & admin IDs
└── README.md
```

---

## 🌐 Running 24/7

To keep the bot running permanently, use **PM2**:

```bash
npm install -g pm2
pm2 start index.js --name auction-bot
pm2 save
pm2 startup
```