Fold

Returns a one-shot summary of the calling user's stocks and ETF portfolio: total current value, ETF value, equity value, total shares, total holdings, and number of demat accounts. Read-only.

Returns the user's total bank balance — the sum of balances across their primary bank accounts. Use when the user asks 'what's my total balance', 'how much money do I have in bank', 'how much across all my accounts', or similar aggregate-bank-balance questions. Output: total (the headline number), currency, as_of (most-recent refresh timestamp among included accounts; null when none included), included_accounts (id, bank_name, balance for each account that contributed), and excluded_accounts (id, bank_name, balance, reason for each excluded account — letting the AI explain 'why isn't X in the total' or 'what would it be if I included Y'). Reason is one of: "user_excluded" (user opted this account out via the app), "passively_tracked" (account is not actively managed and lives in the other-accounts surface), "pending_connection" (first data sync hasn't completed; balance is null). For per-account questions ('what's my HDFC balance'), use list_bank_accounts. For net worth or asset/liability questions, use get_net_worth. For credit card outstanding, use list_credit_cards. Read-only.

Fetch the full detail of one of the calling user's transactions by its id. The row has the same shape list_transactions returns. In particular `amount` is the ORIGINAL figure — not reduced by refunds, and still the full pre-split total on a split parent — while `effective_amount` (COALESCE of remaining_refund_amount, remaining_amount, amount) is the figure that counts towards spending; prefer it whenever the transaction has been refunded or split. `split_type`, `remaining_amount` and `parent_transaction_id` describe this transaction's place in a split, if any. Returns found=false when no such transaction belongs to the user.

Returns the user's connected bank accounts with per-account current balance. One row per account. Fields per row: id, bank_name, nickname (nullable, user-set label), masked_number, holder_name (nullable), account_type (nullable; e.g. SAVINGS, CURRENT), balance (current balance; null while the account is still connecting), currency, is_secondary (true for accounts the user connected via a different phone number — still their own money), is_pending_connection (true while the first data sync hasn't completed; balance is null in that state), tracking ("ACTIVELY" for a primary account; "PASSIVELY" or "PASSIVELY_WITH_TRANSACTIONS" for an account the user keeps but doesn't actively manage), and last_refreshed_at. USE THIS for per-account questions: 'what bank accounts do I have', 'what's my X balance', 'any accounts still connecting', 'when was my Y last refreshed'. DO NOT USE THIS for cross-account aggregations. For 'total balance', 'net worth', 'cashflow', or any sum across accounts, use the dedicated aggregation tools — those apply per-account include/exclude rules that this tool ignores. For credit cards, use list_credit_cards. Read-only.

Lists Fold's category catalog — the tags a transaction can be filed under — with each category's subcategories (called icons in the app) nested underneath. Call it to find the category id to pass to a transaction update. The catalog is GLOBAL: these are Fold's categories, not ones the user created, and there is nothing to create or rename here. No inputs. Output: count and categories[] ({id, name, type[], subcategories[] ({id, name})}), ordered by category name. type lists the transaction directions the category may be applied to — 'INCOMING', 'OUTGOING', or both — and is enforced on write: filing a credit under an OUTGOING-only category is rejected. Category NAMES ARE NOT UNIQUE — 'Return' exists twice, once per direction — so always pass the id, never the name. subcategories is always present and may be empty. Categories the caller's plan does not include are omitted, so every id returned here is one the update path will accept. Read-only.

Lists the user's credit cards with current billing-cycle details: outstanding amount, minimum payment, payment due date, available credit, and whether the previous cycle is paid. Cards may be linked as an addon family (see `relationship`: role PARENT with child_account_ids, or role CHILD with parent_account_id). An addon family shares one statement: the PARENT card's `outstanding` carries the whole family's dues and CHILD cards report 0 — never add a child's cycle totals on top of its parent's. A CHILD card's reconciled cycle `total_amount_due` is the family's combined bill (not child-specific); only its unreconciled `amount_spent_this_cycle` is the child's own spend. Bills are paid on the parent card only. `holder_name` is the cardholder name as the issuer printed it on the parsed statement; null when no name is on record. Use this for any question about CC bills or due dates. Read-only.

Lists the user's fixed deposits with a roll-up summary header (count, total principal, total maturity, total interest on maturity, principal-weighted average interest rate). One row per FD, sorted by maturity date (soonest first). Inputs: status ('active' default, 'archived', or 'all' — case-insensitive; DELETED rows are never returned), limit (1-200, default 100). Per-FD fields: account_id, institution_name, nickname (nullable, user-set label), masked_account_number (nullable), display_name (server-formatted human label like 'HDFC Bank Salary FD ••1234' the AI can echo verbatim), principal_amount, maturity_amount, interest_rate (annual %), interest_on_maturity, opening_date / maturity_date (YYYY-MM-DD), tenure (years/months/days), days_to_maturity (signed; negative when already matured), status ('active' or 'archived'), is_matured, auto_renews, account_type (lowercase, e.g. 'fixed' / 'recurring' / 'sweep'), interest_payout (nullable, lowercase), interest_computation (lowercase). The summary header aggregates the SAME row set returned in the body, so the totals always match the inventory. USE THIS for any FD question: 'what FDs do I have', 'when do my FDs mature', 'what's my total FD principal', 'do I have any archived FDs', 'how much interest will I earn from my FDs'. For net worth that rolls FDs in alongside other assets and honours per-account widget toggles, use get_net_worth. Personal/holder details (name, DOB, PAN, email, mobile, KYC status, IFSC, branch) are deliberately omitted. Read-only.

Lists the calling user's transaction groups — user-created collections of transactions (e.g. a trip, a home renovation, shared flat expenses) used to track project or shared spending. Input (optional): status ('ACTIVE' default, or 'ARCHIVED'; case-insensitive). Each row carries id, name, status, is_pinned, incoming_count / incoming_amount (credits), outgoing_count / outgoing_amount (debits), created_at, and transactions_updated_at (the group's latest-activity timestamp — the same value the app sorts the groups list by; rows are returned in that order, most recent first). The rollups are user-scoped: only transactions on accounts the user can see count, hidden transactions are excluded, and cash-flow-excluded transactions follow the group's own include-in-totals preference — the numbers match what the user sees in the Fold app. Response: groups[] and count (== len(groups)). To see what is inside a group, pass its id to list_transactions as group_ids. Read-only.

Lists the calling user's mutual fund holdings, one row per scheme (ISIN), with units, invested amount, current value, gain/loss, asset category, plan name, and risk profile. Supports an optional case-insensitive asset_category filter and a limit (1-100, default 100).

Lists the user's mutual fund transactions (buys/sells), with optional filtering by type and free-text search. Cursor-based pagination: the first call omits cursor; subsequent calls pass the next_cursor value from the previous response. next_cursor is nil when there are no more pages.

Lists the calling user's recurring expenses (subscriptions, bills, EMIs), sorted by upcoming due date. Filter by status (ACTIVE/ARCHIVED/STOPPED; default ACTIVE). Cursor-based pagination. Read-only.

Lists the calling user's refund groups — user-created links between one or more spends and the refunds / returns / reversals that offset them (a returned order, a cancelled booking, a reimbursed expense). One row per group, most recently updated first. Distinct from list_groups, which returns the user's transaction groups. Inputs: statuses (optional; any of 'ACTIVE', 'SETTLED', 'SURPLUS', case-insensitive; omit for all three). Per-group fields: id, name, status, net_amount, left_to_settle, transaction_count. net_amount is the stored settlement figure — the sum of the group's credits MINUS the sum of its debits — so it is NEGATIVE while part of a spend is still un-refunded, 0 once refunds exactly cover the spends, and positive when refunds exceeded them. status is derived from that sign: 'ACTIVE' (net_amount < 0, a refund is still outstanding), 'SETTLED' (0), 'SURPLUS' (> 0, refunded more than was spent). left_to_settle is max(0, -net_amount) — the un-refunded remainder as a POSITIVE figure, and 0 for SETTLED and SURPLUS groups. Quote left_to_settle when the user asks how much is still to come back; quote net_amount only when a signed figure is wanted. transaction_count counts only transactions the user can still see — hidden transactions, and transactions on deleted or passively-tracked accounts, are not counted — so it can legitimately read 0 for a group that still exists. A transaction belongs to at most one refund group, and a group holds at most 200 transactions. Groups saved WITHOUT a name are not returned: treat this as the user's named refund groups, not an exhaustive account of every refund link they have made. Linking a refund rewrites how the member transactions count towards spending: each spend carries its un-refunded remainder, and the refund credits consumed offsetting those spends are excluded from cash flow so they do not read as income. get_spending_summary and compare_spending_periods already apply that netting, so a fully refunded spend contributes 0 to spending totals there and needs no adjustment by you. To see what is inside a group, pass its id to list_transactions as refund_group_ids — that returns both the spends and the refunds, each row carrying its own remaining_refund_amount. USE THIS when the user asks 'what am I still waiting on a refund for', 'how much is yet to be refunded', 'which refunds have come through', or any refund / return / reimbursement question. Read-only.

Lists the calling user's stocks and ETF holdings, merged by ISIN, sorted by current value descending. Supports a limit (1-100, default 100). Read-only.

Lists the user's stocks and ETF transactions (buys, sells, bonuses, splits, dividends, rights, others), most recent first. Optional filters: type, holding_id. Cursor-based pagination — pass next_cursor from a prior call to fetch the following page. Read-only.

List the calling user's own financial transactions. Filters (all optional): limit (1-100, default 25), cursor (opaque pagination token from next_cursor), type ('debit' or 'credit'), start_date / end_date (YYYY-MM-DD, inclusive / exclusive), exclude_non_cashflow (hide transfers / loan repayments / internal moves), sort_by ('date' default, or 'amount'), sort_order ('desc' default, or 'asc'), account_ids (one or more bank/credit-card account UUIDs), sources ('bank', 'credit_card', and/or 'manual'), category_ids / subcategory_ids (UUIDs), refund_group_ids (UUIDs from list_refund_groups — returns exactly the transactions linked to those refund groups, both the spends and the refunds that offset them), and group_ids (UUIDs from list_groups — returns the transactions the user has filed into those transaction groups). For both group filters an unknown id is not an error, it simply matches nothing. Sort dimensions MUST stay constant across pages of the same cursor walk — the cursor pins a value of the sort column, so changing sort_by/sort_order between pages would silently skip / re-emit rows. Each row carries two timestamps: `date` is when the transaction actually happened (bank-reported time, used for ordering and the date-range filter); `account_in` is a USER-CONTROLLED override that moves the transaction into a different calendar month for cash-flow / spending-summary accounting — for example, a salary credited Jan 31 can be moved into February so it counts under Feb's cash flow. `account_in` is null when the user hasn't moved the transaction; when present, it overrides `date` for monthly accounting only (not for ordering or the date-range filter). The get_spending_summary tool already applies COALESCE(account_in, date) server-side. Each row also carries `account_id` (the bank/credit-card/manual account this transaction belongs to — join key for list_bank_accounts / list_credit_cards results), a nested `category` envelope (null when the transaction is uncategorised; otherwise {id, name, subcategory} where the inner subcategory ({id, name}) is null when the user has not picked an icon under the category), and `excluded_from_cash_flow` (true when the transaction is hidden from cash-flow / spending totals — transfers, loan repayments, internal moves, or user-marked exclusions; the same flag that the `exclude_non_cashflow` input filters on). Two refund fields complete each row: `refund_group_id` (the refund group this transaction is linked to, or null — a transaction is in at most one; resolve the name via list_refund_groups) and `remaining_refund_amount` (the un-refunded remainder of a spend a refund group has offset: 0 when refunds covered it entirely, the shortfall when they covered part, null when refund netting has not touched this row). `group_ids` lists the transaction groups this transaction has been filed into — an array (a transaction can be in several), empty when it is in none; resolve names via list_groups. Three split fields complete each row. A user can SPLIT a spend — carving child transactions out of it, each taking its own category, merchant and notes, while the original row keeps the leftover. `split_type` is 'PARENT' on that original row, 'CHILD' on a carved-off piece, and null when splitting never touched the transaction. `remaining_amount` is the parent's own leftover, the part still carrying the parent's category and notes (null on children and on non-split rows). `parent_transaction_id` points a child back at its parent (null otherwise) and is the only reliable way to group a split back together. This tool returns a parent and its children as SEPARATE sibling rows. `amount` is always the ORIGINAL figure in both directions: it is NOT reduced by refunds, and on a split PARENT it is still the full pre-split total even though that transaction's children are returned as their own rows alongside it. Use `effective_amount` for anything you sum — it is COALESCE(remaining_refund_amount, remaining_amount, amount), the exact figure the spending engines resolve, and the only field that reconciles with get_spending_summary. Summing `amount` instead overstates refunded spend and double-counts every split. Response: transactions[] (this page), count (this page's size, == len(transactions)), total_matched (count across ALL pages of the filter — populated only when truncation was detected; on the non-truncated path it is 0 and count IS the true total), and next_cursor (opaque pagination token; null when there are no more pages). Returns only transactions the user can already see in the Fold app. Read-only.

Lists individual recurring-expense cycle instances (single payments) within a date range, sorted by due date. Includes UPCOMING/OVERDUE/PAID statuses and projects future cycles for dates beyond the backfill window. Default range: today to today + 30 days. Read-only.

Merges a split CHILD transaction back into its parent, undoing one split_transaction call. WRITES to the user's data, so confirm with the user before calling unless they have clearly already asked for this. Input: transaction_id (required) — the UUID of the CHILD leg to merge back, a transaction whose `split_type` is "CHILD". Passing the PARENT's id, or any transaction that is not a split child, is rejected. This DELETES the child transaction and everything that was ever added to it — its notes, its receipts, its own category and merchant. That is NOT recoverable: splitting again creates a fresh child, it does not bring the old one back. What returns to the parent is only the amount. The parent itself, and the original spend, are untouched. Merging the LAST remaining child resets the parent entirely: its `split_type` and `remaining_amount` go back to null and it stops being a split at all. The parent view returned shows whichever of those two states applies, so read it rather than assuming. Refused when the PARENT has since been linked to something that assumes a fixed amount — a recurring-expense cycle, a credit-card bill, or a refund group — because handing the amount back would contradict that link. Not idempotent in the way that matters: once the child is gone, calling again with the same id fails with 'transaction not found'. Never retry blindly on an unclear result — re-read with get_transaction first. Output: parent (the parent as it now stands, same shape as list_transactions) and merged_amount (the amount handed back to it). parent is null only when the merge succeeded but reading the parent back afterwards failed — treat that as a failed READ, not a failed merge.

Splits one of the calling user's transactions by carving a piece off it — the same split the Fold app offers on a transaction. WRITES to the user's data, so confirm with the user before calling unless they have clearly already asked for this exact split. This is CARVE-OFF, NOT divide-into-N. One call creates ONE child transaction of the amount you name and the parent keeps whatever is left in its `remaining_amount`. There is no 'split into 3 equal parts' operation and the amounts you pass do not have to sum to anything: to split a 900 lunch three ways, call this TWICE for 300 each, and the 300 still sitting on the parent IS the third piece. Inputs: transaction_id (required — the PARENT's UUID, from list_transactions or get_transaction), amount (required), and optionally category_id / subcategory_id from list_categories to file the child under. OMIT category_id to let the child inherit the parent's category; pass an EMPTY STRING to leave the child uncategorised instead, the same way an empty string clears a field on update_transaction. amount must be at least 0.01 and STRICTLY LESS than what the parent has left: its `remaining_amount` once it has been split at least once, otherwise its `amount`. A parent always keeps a positive remainder, so a split that would consume the whole transaction is rejected — read the parent with get_transaction first when you are not sure what is left. A parent may carry at most 20 children. NOT IDEMPOTENT: calling twice carves TWO children, not one. If a call comes back unclear — a timeout, an error you cannot read — do NOT retry it. Call get_transaction on the parent and look at `remaining_amount` and the child rows to see whether the split already landed. There is deliberately NO merchant input and NO notes input here. The child INHERITS the parent's merchant, and notes are NEVER inherited (a note written about the whole transaction does not describe the slice). To give the child its own merchant or its own note, call update_transaction on the child_transaction_id this returns. The child inherits everything else too — the account, the date, the cash-flow flag, the receipts, and the parent's category unless category_id is given — and it joins EVERY transaction group the parent is in, so a group's total still covers the whole of what was spent. These transactions CANNOT be split and the call is rejected with the reason: manual transactions (entered by hand rather than fetched from a bank), a transaction that is itself a split CHILD (splits do not nest), credit-card bill payments and transactions linked to a credit-card bill, hidden transactions, transactions inside a refund group, and transactions linked to a recurring-expense cycle. Output: child_transaction_id (the new child's UUID — pass it to update_transaction to tag it further), child, and parent (both in the same shape list_transactions returns; the parent as it NOW stands, with split_type "PARENT" and a reduced remaining_amount). child and parent are null only in the rare case where the split succeeded but reading the rows back afterwards failed — child_transaction_id is still the id that was created, so treat a null view as a failed READ and never as a failed split. To undo a split, call merge_split on the child.

Re-tags the calling user's own transactions: notes, category, subcategory, merchant, whether they count towards cash flow, and which month they are accounted in. WRITES to the user's data — the change is what they will see in the Fold app, so confirm with the user before calling unless they have clearly already asked for this exact change. Inputs: transaction_ids (required, 1-25 UUIDs from list_transactions, all the caller's own) plus any of notes, category_id, subcategory_id, merchant_name, remove_merchant, excluded_from_cash_flow, account_in. At least one of those seven is required, and every one given is applied to EVERY listed transaction — so batch only transactions that should all end up the same. Clearing vs leaving alone: an omitted field is left untouched, an empty string CLEARS it (notes, category_id, account_in). remove_merchant unsets the merchant and cannot be combined with merchant_name. excluded_from_cash_flow takes the transactions out of (true) or back into (false) cash-flow and spending totals — the same toggle as the app. It is refused, and the whole call fails, for a bank transaction linked to a credit-card bill or a credit inside a refund group, because their exclusion is already derived. Setting a category can also change this flag on its own: filing a transaction as a self-transfer excludes it, moving it off self-transfer includes it again. account_in moves transactions into another calendar MONTH for cash-flow and spending-summary accounting without changing when they happened — a salary credited Jan 31 accounted into February, say. Pass a date as YYYY-MM-DD (read in the user's timezone) or an RFC 3339 timestamp; only the month it lands in matters. It may move a transaction ONE month either way at most — into the month before or the month after the one it happened in — and a date further out is refused, failing the whole call. A date inside a transaction's own month clears that transaction's override rather than duplicating it, and an empty string clears it outright. category_id / subcategory_id come from list_categories. A category only accepts transactions in a direction its `type` lists, so an INCOMING transaction cannot be filed under an OUTGOING-only category. There are two ways to set the merchant, and they cannot be combined. merchant_name is free text, matched EXACTLY (case-insensitively) against the user's own merchants and Fold's catalogs; when nothing matches, a new custom merchant is CREATED with that name and appears in the user's merchant picker from then on — a real side effect beyond these transactions, so prefer the plain canonical name ("Swiggy", not "Swiggy order 4th Aug") and tell the user when merchant_resolution.outcome is "created". merchant_id + merchant_type instead names a SPECIFIC merchant from find_merchant_to_tag — use that pair when the name is ambiguous, when a particular outlet is meant, or when you want Fold's catalog brand rather than whatever an exact name match happens to hit. Pass both back exactly as that tool returned them. Output: updated_count, transactions[] (the rows as they now stand, same shape as list_transactions), previous[] ({id, category_id, subcategory_id, notes, merchant_id, merchant_type, excluded_from_cash_flow, account_in} as they were BEFORE this call — pass these back to undo it), and merchant_resolution ({outcome, id, name, type}, null when merchant_name was not given). The whole call fails if any transaction id is not the caller's, so a partial update never happens silently. Some tag rules are applied server-side and may change more than was asked: filing a transaction as a self-transfer also sets its merchant to "Myself", and moving it off self-transfer clears that merchant again. Read `transactions` in the response rather than assuming the patch applied verbatim.