Add a new expense.

Examples:

• "₹450 at Domino's for dinner, paid via UPI, category Food"

• "Flight ticket ₹3500 for Rahul, category Travel"

Get full details of a single expense by ID.

Update specific fields of an expense. Only supply what you want to change.

Soft-delete an expense (can be restored later with restore_expense). The record stays in the database with is_deleted=1.

Restore a previously deleted expense.

List expenses with powerful multi-dimensional filtering.

Examples:

• "All food expenses in July 2026" → month=7, year=2026, category_id=

• "UPI expenses above ₹500 this month" → payment_method='UPI', min_amount=500

• "Expenses at Domino's" → merchant='Domino'

• "Expenses for Girnar trip" → event_id=

List all categories with their subcategories.

Create a new top-level expense category. Example: name='Fashion', icon='👗'

Rename a category or change its icon.

Delete a category. Subcategories are removed automatically (CASCADE).

Add a subcategory to an existing category. Example: category_id=1, name='Biryani'

Move a subcategory to a different parent category.

Category-wise spending summary. Leave year/month empty for all-time totals.

Full monthly report: total, by category (with %), by payment method, top merchant. Example: year=2026, month=7

Month-by-month spending breakdown for an entire year.

Breakdown of spending by payment method (UPI, Cash, Card, etc.).

Budget vs actual for all categories with budgets set. Returns alert level: 🟢 ok / 🟡 warning (≥80%) / 🔴 danger (≥100%)

Set or update a spending budget for a category in a specific month/year.

Add a recurring expense that auto-creates entries when due. frequency: 'daily' | 'weekly' | 'monthly' | 'yearly' next_due_date: YYYY-MM-DD

Examples: Netflix monthly ₹199, Gym monthly ₹1500, Rent monthly ₹8000

List all active recurring expenses.

Process all overdue recurring expenses — creates actual expense entries for each one and updates next_due_date. Call this daily or at server startup.

Add a friend to track balances with.

List all friends.

Record a money exchange with a friend.

direction options: "i_paid" → I paid for them → they owe me ₹amount "they_paid" → They paid for me → I owe them ₹amount

Examples:

• "Rahul owes me ₹500 for recharge" → direction='i_paid', friend_id=Rahul's id

• "I paid ₹120 for Prince for chai" → direction='i_paid', friend_id=Prince's id

• "Jay paid ₹200 for my food at Domino's" → direction='they_paid', friend_id=Jay's id

Mark balances with a friend as settled. If amount is given, settle exactly that much; otherwise settle everything.

Net balance summary with a specific friend. Returns: who owes whom, and by how much.

Net balance summary across ALL friends. Shows total receivable (others owe you) and total payable (you owe others).

Explains how the minimal debt settlement algorithm works. Great for learning and interview preparation!

Create a group event for expense splitting. member_ids: list of friend IDs to add as participants.

Example: "Girnar Trip" with Rahul (id=1), Prince (id=2), Jay (id=3)

Add a friend to an existing event.

Add an expense to a group event and compute per-member splits.

split_type options: "equal" → split evenly among all members (or included_member_ids) "percentage" → supply split_data={"friend_id": percent, ...} summing to 100 "custom" → supply split_data={"friend_id": amount, ...} summing to total

Returns the computed split immediately so you can verify it.

Example: Hotel ₹4000 paid by Neev, split equally among 4 friends: → each owes ₹1000

Complete event summary including:

• All expenses

• Per-member net balances

• Minimum settlement transactions (who pays whom, how much)

This uses the greedy two-pointer algorithm to minimize the number of transactions.

List all events (active and closed).

Mark an event as closed (all expenses settled).

Natural language expense search.

Claude should use this when the user asks conversational questions about their spending.

Examples: "How much did I spend on food this month?" "Show me Domino's expenses" "All UPI payments above ₹500 in June" "What did I spend at Girnar trip?" "Show my expensive purchases in 2026"

Returns both the matching expenses AND a quick summary (total, count, avg).

Dashboard-style overview: this month's total, category breakdown, and overall balance. Perfect for "Give me a financial overview" or "How am I doing this month?"

Export all expenses for a given month as a CSV string. The CSV is also saved to the /reports/ directory.

Export all expenses for a given month to an Excel file (.xlsx). Returns the file path.