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.
- Expense
- 20260710-3
- Amount
- 15.50 EUR
- Merchant
- Mario's Pizzeria
- Date
- 2026-07-10
- Category
- Meals
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
Receipt photo extraction
Send a photo of any receipt, paper or digital. The amount, currency, merchant, date, and category come back filled in.
PDF receipts
Invoices and statements up to 5 pages. A multi-page PDF counts as one receipt, not five.
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.
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.
Monthly CSV reports
/report exports the current month with the leading expense key, date, merchant, category, amount, and currency — ready for accounting.
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.
Send
A photo, a PDF, or a sentence.
Extract
An LLM fills the fields it can read.
Confirm or correct
The bot says what it understood and names what is missing.
Report
Browse with /list, export the month with /report.
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.
| Command | What it does | Button |
|---|---|---|
| /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
Extraction calls go from your machine straight to the endpoint you configured. The parsed expense is written only to your local SQLite file.