Reports & History

Keeping tabs on your spending is effortless once you master /recent and /report.

/recent

/recent
/recent food on=2024-12-25
/recent @Travel 2024-10-01..2024-12-31 limit=50
/recent since=2024-10-01 until=2024-10-15

• category can be positional (e.g. /recent Food) or a key-value pair (category=Food).
• Partial matching – You can type just the beginning of a category name and it will match automatically. For example, /recent din will match "Dining Out" if that's the only category starting with "din". If multiple categories match, you'll see a list of options.
• Date filters: Supports since=YYYY-MM-DD, until=YYYY-MM-DD, on=YYYY-MM-DD, or positional range YYYY-MM-DD..YYYY-MM-DD.
• limit caps the total number of rows fetched (max 500).
• per controls how many transactions appear per page (default 10).
• since filters by ISO date. Combine with @wallet for focused audits.
• Inline Prev/Next buttons appear automatically when there are more results. They remember your original filters.

Use /recent limit=2 per=1 during testing to ensure pagination works end-to-end (the integration tests already do this).

/report

/report today
/report last 30 days
/report mtd
/report @Investment ytd
/report since=2025-01-01
/report since=2025-01-01 until=2025-06-30
/report @Travel since=2025-01-01 debts

• Supported ranges include: today, yesterday, week, month, quarter, year, mtd, ytd, last n days/months, etc.
• Use since=YYYY-MM-DD to set a start date (end defaults to today).
• Use until=YYYY-MM-DD to set an end date.
• Combine with @wallet to scope to a specific wallet.
• If the wallet hint matches multiple wallets, the bot prompts you to pick one from a button list.
• The bot groups totals by currency and type (expense, income, debt, receivable) and shows a net figure at the end.

/owed

• /owed - see everyone who owes you money.
• /owed Alex - narrow down to a specific beneficiary.
• Results show total outstanding plus the latest installment/due date.

Category catalogue

Categories are just short text labels attached to each transaction. Filters such as /recent category=Food and the category breakdown inside /report simply read whatever label is stored on the record. To make onboarding easier, every user automatically starts with the following suggestions (the same list described in the Gemini prompt) and /categories reset restores them at any time:

Category	Typical usage
Groceries	Supermarket, bulk household shopping.
Dining Out	Restaurants, cafés, takeaway drinks.
Transportation	Fuel, ride-hailing, public transit, tolls.
Housing & Utilities	Rent, mortgage, electricity, water, internet.
Subscriptions & SaaS	Streaming services, cloud software fees.
Shopping & Personal Care	Apparel, cosmetics, gadgets, general retail.
Entertainment	Movies, concerts, in-app purchases.
Health & Insurance	Clinics, pharmacy, premiums.
Travel	Flights, accommodation, roaming data.
Income	Salary, reimbursements, refunds.
Debt & Repayments	Loan payments, receivables being settled.
Investments	Brokerage top-ups, robo-advisor contributions.

Customising categories

• Per transaction – Tap Edit → Category (or run /transaction edit <id> category=New Label) to overwrite whatever the LLM suggested. The next /recent category=New Label query will instantly use it.
• During capture – Add category=YourLabel to /add or edit the inline fields shown by /recent → Details → Edit to set it before the classifier runs.
• Personalise from Telegram – Use /categories set Name1,Name2,... to replace the built-in list (up to 24 entries). /categories list shows your current set and /categories reset reverts to the defaults.

Using data outside Telegram

• Every command you trigger is backed by the same FastAPI endpoints exposed via the RapiDoc UI (https://your-backend-host/docs/rapidoc).
• Admins can export raw transactions from the database or via /api/transactions for spreadsheets and BI tools.
• Because wallet links are preserved on delete (they just become null), you never lose historical context.