Centpai

𝙷𝚘𝚠 𝚃𝚘 𝚄𝚜𝚎 ✦ 𝙶𝚎𝚝𝚝𝚒𝚗𝚐 𝚂𝚝𝚊𝚛𝚝𝚎𝚍 ✦ 𝙲𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛𝚜 ✦ 𝚂𝚙𝚘𝚗𝚜𝚘𝚛 ✦

Split expenses effortlessly in Telegram with Centpai. Track shared costs, settle balances, and keep everyone in sync — all without leaving your chat.

Important

This project is in active development. New features are being added continuously, and we welcome contributions from the community. If you have any suggestions or feature requests, please feel free to open an issue on GitHub.

How To Use

No setup required — just find @CentpaiBot on Telegram and add it to any group of your choice. The bot will guide you from there.

1. Search for @CentpaiBot on Telegram
2. Add the bot to your group
3. Each member runs /join to register
4. Start adding expenses with /expense_add <Amount> <Category> [split rule]

Getting Started

Prerequisites

• Docker (recommended)
• Python 3.11+ and Poetry
• A Telegram bot token from @BotFather
• A public URL for the webhook — sign up at ngrok and install the CLI

Setup

1. Clone the repository

   git clone https://github.com/yyueda/centpai.git
   cd centpai

2. Create a .env file in the project root, following the example given in .env.example

   With Docker:

   BOT_TOKEN=<your telegram bot token>
   DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/centpai_db
   WEBHOOK_URL=<your public webhook url>
   WEBHOOK_SECRET=<random secret string>

   Without Docker (use your own Postgres credentials):

   BOT_TOKEN=<your telegram bot token>
   DATABASE_URL=postgresql+asyncpg://<user>:<password>@localhost:5432/<database>
   WEBHOOK_URL=<your public webhook url>
   WEBHOOK_SECRET=<random secret string>

   To get your WEBHOOK_URL, you can run ngrok in a separate terminal and copy the Forwarding URL:

   ngrok http 8000
   # Forwarding  https://abc123.ngrok-free.app -> http://localhost:8000

   Why ngrok? Telegram's webhook requires a publicly reachable HTTPS URL to push updates to your bot. Since localhost isn't accessible from the internet, ngrok creates a secure tunnel that forwards Telegram's requests to your local server.

   You can generate a WEBHOOK_SECRET with:

   python -c "import secrets; print(secrets.token_hex(32))"

3. Run with Docker

   docker compose -f docker-compose.dev.yml up --build

   Or without Docker (requires a running Postgres instance on port 5432)

   poetry install
   poetry run uvicorn app.main:app --reload

Sponsor

If you find Centpai useful, consider supporting its development:

Contributors