Summarise who owes you and whom you owe, per friend and per currency.

Calls GET /get_friends once and, from each friend's balance list, renders every non-zero balance per currency, plus per-currency totals: how much you are owed, how much you owe, and the net. Friend balances already combine group and non-group expenses. Sign convention: positive = the friend owes you (owed to you); negative = you owe the friend. Zero balances are hidden unless include_zero is true; the optional currency filter keeps a single currency (applied locally — the endpoint takes no filter). An amount Splitwise sends that is not a plain decimal, or an entry with no currency, is shown raw and flagged, and left out of the totals.

When to Use:

• "How much am I owed / do I owe overall?", "who owes me money?", "my USD balance".

• Before settling up, to see every open balance in one call.

When NOT to Use:

• For balances inside ONE group and who pays whom there (use splitwise_get_group_balances).

• For friend profiles, e-mails or per-group breakdowns (use splitwise_get_friends / splitwise_get_friend).

• To find a friend's id from a name (use splitwise_resolve_friend).

Returns: Markdown: the sign convention, a totals table (Currency | You are owed | You owe | Net) and a table of friends (First Last (id N) with e.g. +12.50 USD, -3.00 PEN; with include_zero, settled up or no USD balance), capped at 50 rows (totals cover every friend except the flagged entries). JSON: {sign_convention, currency_filter, totals: {CUR: {owed_to_you, you_owe, net}}, unparsed: [{friend_id, currency_code, amount, reason}], friend_count, friends: [raw friend objects]} with you_owe as a positive magnitude and money as 2-decimal strings.

Examples:

• params = {}

• params = {"currency": "USD"}

• params = {"include_zero": true, "response_format": "json"}

Error Handling: A bad currency (not 3 letters) is rejected before any call. 401 means the API key is missing or was regenerated; 429 means back off (Retry-After). Errors come back as an Error ... string.

Show each member's balance in one group and who should pay whom to settle it.

Calls GET /get_group/{group_id} and renders the members' non-zero balances per currency, then the group's debts as From → To amount CUR (From owes To), with names resolved from the group's own members (an id not among them is shown as user N). Uses simplified_debts; when Splitwise returns none, falls back to original_debts and says so. Sign convention: positive = the member is owed by the group; negative = the member owes the group. Settled-up members are listed by name only. An amount that is not a plain decimal is shown raw and flagged (unparsed).

When to Use:

• "Who owes whom in the Trip group?", "how do we settle up the apartment?".

• Before recording a settle-up payment, to get the exact amounts and user ids.

When NOT to Use:

• For your balances across all friends (use splitwise_get_balances).

• For non-group expenses: group_id 0 is the non-group pseudo-group; /get_group/0 answers but lists only you as a member, so per-friend balances come from splitwise_get_balances, not from here.

• For the group's details, invite link or membership changes (use splitwise_get_group, splitwise_add_user_to_group, splitwise_remove_user_from_group).

• To find a group id from its name (use splitwise_resolve_group / splitwise_get_groups).

Returns: Markdown: a member table (First Last (id N) | +20.00 USD), the settled-up members, and the debts list with its source (simplified_debts or original_debts), capped at 50 rows each. JSON: {group: {id, name}, sign_convention, members: [raw members], debts_source: "simplified_debts" | "original_debts" | null, debts: [raw debts]}.

Examples:

• params = {"group_id": 12345}

• params = {"group_id": 12345, "response_format": "json"}

Error Handling: 403 means you are not a member of that group; 404 means the id is wrong or the group was deleted (splitwise_undelete_group restores it) — or, for group_id 0, that the pseudo-group is not served here (use splitwise_get_balances). Errors come back as an Error ... string.

List the comments on one Splitwise expense.

Calls GET /get_comments?expense_id=… and renders one row per comment: its id, the author as First Last (id N), the type (System = written by Splitwise, e.g. an edit log; User = written by a person), when it was created, and the text.

When to Use:

• To read the discussion or the edit history on an expense.

• To find a comment's id before deleting it with splitwise_delete_comment.

When NOT to Use:

• To read the expense itself (cost, shares) — use splitwise_get_expense.

• To see recent activity across all expenses and groups — use splitwise_get_notifications.

• To find an expense id from a description — use splitwise_get_expenses.

Returns: Markdown: a table | Id | Author | Type | Created | Content | (at most 50 rows, the rest counted; each text capped at 2,000 characters, the cut counted). JSON: {"expense_id", "count", "comments": [raw comment objects]}.

Examples:

• params = {"expense_id": 51023}

• params = {"expense_id": 51023, "response_format": "json"}

Error Handling: 404 means the expense id does not exist or was deleted; 403 means you are not part of that expense. Errors come back as an Error ... string, never raised.

Add a comment to a Splitwise expense.

Write — refused unless SPLITWISE_ALLOW_WRITES=1. Calls POST /create_comment with expense_id and content. Everyone on the expense can see the comment. Not idempotent: calling it twice posts the comment twice.

When to Use:

• To leave a note on an expense ("paid in cash", "includes the tip").

When NOT to Use:

• To change the expense's own description or notes — use splitwise_update_expense.

• To read existing comments — use splitwise_get_comments.

Returns: A confirmation echoing the comment Splitwise returned: its id, the expense id, the author, the type, the creation time and the text.

Examples:

• params = {"expense_id": 51023, "content": "Paid in cash, settled at dinner."}

Error Handling: Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. A blank content is rejected before any call. 404 = the expense does not exist or was deleted; 403 = you are not part of it. On a timeout or 5xx the outcome is UNKNOWN — read the comments back with splitwise_get_comments before retrying, or the comment may be posted twice. Undo with splitwise_delete_comment.

Delete a comment from a Splitwise expense (destructive; comments have no undelete).

Write — refused unless SPLITWISE_ALLOW_WRITES=1. Calls POST /delete_comment/{id}. Splitwise answers with the deleted comment, which this tool renders so you can see exactly what was removed. There is NO undelete for comments in the Splitwise API — if needed, re-post the text with splitwise_create_comment (it gets a new id and a new timestamp).

When to Use:

• To remove a comment you posted by mistake (get its id from splitwise_get_comments).

When NOT to Use:

• To delete the expense itself — use splitwise_delete_expense.

• When you only know the comment's text — list them with splitwise_get_comments first.

Returns: A confirmation echoing the deleted comment as Splitwise returned it: id, expense id, author, type, created/deleted times and the text.

Examples:

• params = {"comment_id": 79800950}

Error Handling: Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. 404 = the comment id does not exist or is already gone; 403 = you are not allowed to delete it (you are not part of that expense). Errors come back as an Error ... string, never raised.

List expenses, newest first, optionally filtered by group, friend and date range.

Calls GET /get_expenses. Splitwise includes DELETED expenses in this list; they are hidden by default and the response says how many were hidden (include_deleted=true shows them, tagged [deleted]). Settle-up payments are tagged [settle-up]. Each row shows the date, description, full cost, group, who paid (shares with paid_share > 0) and — when current_user_id is given — your net on that expense.

Sign convention: "Your net" is your net_balance on the expense; positive = owed to you (you paid more than your share), negative = you owe.

When to Use:

• "What did we spend in the Lima trip group?" (group_id) or "expenses with Ana" (friend_id).

• Finding an expense id before reading, updating or deleting it.

• Reviewing recent activity in a date window (dated_after / dated_before).

When NOT to Use:

• To see one expense's full split, repayments and comments (use splitwise_get_expense).

• To get balances per friend or per group (use splitwise_get_balances / splitwise_get_group_balances).

• To turn a group or friend NAME into an id (use splitwise_resolve_group / splitwise_resolve_friend).

Returns: Markdown: a table | id | Date | Description | Cost | Group | Paid by | (Your net) | plus the hidden-deleted count and the next offset. JSON: {count, returned_by_api, hidden_deleted, limit, offset, has_more, next_offset, expenses: [raw expense objects]}.

Pagination: limit (1-100, default 20) is sent to Splitwise; has_more is true when Splitwise returned a full page, and the next offset is offset + rows returned by Splitwise (deleted rows count toward it even when hidden). Markdown shows at most 50 rows; the note under the table gives the offset to continue from.

Examples:

• params = {"group_id": 12345, "dated_after": "2026-09-01"}

• params = {"friend_id": 678, "limit": 50, "current_user_id": 491923}

• params = {"limit": 20, "offset": 20, "response_format": "json"}

Error Handling: Passing both group_id and friend_id is refused (Splitwise would ignore friend_id). 401 → API key missing/regenerated; 403 → you are not a member of that group; 429 → back off for Retry-After seconds.

Read one expense in full: cost, group, category, every share, repayments and comments.

Calls GET /get_expense/{id}. The shares table shows what each person paid, owed and their net on this expense; repayments say who owes whom for it; comments are listed with author and time. A deleted expense is still readable and is flagged as deleted.

Sign convention: Net = paid − owed; positive = that person is owed money on this expense, negative = they owe.

When to Use:

• Before splitwise_update_expense, to see the current shares (an update with shares replaces ALL of them).

• "Who paid for dinner and how was it split?"

• Checking that a create/update landed the way it was intended.

When NOT to Use:

• To list or search expenses (use splitwise_get_expenses).

• To read only the comments thread (use splitwise_get_comments).

• For overall balances (use splitwise_get_balances).

Returns: Markdown: header fields, a | Person | Paid | Owed | Net | table, repayments From → To amount, and a comments table. JSON: the raw expense object.

Examples:

• params = {"expense_id": 3456789012}

• params = {"expense_id": 3456789012, "response_format": "json"}

Error Handling: 404 → wrong id; 403 → you are not part of that expense; 401 → API key problem.

Create an expense with exactly one split mode; the shares are checked locally before sending.

Calls POST /create_expense. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1 (the server's client enforces it; this tool never bypasses it). Undo with splitwise_delete_expense. NOT idempotent: every successful call creates a new expense — never retry blindly after a timeout; list first.

Pick EXACTLY ONE split mode:

• A split_equally: true — a GROUP expense (group_id > 0) that YOU paid, split equally among all group members by Splitwise.

• B shares: [...] — explicit shares, one per participant (≥ 2), each with user_id OR email+first_name+last_name, a paid_share and an owed_share (2-decimal strings). Σ paid_share and Σ owed_share must each equal cost.

• C equal_split_between: [user ids] — equal split between these people (≥ 2, INCLUDING the payer). The payer is paid_by_user_id, or you when omitted (one GET /get_current_user). Owed shares are cost / n rounded down to the cent; the leftover cents go on the payer so the sums close (10.00 / 3 → 3.34 payer, 3.33, 3.33).

Shares that do not add up are refused with an error naming the mismatch BEFORE any request. Shares are sent flattened as users__{i}__user_id|email|first_name|last_name| paid_share|owed_share. Money is a 2-decimal string, never a float.

When to Use:

• "Add 90.00 for dinner in the Cusco group, split equally" (mode A).

• "I paid 30.00 for a taxi with Ana and Luis, split three ways" (mode C).

• "Ana paid 50.00; I owe 20.00 of it and she owes 30.00" (mode B).

When NOT to Use:

• To change an existing expense (use splitwise_update_expense).

• To find a friend's, group's or category's id by name (use splitwise_resolve_friend, splitwise_resolve_group, splitwise_resolve_category first).

• To comment on an expense (use splitwise_create_comment).

Returns: A confirmation echoing Splitwise's response: the literal errors value (empty {} means accepted), and per returned expense its id, description, cost, group, date and the shares exactly as Splitwise stored them.

Examples:

• params = {"cost": "90.00", "description": "Dinner", "group_id": 12345, "split_equally": true}

• params = {"cost": "30.00", "description": "Taxi", "equal_split_between": [491923, 678, 910]}

• params = {"cost": "50.00", "description": "Groceries", "currency_code": "PEN", "shares": [ {"user_id": 678, "paid_share": "50.00", "owed_share": "30.00"}, {"user_id": 491923, "paid_share": "0.00", "owed_share": "20.00"}]}

Error Handling: Local refusals (no request made): more or fewer than one split mode, shares that do not sum to cost, a share with both or neither identity, duplicate participants, split_equally without a group, a payer missing from equal_split_between. Splitwise answers 200 even when it rejects an expense — the client turns a non-empty errors into Error: Splitwise rejected the request…; if that body still carried an expense object the error adds "Splitwise still returned N expense object(s) … may have landed" with the ids, so read back before retrying. On a timeout or 5xx the outcome is UNKNOWN: check splitwise_get_expenses before retrying.

Change an existing expense — only the fields given are sent.

Calls POST /update_expense/{id}. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1 (enforced by the server's client).

WARNING: shares REPLACES ALL existing shares. Splitwise treats any users__* key as the complete new split, so list EVERY participant with their paid_share and owed_share — sending only the person who changed drops everyone else from the expense. Read the current split first with splitwise_get_expense.

No undo tool — to revert, re-send the previous values read with splitwise_get_expense first.

When shares is given, Σ paid_share and Σ owed_share must each equal the cost: the new cost if you pass one, otherwise the expense's current cost (read once with GET /get_expense/{id}). A mismatch is refused before the update is sent. Changing cost WITHOUT shares leaves the split to Splitwise, which may reject it if the current shares no longer add up — pass both to be explicit.

When to Use:

• Fix a description, date, category or currency.

• Change the amount together with the full new split.

• Move an expense to another group (group_id; 0 = no group).

When NOT to Use:

• To create a new expense (use splitwise_create_expense).

• To delete or restore one (use splitwise_delete_expense / splitwise_undelete_expense).

• To look up ids by name (use splitwise_resolve_friend / splitwise_resolve_group / splitwise_resolve_category).

Returns: A confirmation echoing Splitwise's response: the literal errors value and the expense as returned (id, description, cost, group, date, shares).

Examples:

• params = {"expense_id": 3456789012, "description": "Dinner (incl. tip)"}

• params = {"expense_id": 3456789012, "cost": "60.00", "shares": [ {"user_id": 491923, "paid_share": "60.00", "owed_share": "30.00"}, {"user_id": 678, "paid_share": "0.00", "owed_share": "30.00"}]}

Error Handling: Refused locally (nothing sent) when no field is given, when shares do not add up, or a share has both/neither identity. Splitwise answers 200 even on failure — the client turns a non-empty errors into Error: Splitwise rejected the request…; if that body still carried an expense object the error adds "Splitwise still returned N expense object(s) … may have landed", so read the expense back before retrying. 404 → wrong id; 403 → not your expense.

Delete an expense (Splitwise keeps it as deleted; restore with splitwise_undelete_expense).

Calls POST /delete_expense/{id}. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1 (enforced by the server's client). Deleting changes every participant's balances. Restore with splitwise_undelete_expense and the same id.

When to Use:

• Remove a duplicate or mistaken expense.

When NOT to Use:

• To fix an amount or split (use splitwise_update_expense).

• To remove a whole group with its expenses (use splitwise_delete_group).

Returns: The success value Splitwise returned for the deletion, and the undo hint.

Examples:

• params = {"expense_id": 3456789012}

Error Handling: Splitwise answers 200 even when it refuses — the client turns success: false / a non-empty errors into Error: Splitwise rejected the request…. 404 → wrong id; 403 → not your expense.

Restore a deleted expense.

Calls POST /undelete_expense/{id}. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1 (enforced by the server's client). The expense comes back with its original shares, so balances change again.

When to Use:

• Undo a splitwise_delete_expense.

• Bring back an expense seen as [deleted] in splitwise_get_expenses with include_deleted=true.

When NOT to Use:

• On an expense that is not deleted (nothing to restore).

• To restore a deleted group (use splitwise_undelete_group).

Returns: The success value Splitwise returned.

Examples:

• params = {"expense_id": 3456789012}

Error Handling: Splitwise answers 200 even when it refuses — the client turns success: false into Error: Splitwise rejected the request…. 404 → wrong id; 403 → not your expense.

List your Splitwise friends with their balance per currency.

Calls GET /get_friends. One row per friend: First Last (id N), e-mail, registration status (confirmed | invited | dummy) and the overall balance per currency. Sign convention: positive = they owe you; negative = you owe them. JSON mode returns the raw friend objects, including groups[] with the balance per shared group (group 0 = non-group expenses).

When to Use:

• To see who owes you / whom you owe, per friend and currency.

• To find a friend's user id before building expense shares or adding them to a group.

• With only_with_balance=true to list only the friendships that are not settled up.

When NOT to Use:

• To find a friend by a fuzzy name (use splitwise_resolve_friend).

• For totals per currency across all friends (use splitwise_get_balances).

• For one friend's detail incl. per-group balances (use splitwise_get_friend).

• For balances inside one group (use splitwise_get_group_balances).

Returns: Markdown: a header with the sign convention and counts, then a table (Friend | Email | Status | Balance), capped at 50 rows with a note when more exist. JSON: {"count", "only_with_balance", "friends": [raw friend objects]}.

Examples:

• All friends: params = {}

• Only open balances: params = {"only_with_balance": true}

• Raw objects with per-group balances: params = {"response_format": "json"}

Error Handling: 401 means the API key is missing or revoked (https://secure.splitwise.com/apps); 429 means back off and retry later.

Get one Splitwise friend with their overall and per-group balances.

Calls GET /get_friend/{id}. Renders the friend as First Last (id N), e-mail, registration status, the overall balance per currency, the balance in each shared group (group 0 = non-group expenses) and when the friendship last changed. Sign convention: positive = they owe you; negative = you owe them.

When to Use:

• To see how a balance with one friend splits across shared groups.

• To confirm a user id belongs to a friend before using it in an expense.

When NOT to Use:

• To list every friend (use splitwise_get_friends).

• To turn a name into an id (use splitwise_resolve_friend).

• For a user who is not a friend (use splitwise_get_user).

Returns: Markdown: a summary block plus a "Shared groups" list. JSON: the raw friend object.

Examples:

• params = {"friend_id": 4821}

• params = {"friend_id": 4821, "response_format": "json"}

Error Handling: 404 means the id is not one of your friends (or does not exist); 401 means the API key is missing or revoked.

Add one person as a Splitwise friend by e-mail. 🔒 Needs SPLITWISE_ALLOW_WRITES=1.

Calls POST /create_friend with user_email (+ user_first_name / user_last_name when given). If an account already exists for that e-mail the names are ignored; if not, Splitwise creates an invited user and user_first_name is required. If you don't know whether they have an account, pass user_first_name; it is ignored for existing users. Adding someone without an account probably sends them an invitation e-mail (unverified; the live smoke t10 confirms). Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. There is no undo tool; remove a friend with splitwise_delete_friend.

When to Use:

• To befriend one person so you can share non-group expenses with them.

When NOT to Use:

• To add several people at once (use splitwise_create_friends).

• To add someone to a group (use splitwise_add_user_to_group).

• To check whether someone is already a friend (use splitwise_get_friends or splitwise_resolve_friend).

Returns: A confirmation echoing the friend Splitwise returned: First Last (id N), e-mail and registration status.

Examples:

• Existing user: params = {"user_email": "grace@example.com"}

• New user: params = {"user_email": "alan@example.com", "user_first_name": "Alan", "user_last_name": "Turing"}

Error Handling: Error: … writes are disabled → set SPLITWISE_ALLOW_WRITES=1. A 400 usually means an invalid e-mail or a missing first name for a new user. On a 5xx/timeout the outcome is UNKNOWN — check splitwise_get_friends before retrying.

Add several people as Splitwise friends in one call. 🔒 Needs SPLITWISE_ALLOW_WRITES=1.

Calls POST /create_friends with the list flattened to users__{i}__email / users__{i}__first_name / users__{i}__last_name (index from 0). Names matter only for people without a Splitwise account yet. Splitwise answers HTTP 200 even when it rejects entries, so success is read from the body's errors. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. There is no undo tool; remove a friend with splitwise_delete_friend.

When to Use:

• To befriend a list of people (e.g. trip companions) before sharing expenses.

When NOT to Use:

• For a single person (use splitwise_create_friend).

• To put people in a group (use splitwise_create_group / splitwise_add_user_to_group).

Returns: A confirmation listing every user Splitwise returned (First Last (id N), e-mail, registration status) and the body's errors (none on success). On a rejected batch the Error: is followed by the users Splitwise still listed in users[] (probably the ones it added) and a read-back hint.

Examples:

• params = {"friends": [{"email": "grace@example.com"}, {"email": "alan@example.com", "first_name": "Alan", "last_name": "Turing"}]}

Error Handling: Duplicate e-mails in the list are rejected locally before any call. If Splitwise reports any error the call is returned as an Error: — the people its response still listed are named under it (probably added), so read back with splitwise_get_friends before retrying. On a 5xx/timeout the outcome is UNKNOWN.

Remove a friendship (unfriend a user). 🔒 Needs SPLITWISE_ALLOW_WRITES=1. Destructive.

Calls POST /delete_friend/{id} with the friend's user id. Splitwise answers HTTP 200 even when it refuses, so the outcome is read from the body's success / errors. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. There is no undelete for friendships — re-add with splitwise_create_friend.

When to Use:

• The user explicitly asked to remove someone from their friends list.

When NOT to Use:

• To remove someone from a group (use splitwise_remove_user_from_group).

• To settle a balance (record the repayment as an expense via splitwise_create_expense).

• When the id is uncertain — confirm it first with splitwise_resolve_friend or splitwise_get_friend.

Returns: A confirmation with the user id and the body's success value.

Examples:

• params = {"friend_id": 4821}

Error Handling: Error: … writes are disabled → set SPLITWISE_ALLOW_WRITES=1. If Splitwise refuses, its errors message is returned as Error: Splitwise rejected the request …. 404 means the id is not a friend.

List every group you belong to, with members count and balances per currency.

Calls GET /get_groups and renders one row per group: name, id, type, number of members and the balance column. With current_user_id the column is YOUR balance in that group; without it, members' non-zero balances are listed compactly (at most 6 per group — splitwise_get_group has the rest). Group id 0 is Splitwise's pseudo-group for non-group expenses. Sign convention: positive = owed to that member (with current_user_id: owed to you); negative = they (you) owe.

When to Use:

• To find a group's id before reading, adding an expense to it, or changing its members.

• For an overview of where you owe or are owed money, group by group.

When NOT to Use:

• To match a group by a fuzzy name (use splitwise_resolve_group).

• For one group's members, debts and invite link (use splitwise_get_group).

• For balances per friend across all groups (use splitwise_get_balances / splitwise_get_friends).

Returns: A markdown table or, with response_format=json, {"count", "offset", "shown", "has_more", "next_offset", "groups": [raw group objects]}.

Pagination: Splitwise returns every group at once; the tool shows 50 per call. When more remain it reports the next offset — call again with offset set to it.

Examples:

• params = {}

• params = {"current_user_id": 491923}

• params = {"offset": 50, "response_format": "json"}

Error Handling: 401 → the API key is missing or was regenerated; network errors are reported as Error: ....

Read one group: its members with balances, who owes whom, and the invite link.

Calls GET /get_group/{id}. Members are rendered First Last (id N) with every non-zero balance per currency. Debts are rendered A → B 12.50 USD (A owes B), names resolved from the group's own members; the simplified debts are shown, or the original debts (labelled as such) when Splitwise returned no simplified ones. Sign convention for member balances: positive = that member is owed money; negative = they owe. Group id 0 is the pseudo-group for non-group expenses.

When to Use:

• To see who owes whom inside a group before settling up.

• To get a member's user id before removing them or building expense shares.

• To fetch the group's invite link.

When NOT to Use:

• To list all your groups (use splitwise_get_groups), or find one by name (splitwise_resolve_group).

• For the group's expenses (use splitwise_get_expenses with group_id).

Returns: A markdown block (name, type, settings, members, debts, invite link; members and debts capped at 50 each, with a note) or, with response_format=json, the raw group object.

Examples:

• params = {"group_id": 12345}

• params = {"group_id": 12345, "response_format": "json"}

Error Handling: 403 → you are not a member of that group; 404 → wrong id or the group was deleted (see splitwise_undelete_group).

Create a group, optionally with members (you are added automatically). 🔒 write.

Calls POST /create_group with name, group_type, simplify_by_default and the members flattened to users__{i}__user_id or users__{i}__email / users__{i}__first_name / users__{i}__last_name. Each member is EITHER an existing user_id OR an email + first_name (+ last_name) to invite — checked locally before any call. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Undo: splitwise_delete_group with the returned id.

When to Use:

• To start a new shared-expenses group (a trip, a flat, a couple).

When NOT to Use:

• To add someone to an existing group (use splitwise_add_user_to_group).

• To bring back a deleted group (use splitwise_undelete_group).

• To find a friend's user id by name first (use splitwise_resolve_friend).

Returns: A confirmation echoing what Splitwise returned: the new group's name, id, type and members, plus how many members were requested vs returned (a silently dropped invite shows up there).

Examples:

• params = {"name": "Lima trip", "group_type": "trip", "members": [{"user_id": 5823}]}

• params = {"name": "Flat", "group_type": "home", "simplify_by_default": true, "members": [{"email": "ana@example.com", "first_name": "Ana", "last_name": "Diaz"}]}

Error Handling: A member with both or neither identity is rejected before the call. Splitwise's 400 field errors (e.g. a blank name) are surfaced as Error (400): ....

Delete a group and all its expenses — for every member, not just you. 🔒 destructive write.

Calls POST /delete_group/{id}. Splitwise destroys the group's associated records: every expense in it disappears for all members. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Undo: splitwise_undelete_group with the same id restores the group and its expenses.

When to Use:

• Only when the user explicitly asked to delete this group. Confirm the id first with splitwise_get_group, and run splitwise_get_expenses with group_id so the user knows how many expenses will go with it.

When NOT to Use:

• To leave a group or drop one member (use splitwise_remove_user_from_group).

• To delete a single expense (use splitwise_delete_expense).

• With a group NAME — resolve it to an id first (use splitwise_resolve_group).

Returns: A confirmation with the success value Splitwise returned and how to undo it — or, when the body does not say success: true, a note to verify before reporting it as deleted.

Examples:

• params = {"group_id": 12345}

Error Handling: A refusal that comes back as HTTP 200 with success: false is reported as Error: Splitwise rejected the request ...; 403 → not a member; 404 → wrong id or already deleted.

Restore a deleted group (and its expenses). 🔒 write.

Calls POST /undelete_group/{id}. Splitwise answers HTTP 200 even when this fails and puts the outcome in success / errors; the client turns a failure into an error, and this tool reports the group as restored only when the body says success: true. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Undo: splitwise_delete_group.

When to Use:

• To bring back a group deleted by mistake (splitwise_delete_group).

When NOT to Use:

• To restore one expense (use splitwise_undelete_expense).

• To re-add a removed member (use splitwise_add_user_to_group).

• With a group NAME — resolve it to an id first (use splitwise_resolve_group).

Returns: A confirmation with the success / errors values Splitwise returned — or, when the body does not say success: true, a note to verify before reporting it as restored.

Examples:

• params = {"group_id": 12345}

Error Handling: success: false / non-empty errors come back as Error: Splitwise rejected the request ....

Add a person to a group, by user id or by inviting a name + email. 🔒 write.

Calls POST /add_user_to_group with group_id plus EITHER user_id OR all of first_name, last_name, email (a oneOf, checked locally before any call; an invited email may receive a Splitwise invitation). Splitwise answers HTTP 200 even on failure; the client turns success: false / non-empty errors into an error, and the person is reported as added only when the body says success: true and returns the user. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Undo: splitwise_remove_user_from_group with the returned user id.

When to Use:

• To add a friend (user id) or a new person (name + email) to an existing group.

When NOT to Use:

• To create a group with its members in one call (use splitwise_create_group).

• To find a friend's user id by name (use splitwise_resolve_friend first), or a group's id by name (use splitwise_resolve_group).

Returns: A confirmation with the user Splitwise returned (First Last (id N)) and its success value.

Examples:

• params = {"group_id": 12345, "user_id": 5823}

• params = {"group_id": 12345, "first_name": "Ana", "last_name": "Diaz", "email": "ana@example.com"}

Error Handling: Both or neither identity → rejected before the call; success: false → Error: Splitwise rejected the request ...; 403 → you are not a member of the group.

Remove a member from a group. 🔒 destructive write.

Calls POST /remove_user_from_group with group_id and user_id. Splitwise refuses when the member has a non-zero balance in the group (settle up first) — and it does so with HTTP 200 + success: false, which the client turns into an error. The member is reported as removed only when the body says success: true. Refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Undo: splitwise_add_user_to_group with the same ids.

When to Use:

• To drop someone (or yourself) from a group whose balances are settled.

When NOT to Use:

• To delete the whole group (use splitwise_delete_group).

• To check balances first (use splitwise_get_group).

• With a group NAME — resolve it to an id first (use splitwise_resolve_group).

Returns: A confirmation with the success / errors values Splitwise returned — or, when the body does not say success: true, a note to verify before reporting it as removed.

Examples:

• params = {"group_id": 12345, "user_id": 5823}

Error Handling: A non-zero balance (or any refusal) → Error: Splitwise rejected the request ... with Splitwise's message; 403 → you are not a member of the group.

Verify connectivity and the API key against Splitwise, and report the write kill-switch.

Calls GET /get_current_user with the configured personal API key and renders who you are logged in as (name, id, email, default currency, locale, unread notifications). Also states whether writes are enabled (SPLITWISE_ALLOW_WRITES).

When to Use:

• As the first call after configuring the server, to confirm the key works.

• To learn your own user id before building expense shares.

• To debug a 401 (key missing / regenerated) before trying other tools.

When NOT to Use:

• To read balances (use splitwise_get_balances / splitwise_get_friends).

• To change profile settings (use splitwise_update_user).

Returns: A markdown block with the base URL, the kill-switch state, connectivity, and the current user — or an Error ... string describing the failure.

Error Handling: 401 means the key is missing, mistyped, or was regenerated at https://secure.splitwise.com/apps; a connection error means the API URL or the network is wrong. Without a configured key the tool returns the config state and says what to set, without calling the API.

List Splitwise's expense categories: each parent with its subcategories and their ids.

Calls GET /get_categories once and caches the answer in-process for 24 h (the list is static); refresh: true refetches. Expenses must use a subcategory id as category_id — a parent id is not accepted. When nothing fits, use the "Other" subcategory under the closest parent (or "General" under "Uncategorized"). Names come back in the account's locale (a Spanish account sees "Supermercado", "Taxi", "Avión" — not the English names from Splitwise's docs); the ids are the same everywhere.

When to Use:

• To browse the categories before creating or recategorising an expense.

• To list one parent's subcategories (parent: "food").

When NOT to Use:

• To turn a category name into an id — use splitwise_resolve_category, which ranks subcategories by similarity and says when one is a clear match.

• For currencies — use splitwise_get_currencies.

Returns: A markdown table with one row per parent (flagged as not usable for expenses) and its subcategories as Name (id N), capped at 50 parents; or the raw {"categories": [...]} objects (with icons and nested subcategories) when response_format is json.

Examples: params = {} params = {"parent": "transport"} params = {"refresh": true, "response_format": "json"}

Error Handling: A 401 means the API key is missing or was regenerated. A failed fetch is never cached (a failed refresh keeps the previous cached list); a parent filter that matches nothing lists the parent names to pick from.

List the currency codes Splitwise accepts, optionally filtered by a substring.

Calls GET /get_currencies once and caches the answer in-process for 24 h (the list is static); refresh: true refetches. Codes are mostly ISO 4217 plus a few colloquial ones (e.g. BTC); each comes with its display unit ($, S/, €).

When to Use:

• To check that a currency code is accepted before using it as currency_code on an expense or as a user's default_currency.

• To find a code from its symbol (query: "€").

When NOT to Use:

• For balances per currency — use splitwise_get_balances.

• For categories — use splitwise_get_categories.

Returns: A markdown table of Code | Unit (capped at 50 rows; narrow with query), or the raw {"currencies": [{currency_code, unit}]} objects when response_format is json.

Examples: params = {} params = {"query": "pen"} params = {"query": "eur", "response_format": "json"}

Error Handling: A 401 means the API key is missing or was regenerated. A failed fetch is never cached; a query that matches nothing says so instead of returning an empty table.

Turn a friend's name (or email) into their Splitwise user id, with ranked fuzzy candidates.

Calls GET /get_friends (not cached — friends change) and scores every friend with difflib.SequenceMatcher on case- and accent-folded text: the best of "first last", the first name, the last name, the email local-part and the full email. Returns the top limit candidates with their scores.

A friend is resolved ONLY on an exact match (1.000 on one of those fields, for exactly one friend, and no other friend's name or email starting with the query). A wrong id here is a wrong person — the expense, the group membership or the deletion lands on someone else — so a close-but-not-exact candidate ("Daniela" vs "Daniel", 0.923) is reported as probable and must be confirmed with the user. No fuzzy candidate is offered for a query under 4 characters or whose numbers differ.

When to Use:

• Before splitwise_create_expense, splitwise_add_user_to_group, splitwise_get_friend or splitwise_delete_friend, when the user named a person ("split it with Jon").

When NOT to Use:

• For balances with each friend — use splitwise_get_balances / splitwise_get_friends.

• For groups or categories — use splitwise_resolve_group / splitwise_resolve_category.

• Someone who is not your friend yet: they will not be listed — add them with splitwise_create_friend.

Returns: The resolution line plus a markdown table (rank, First Last (id N), email, score, matched on); or, with response_format json, {query, resolution, ambiguous_count, reason, resolved, probable, candidates: [{id, first_name, last_name, email, score, matched_on}]} where resolution is exact | probable | ambiguous | none, ambiguous_count (always present, 0 unless ambiguous) says how many candidates are in contention, resolved is set only for exact, and probable only for probable.

Examples: params = {"query": "Jon"} params = {"query": "maria garcia", "limit": 3, "response_format": "json"}

Error Handling: A 401 means the API key is missing or was regenerated. With no friends at all the tool says so. Anything but exact means: ask the user, do not pick.

Turn a group's name into its Splitwise group id, with ranked fuzzy candidates.

Calls GET /get_groups (not cached — groups change) and scores every group name with difflib.SequenceMatcher on case- and accent-folded text. Returns the top limit candidates with their scores. Group id 0 is Splitwise's pseudo-group for non-group expenses (group_id: 0 = no group).

A group is resolved ONLY on an exact name match (1.000, for exactly one group, and no other group name starting with the query — "Peru trip" next to "Peru trip 2026" is ambiguous). A close-but-not-exact name is reported as probable and must be confirmed with the user; a query whose numbers differ ("peru trip 2025" vs "Peru trip 2026") or that is under 4 characters gets no fuzzy candidate at all.

When to Use:

• Before splitwise_create_expense, splitwise_get_group, splitwise_get_expenses, splitwise_add_user_to_group or splitwise_delete_group, when the user named a group ("the Peru trip").

When NOT to Use:

• To list every group with balances — use splitwise_get_groups.

• For people or categories — use splitwise_resolve_friend / splitwise_resolve_category.

Returns: The resolution line plus a markdown table (rank, Name (id N), type, members, score); or, with response_format json, {query, resolution, ambiguous_count, reason, resolved, probable, candidates: [{id, name, group_type, members_count, pseudo_group, score}]} where resolution is exact | probable | ambiguous | none, ambiguous_count (always present, 0 unless ambiguous) says how many candidates are in contention, resolved is set only for exact, and probable only for probable.

Examples: params = {"query": "peru trip"} params = {"query": "home", "limit": 3, "response_format": "json"}

Error Handling: A 401 means the API key is missing or was regenerated. With no groups the tool says so. Anything but exact means: ask the user, do not pick.

Turn a category name into the subcategory id an expense needs, with ranked fuzzy candidates.

Reads the categories from GET /get_categories through the same 24 h in-process cache as splitwise_get_categories (refresh: true refetches). Every subcategory is scored with difflib.SequenceMatcher on case- and accent-folded text — the best of its name, each piece of the name split on / and spaces ("phone" → TV/Phone/Internet), and "Parent Subcategory" (so "transportation other" picks the right "Other").

Subcategories are listed first and are the only ones that can be resolved: exactly one exact (1.000) match, or — with no exact match — exactly one scoring ≥ 0.85 (unique_strong; a wrong category is cheap to fix with splitwise_update_expense). Either way no other subcategory may start with the query ("tax" next to Taxi and Taxes is ambiguous), a fuzzy match needs a query of 4+ characters, and digits in the query must match. The closest parent categories follow, flagged "parent — not usable for expenses", with their subcategories so you can pick one; a parent scores the better of its own name and its best subcategory (so "groceries" surfaces "Food and drink").

The names scored are the ones Splitwise returns for this account's locale: on a Spanish account "groceries" finds nothing but "supermercado" resolves. Query in the language the user sees in their Splitwise app, or browse splitwise_get_categories.

When to Use:

• Before splitwise_create_expense / splitwise_update_expense, when the user named a category ("groceries", "taxi").

When NOT to Use:

• To browse the whole tree — use splitwise_get_categories.

• For people or groups — use splitwise_resolve_friend / splitwise_resolve_group.

Returns: The resolution line, a markdown table of the top limit subcategories (rank, Name (id N), parent, score, matched on), then up to 3 parents with their subcategories; or, with response_format json, {query, resolution, ambiguous_count, reason, resolved, subcategories: [...], parents: [...]} where resolution is exact | unique_strong | ambiguous | none, ambiguous_count (always present, 0 unless ambiguous) says how many candidates are in contention, and parents carry usable_for_expenses: false.

Examples: params = {"query": "groceries"} params = {"query": "transportation other", "response_format": "json"}

Error Handling: A 401 means the API key is missing or was regenerated. A failed fetch is never cached. Several subcategories share the name "Other" — "other" alone is reported as ambiguous; qualify it with the parent.

List your recent Splitwise activity (notifications), newest first.

Calls GET /get_notifications and renders one row per notification: when it happened, what kind it is (expense added/updated/deleted, comment added, group and friend changes, …), its text with the HTML flattened (a struck-through old value shows as ~~old~~), what it is about (source type, id and URL) and who triggered it (user N). Codes Splitwise has not documented show as unknown (N).

When to Use:

• "What changed in my Splitwise lately?" / "Did anyone add an expense this week?"

• To find the id of a recently added or edited expense or group (the source column).

When NOT to Use:

• To list expenses with filters (group, friend, dates) — use splitwise_get_expenses.

• To read the comments on one expense — use splitwise_get_comments.

• To see who owes whom — use splitwise_get_balances.

Returns: Markdown: | When | Type | Content | Source | By | Id |, at most 50 rows (the rest counted; each text capped at 2,000 characters, the cut counted). JSON: {"count", "limit", "updated_after", "type_names", "notifications": [raw objects]} — content stays raw HTML there, and type_names maps the codes present to their names.

Pagination: There is no offset. limit returns the newest N (0 = the server's maximum, which can be large); updated_after returns only what changed since a point in time (e.g. your last check). Combine them to keep the response small.

Examples:

• params = {} (the 20 most recent)

• params = {"updated_after": "2026-10-01", "limit": 50}

• params = {"limit": 5, "response_format": "json"}

Error Handling: A malformed updated_after or a limit outside 0–100 is rejected before any call. 401 means the API key is missing or was regenerated. Errors come back as an Error ... string, never raised.

Get the Splitwise user the API key belongs to: name, id, email, currency, locale, notifications.

Calls GET /get_current_user and renders your name and id (as First Last (id N), so the id can be chained into other tools), email, registration status, default currency, locale, the unread notifications count, when notifications were last read, and your email-notification settings (expense_added=on, …).

When to Use:

• To learn your own user id before building expense shares or updating your profile.

• To check your default currency or locale before creating expenses.

• To see how many unread notifications you have (read them with splitwise_get_notifications).

When NOT to Use:

• To check the API key / kill-switch state (use splitwise_health_check).

• To look up someone else (use splitwise_get_user, or splitwise_resolve_friend for a name → id).

• To read balances (use splitwise_get_balances / splitwise_get_friends).

• To change your name, locale or default currency (use splitwise_update_user).

Returns: Markdown (default): a bullet list with the fields above. JSON: the raw Splitwise current_user object (incl. picture, notifications_read, notifications).

Examples:

• params = {}

• params = {"response_format": "json"}

Error Handling: 401 means SPLITWISE_API_KEY is missing, mistyped or was regenerated at https://secure.splitwise.com/apps. Every failure comes back as an Error ... string.

Get another Splitwise user's public profile by id: name, email, registration status.

Calls GET /get_user/{id}. Splitwise only answers for users you are connected to — a friend, or someone who shares a group with you — and for yourself.

When to Use:

• To turn a user id seen in an expense, debt or notification into a name and email.

• To check whether someone is a confirmed user or a dummy/invited placeholder.

When NOT to Use:

• For yourself with notification settings, currency and locale (use splitwise_get_current_user).

• To find a user id from a name (use splitwise_resolve_friend).

• For balances with that person (use splitwise_get_friend / splitwise_get_balances).

Returns: Markdown (default): First Last (id N) <email> and the registration status (confirmed | dummy | invited). JSON: the raw Splitwise user object (incl. picture).

Examples:

• params = {"user_id": 491923}

• params = {"user_id": 491923, "response_format": "json"}

Error Handling: 403 when the user is neither your friend nor in a group with you; 404 when the id does not exist; 401 when the API key is missing or revoked. Every failure comes back as an Error ... string.

Update your Splitwise profile: first name, last name, locale and/or default currency.

Calls POST /update_user/{id} with only the fields you pass (at least one). This is a write: it is refused with Error: … writes are disabled unless SPLITWISE_ALLOW_WRITES=1. Email and password are NOT updatable on purpose — the input has no such fields and the server's client refuses to send them under any configuration, so an LLM can never change the account's login. There is no undo tool: to revert, read the current values first with splitwise_get_current_user and call this tool again with them.

When to Use:

• To fix a typo in your name, or switch the default currency / interface locale.

When NOT to Use:

• To change email or password (impossible here by design — do it at https://secure.splitwise.com).

• To read your profile (use splitwise_get_current_user).

• To rename a friend or group member (Splitwise does not allow editing other users).

Returns: A confirmation naming the user Splitwise returned and, for each field you sent, the value as it appears in the response. It is headed "Profile updated" only when every sent field comes back with exactly the value sent. Otherwise it is headed "Update accepted by Splitwise — N of M field(s) not confirmed" with those fields flagged, and tells you to read the profile back with splitwise_get_current_user. This is common for locale/default_currency, which the flat user object in the response may omit.

Examples:

• params = {"user_id": 491923, "default_currency": "PEN"}

• params = {"user_id": 491923, "first_name": "Ada", "last_name": "Lovelace", "locale": "es"}

Error Handling: Validation rejects a call with no field to change, an unknown field (including email/password) or a currency that is not a 3-letter code, before any request. locale is checked for format only and passed through; Splitwise decides whether it is supported (a value it ignores shows as 'differs' in the confirmation). 403 when user_id is not your own id; 400 with Splitwise's field messages for a value it rejects. A timeout or 5xx leaves the outcome UNKNOWN — read the profile back with splitwise_get_current_user before retrying.