Self-hosted · Telegram · MIT

Receipts in. Ledger out.

(ex)SpenserBot reads receipt photos, PDF invoices, and plain sentences, and writes down the expense — amount, currency, merchant, date, category — with LLM extraction you can correct.

No hosted instance. One Docker container, one SQLite file, your own bot token.

01 What it does

A narrow job, done properly.

One bot, six behaviours. It gets an expense out of whatever you have at hand, and keeps it tidy afterwards.

Python 3.12 · dSPy · SQLite · Docker

01

Receipt photo extraction

Send a photo of any receipt, paper or digital. The amount, currency, merchant, date, and category come back filled in.

02

PDF receipts

Invoices and statements up to 5 pages. A multi-page PDF counts as one receipt, not five.

03

Free-text logging

No receipt at all? Write “lunch 15.50 eur at Mario’s Pizzeria” and it is structured and saved — ideal for cash.

04

Correction loop

If a required field is missing, the bot names it and asks. You can refine up to 3 times before it hands the job back to you.

05

Monthly CSV reports

/report exports the current month with the leading expense key, date, merchant, category, amount, and currency — ready for accounting.

06

Delete with an audit trail

Drop a mistake by key, or from the inline delete button under the confirmation. Deletion is logical, so the record stays auditable.

02 Who it is for

Four kinds of receipt chaser.

Travel & business trips

Log each expense as it happens, then hand finance a clean month instead of a shoebox.

Personal budgeting

Browse month by month with /list and see totals per currency. Spot where the money went.

Freelancer tax prep

Multi-currency by design: every expense keeps its original ISO 4217 currency, with no forced conversion.

Small teams

Each person sees only their own expenses, and a whitelist decides who may use the bot at all.

03 How it works

From receipt to record in four steps.

01

Send

A photo, a PDF, or a sentence.

photoPDF · up to 5 pages“taxi 25 usd”
02

Extract

An LLM fills the fields it can read.

amountcurrencymerchantdatecategory
03

Confirm or correct

The bot says what it understood and names what is missing.

I extracted partial information. Please reply with the missing details: amount, currency
04

Report

Browse with /list, export the month with /report.

expenses-2026-07.csv
user_key,date,merchant,…

04 Reference

Commands and the bottom bar.

Type a command, or tap a button. The reply keyboard stays under the input field for the whole chat.

Tapping a button sends its label as a message, so the keyboard and the commands reach the same handlers. /delete needs the expense key you see in the /list view.

CommandWhat it doesButton
/start Welcome message and usage instructions Help
/add How to track a new expense Add
/list Browse your expenses by month and year, with totals per currency List
/report The current month as a CSV file Report
/delete <key> Delete one expense by its key — also the inline button under a confirmation Delete
/remove How to delete an expense Remove

05 Your data

Your expenses never leave your machine.

There is no (ex)SpenserBot server to trust: you are the operator.

Self-hosted storage

Expenses live in one SQLite file that you own. Inspect it, back it up, or wipe it.

Per-user isolation

Every read and write is scoped to the Telegram user ID that sent it. One user never sees another's rows.

Whitelist with an audit log

Only the Telegram IDs in your whitelist can use the bot. Unauthorized attempts are appended to a log, never processed.

Where a receipt goes

Telegramthe chat you already use
message
Your server
The botpython-telegram-bot · Docker
Expenses./data/expenses.db · SQLite
Whitelist/data/authorized-users.json
extraction request
LLM endpointany OpenAI-compatible API you configure

Extraction calls go from your machine straight to the endpoint you configured. The parsed expense is written only to your local SQLite file.