Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ad/telegram-prediction-market


https://github.com/ad/telegram-prediction-market

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

          



# ๐ŸŽฏ Telegram Prediction Market Bot



**Create your prediction market right in Telegram**



[![Go Version](https://img.shields.io/badge/Go-1.25.5+-00ADD8?style=flat&logo=go)](https://go.dev/)

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[![Telegram](https://img.shields.io/badge/Telegram-Bot-blue?logo=telegram)](https://telegram.org/)



English | [ะ ัƒััะบะธะน](README.md)



[Features](#-features) โ€ข [Quick Start](#-quick-start) โ€ข [Usage](#-usage) โ€ข [Architecture](#-architecture)






---



## ๐ŸŒŸ About



Telegram Prediction Market Bot is a full-featured bot for creating prediction markets where users can make forecasts on various events and compete in accuracy. Perfect for teams, communities, and friend groups who want to add a competitive element to their discussions.



### ๐Ÿ’ก Why Use It?



- **For Teams**: Predict sprint outcomes, releases, metrics

- **For Communities**: Create prediction tournaments on any topic

- **For Friends**: Compete in forecasts on sports events, weather, politics

- **For Learning**: Develop critical thinking and probability assessment skills



---



## โœจ Features



### ๐Ÿข Multi-Group Architecture

- **Complete data isolation** between groups

- **Deep-link invitations** for easy joining

- **Unlimited participation** โ€” users can be in multiple groups simultaneously

- **Independent ratings** and achievements in each group

- **๐Ÿ†• Telegram Forums support** โ€” send events to specific forum topics



### ๐ŸŽฒ Flexible Event Types

- **Binary** (Yes/No) โ€” classic predictions

- **Multiple Choice** (2-6 options) โ€” for complex scenarios

- **Probabilistic** (ranges 0-25%, 25-50%, 50-75%, 75-100%) โ€” for confidence calibration



### ๐ŸŽฏ Smart Scoring System

```

โœ… Correct Prediction:

   โ€ข Binary event: +10 points

   โ€ข Multiple choice: +15 points

   โ€ข Probabilistic: +15 points



๐ŸŽ Bonuses:

   โ€ข Minority (<40% votes): +5 points

   โ€ข Early vote (first 12 hours): +3 points

   โ€ข Participation: +1 point



โŒ Penalties:

   โ€ข Wrong prediction: -3 points

```



### ๐Ÿ† Achievement System

- ๐ŸŽฏ **Sharpshooter** โ€” 3 correct predictions in a row

- ๐Ÿ”ฎ **Oracle** โ€” 10 correct predictions in a row

- ๐ŸŽฒ **Risk Taker** โ€” 3 correct minority predictions in a row

- ๐Ÿ“Š **Analyst of the Week** โ€” most points in a week

- ๐Ÿ† **Veteran** โ€” participated in 50 events



### ๐Ÿ”„ FSM-based Event Creation

- **Interactive step-by-step process** with validation at each step

- **Automatic message cleanup** for clean chat

- **Persistent sessions** โ€” continue after bot restart

- **Conflict protection** โ€” multiple admins can create events simultaneously



### ๐Ÿ”” Smart Notifications

- Reminders 24 hours before deadline

- New event announcements

- Achievement notifications



### ๐Ÿ’ฌ Telegram Forums Support (NEW!)

- **Send events to topics** โ€” create events in specific forum topics

- **Default topic** โ€” configure group to automatically send to a specific topic

- **Flexibility** โ€” each event can be sent to its own topic

- **Backward compatibility** โ€” regular groups continue to work as before



---



## ๐Ÿš€ Quick Start



### Requirements



- Go 1.25.5+

- SQLite (embedded via modernc.org/sqlite)

- Telegram Bot Token (get from [@BotFather](https://t.me/BotFather))



### Installation



```bash

# Clone the repository

git clone https://github.com/ad/telegram-prediction-market.git

cd telegram-prediction-market



# Install dependencies

go mod download



# Build the bot

go build -o bin/bot ./cmd/bot

```



### Configuration



Create a `.env` file based on `.env.example`:



```bash

# Required parameters

TELEGRAM_TOKEN="your-bot-token-here"

ADMIN_USER_IDS="123456789,987654321"



# Optional parameters

DATABASE_PATH="./data/bot.db"

LOG_LEVEL="INFO"

DEFAULT_GROUP_NAME="Default Group"

MAX_GROUPS_PER_ADMIN="10"

MAX_MEMBERSHIPS_PER_USER="20"

```



### Running



```bash

# Run the bot

./bin/bot



# Or directly via Go

go run ./cmd/bot

```



---



## ๐Ÿ“– Usage



### For Users



```

/start    โ€” Start working with the bot

/help     โ€” Show help

/groups   โ€” List your groups

/rating   โ€” Top 10 participants

/my       โ€” Your statistics

/events   โ€” Active events

```



### For Administrators



#### 1. Create a Group

```

/create_group

```

The bot will guide you through the creation process and provide an invitation link.



#### 2. Invite Participants

Share the deep-link:

```

https://t.me/your_bot?start=group_abc123

```



#### 3. Create an Event

```

/create_event

```

Interactive process:

1. Select group (if you have multiple)

2. Enter question

3. Choose event type

4. Specify options (for multiple choice)

5. Set deadline

6. Confirm



#### 4. Resolve Event

```

/resolve_event

```

Select the correct answer, and the bot will automatically calculate points and update ratings.



### Additional Admin Commands



```

/list_groups     โ€” List all groups with links

/group_members   โ€” Group members

/remove_member   โ€” Remove member

/edit_event      โ€” Edit event (only without votes)

```



---



## ๐Ÿ— Architecture



### Technology Stack



- **Language**: Go 1.25.5

- **Database**: SQLite with WAL mode

- **Telegram API**: [go-telegram/bot](https://github.com/go-telegram/bot)

- **FSM**: Custom implementation with persistence

- **ID Encoding**: Custom Base-N encoder for short deep-links



### Project Structure



```

.

โ”œโ”€โ”€ cmd/bot/              # Application entry point

โ”œโ”€โ”€ internal/

โ”‚   โ”œโ”€โ”€ bot/             # Telegram handlers and FSM

โ”‚   โ”‚   โ”œโ”€โ”€ handler.go              # Main handler

โ”‚   โ”‚   โ”œโ”€โ”€ event_creation_fsm.go   # Event creation FSM

โ”‚   โ”‚   โ”œโ”€โ”€ event_resolution_fsm.go # Event resolution FSM

โ”‚   โ”‚   โ”œโ”€โ”€ group_creation_fsm.go   # Group creation FSM

โ”‚   โ”‚   โ””โ”€โ”€ message_deletion.go     # Cleanup utilities

โ”‚   โ”œโ”€โ”€ config/          # Configuration management

โ”‚   โ”œโ”€โ”€ domain/          # Business logic

โ”‚   โ”‚   โ”œโ”€โ”€ event_manager.go           # Event management

โ”‚   โ”‚   โ”œโ”€โ”€ rating_calculator.go       # Rating calculation

โ”‚   โ”‚   โ”œโ”€โ”€ achievement_tracker.go     # Achievement tracking

โ”‚   โ”‚   โ”œโ”€โ”€ deeplink_service.go        # Deep-link generation

โ”‚   โ”‚   โ””โ”€โ”€ group_context_resolver.go  # Group context resolution

โ”‚   โ”œโ”€โ”€ encoding/        # Base-N encoding for IDs

โ”‚   โ”œโ”€โ”€ logger/          # Structured logging

โ”‚   โ””โ”€โ”€ storage/         # Repositories and migrations

โ”‚       โ”œโ”€โ”€ fsm_storage.go                  # FSM persistence

โ”‚       โ”œโ”€โ”€ group_repository.go             # Group operations

โ”‚       โ”œโ”€โ”€ group_membership_repository.go  # Membership management

โ”‚       โ””โ”€โ”€ migrations.go                   # DB migrations

โ””โ”€โ”€ data/                # SQLite database

```



### Key Implementation Features



#### ๐Ÿ”„ FSM with Persistence

All interactive processes (event creation, group creation, event resolution) are implemented through finite state machines with state persistence in DB. This allows:

- Continue process after bot restart

- Avoid conflicts between sessions

- Automatically clean up stale sessions (>30 minutes)



#### ๐Ÿ” Data Isolation

Each group is a completely isolated space:

- Events visible only to group members

- Ratings maintained separately

- Achievements earned independently

- Users can have different positions in different groups



#### ๐Ÿ“Š Smart Rating Calculation

The system considers:

- Event complexity (type)

- Choice popularity (minority bonus)

- Reaction speed (early vote bonus)

- History of correct predictions (streaks)



#### ๐Ÿ”— Short Deep-links

Uses custom Base-N encoding to create short and readable invitation links instead of long numeric IDs.



---



## ๐Ÿงช Testing



```bash

# Run all tests

go test ./...



# With verbose output

go test ./... -v



# Only specific package

go test ./internal/bot -v



# With coverage

go test ./... -cover

```



The project includes:

- Unit tests for all components

- Integration tests for FSM

- Property-based tests (gopter) for encoding

- Tests for multi-group scenarios



---



## ๐Ÿค Contributing



We welcome contributions! Here's how you can help:



1. ๐Ÿ› **Report bugs** via Issues

2. ๐Ÿ’ก **Suggest new features** via Discussions

3. ๐Ÿ”ง **Submit Pull Requests**

4. ๐Ÿ“– **Improve documentation**

5. โญ **Star** the project



---



## ๐Ÿ“ License



This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.



---



## ๐Ÿ™ Acknowledgments



- [go-telegram/bot](https://github.com/go-telegram/bot) โ€” excellent library for Telegram Bot API

- [modernc.org/sqlite](https://gitlab.com/cznic/sqlite) โ€” pure Go SQLite driver

- Go community for amazing tools and libraries



---






**Made with โค๏ธ for communities who love predicting the future**



[โฌ† Back to Top](#-telegram-prediction-market-bot)