MoneyMatter

Create a new subscription, recurring bill, or installment plan. Use type="subscription" for SaaS/streaming services, type="bill" for utilities, and type="installment" for a finite financed purchase paid off over a fixed number of payments. An installment requires maxOccurrences (number of payments) and dueDate (first payment date). expectedAmount is a decimal in the subscription currency. Requires finance:write scope.

Create a new tag that can be assigned to transactions. Use when the user wants to label or categorize transactions with a custom tag. Returns the created tag with its ID.

Create a tracker with an optional spending limit and date range. It does not create or change the period-based Budget plan. Set rulesEnabled with categoryIds and/or tagIds to auto-add matching transactions; link others with add_transactions_to_tracker. Set aiEnabled with aiDescription and startDate to turn on smart tracking; review its suggestions with list_tracker_suggestions. Returns the created tracker with its ID, status, rule categories and tags.

Add a line to a tracker: a named category set with its own optional limit. A transaction lands in at most one line — the first line by position whose category set (expanded to children) contains its category; spending matching no line counts as "other". Requires manage access to the tracker. Returns the created line with its ID, limit and categories.

Create a new transaction (income, expense, or transfer). Requires accountId, amount (decimal), transactionType, paymentType, and transferNature. For transfers, also provide destinationAccountId and destinationAmount. Use splits to categorize portions of the amount. Use originalAmount + originalCurrencyCode to record what the purchase cost in its invoice currency when that differs from the account currency.

Create a transaction automation rule that categorizes, tags, sets a payee, or edits the note of matching transactions. The rule is appended last in evaluation order and only fires for newly synced or imported bank transactions that are not transfers and not planned; existing transactions are never changed retroactively. Preview the conditions with preview_transaction_automation first. Requires finance:write scope.

Create a new transaction group that bundles related transactions together (e.g. a split bill). Requires at least 2 transactions. Transfer pairs are automatically included. Requires finance:write scope.

Create a venture deal (private/illiquid investment record). All monetary amounts are decimal strings in the deal's currency (e.g. "16000"). Fee percentages are decimal fractions in [0,1] — e.g. 0.085 for 8.5%, NOT 8.5. If platformId is provided, omitted fee fields are auto-filled from the platform's defaults. Optionally creates the initial_investment event in the same operation when `initialInvestment` is supplied. Only the SPV vehicle type is supported in v1.

Record an event on a venture deal. The deal must already have an initial_investment before any other event type can be created (initial_investment must come first). Event date cannot precede the initial_investment date. Rules per type (the schema is flat but the service enforces these — invalid combinations return a clear ValidationError): • initial_investment: grossAmount is auto-derived from the deal's principal + entryFee — do NOT pass it. cashFlowMode must be 'linked' or 'out_of_wallet'. • capital_call, fee_payment, distribution: require grossAmount. cashFlowMode must be 'linked' or '…

Create a venture investment platform (e.g. AngelList, a syndicate, a fund manager) so its default fees can be auto-applied when creating new deals. Fee fields are decimal fractions in [0,1] — e.g. pass 0.085 for 8.5%, NOT 8.5. Returns the created platform's id for use with create_venture_deal.

Permanently delete a category by ID. This is destructive — if the category has linked transactions you must supply replaceWithCategoryId to reassign them first, otherwise the call will fail. Cannot delete a parent category that still has subcategories. Only call when the user explicitly confirms deletion.

Permanently delete a savings goal and free its account shares. Accounts and balances are not touched. Prefer update_goal with status archived to keep it. Returns { success: true }.

Permanently delete an investment transaction. The holding and portfolio cash balance are automatically recalculated after deletion. This action is irreversible — confirm with the user before calling. Obtain transactionId from get_investment_transactions.

Delete a Payee. Linked transactions retain their categoryId but their payeeId is set to null. Use cautiously — this is irreversible. Requires finance:delete scope.

Permanently delete a portfolio and, if force is true, all its holdings, transactions, and cash balances. Without force, deletion is blocked when the portfolio has any data. This action is irreversible — confirm with the user before calling. Obtain portfolioId from get_portfolios.

Delete a single split from a transaction by its split ID (UUID string). DESTRUCTIVE: the split amount returns to the primary category. Fails if the split has refunds targeting it.

Permanently delete a subscription or recurring bill. Linked transaction associations are also removed. This action cannot be undone. Requires finance:delete scope.

Permanently delete a tag by ID. This is destructive — the tag will be removed and unlinked from all transactions. Only call when the user explicitly confirms deletion.

Permanently delete a tracker and all its transaction links. This action cannot be undone. Returns { success: true } on completion.

Permanently delete a line from a tracker. Transactions are kept; their spending moves to the next matching line or to "other". Requires manage access to the tracker. Returns { success: true } on completion.

Permanently delete a transaction by ID. DESTRUCTIVE: this cannot be undone. For transfer transactions, both sides of the transfer are deleted.

Permanently delete a transaction automation rule. Transactions the rule already changed keep their values. This cannot be undone, so only call it when the user explicitly confirms deletion; to stop a rule temporarily set isEnabled to false via update_transaction_automation instead. Returns { success: true } on completion. Requires finance:delete scope.

Permanently delete a transaction group. The transactions themselves are NOT deleted — only the grouping is removed. This action cannot be undone. Requires finance:delete scope.

Delete a venture deal. Cascade-deletes its events and event-link rows. Bank transactions previously linked to the deal's events remain intact in the main transactions list with their original state restored. With force=true the deal row is hard-deleted; otherwise it is soft-deleted. Confirm with the user before calling.

Delete a venture event. Linked bank transactions are unlinked first (their original state is restored). The initial_investment cannot be deleted while other events still exist on the deal — delete the other events first. Pass deleteLinkedTransactions=true to also remove the bank tx rows themselves (not just the link); only do this when the user explicitly asks. Confirm with the user before calling.

Delete a venture platform. Existing deals that reference it have their platformId cleared (deals are preserved). With force=true, hard-deletes the platform; otherwise it is soft-deleted. Confirm with the user before calling — operates against the user's records.

Scan the past 12 months of transactions to detect recurring payment patterns and generate subscription candidates. This operation can be slow on large transaction histories. Results are cached for 1 hour — subsequent calls within the cooldown return cached candidates. Check isFromCache in the response to know if the data is fresh. Requires finance:write scope (writes candidate records).

Dismiss a pending subscription candidate so it no longer appears in the candidate list. The underlying transactions are unaffected. Only pending candidates can be dismissed. Requires finance:write scope.

List all user accounts with current balances. Returns account name, type, currency, current balance (in original and base currency), and credit limit.

Get account balance over time. If accountId is provided, returns balance history for that specific account. Otherwise, returns combined balance across all accounts.

Get income, expenses, and net cash flow for a period with configurable granularity (monthly/biweekly/weekly). Returns period-by-period breakdown plus totals with savings rate.

List all transaction categories. Returns category ID, name, color, icon, type (income/expense), and parent ID for hierarchical categories.

Get total expense amount for a date range. Returns a single total number. Use this for quick "how much did I spend" queries instead of summing transactions manually.

List savings goals (active, paused, archived) in the user's order. Each goal has a target amount in its own currency (currencyCode), an optional targetDate and plannedMonthly, and the accounts backing it. Of an account's balance (minus its credit limit, never below 0), each fixedAmount (account currency) is taken first in fixedPosition order, then sharePercent is the part of what is left that counts toward the goal; exactly one of the two is set. progress holds currentValue, remaining, pace (plannedMonthly when set, else the median monthly change over recent full months), historicalPace, neede…

Investment transaction history: buy, sell, dividend, transfer, tax, fee, cancel, other. Each transaction includes amount, quantity, price, fees, date, category, and the embedded security. Distinct from search_transactions, which covers regular (non-investment) spending. Default: 20 most recent across all portfolios.

Fetch a single Payee with aliases and computed stats. Useful when the user references a merchant by id and wants its full record.

List Payees (merchants/counterparties) for the user, optionally filtered by a substring query. Returns Payee id, name, defaultCategoryId, and aggregated stats (transactionCount, netFlowRef, top category, last seen).

Cash balances held in a portfolio, broken down per currency. Each entry includes totalCash and availableCash in the original currency plus their ref* equivalents converted to the user's base currency. Useful for answering 'how much cash do I have to invest'.

Positions held in a portfolio with dynamically calculated market value, cost basis, and realized/unrealized gain (value and percent). Each holding includes the embedded security (symbol, name, asset class, currency). Filter by securityId to look at a single position.

Portfolio-level aggregates for a single portfolio: total current market value, total cost basis, realized and unrealized gains (value and percent), cash balances, and total portfolio value (holdings + cash). All monetary values are decimals in the user's base currency.

List the user's investment portfolios. Returns id, name, portfolio type (investment/retirement/savings/other), description, enabled state, and creation date. Use the returned id with get_portfolio_summary, get_portfolio_holdings, get_portfolio_balances, and get_investment_transactions.

Get spending breakdown by category for a date range. Returns each category with its total amount. Great for understanding where money goes. Defaults to current month expenses.

Retrieve a single subscription by its ID including all linked transactions (with match source and date) and the computed next expected payment date.

List all subscriptions and recurring bills for the user. Returns name, frequency, expected amount, linked account/category, active state, and linked transaction count. Use isActive to filter active-only.

Aggregate summary across all active subscriptions with an expected amount, split by direction. Returns estimated monthly cost and projected yearly cost from expense subscriptions, expected monthly income from income subscriptions, active counts as { expense, income }, the user's average monthly income over the last 6 complete months (observed from transaction history, separate from subscription-based expected income), and percent of that income spent on subscriptions (all monetary values in the user base currency). Useful for "how much am I spending on subscriptions per month?", "how much recu…

List all user tags. Returns tag ID, name, color, and icon.

Get spending statistics for a tracker: spending broken down by category and a time-series of expense vs income over the tracker period. Granularity is daily for ranges ≤62 days, weekly ≤184 days, monthly otherwise. Also returns spending by original currency, the top 5 payees, the biggest spending day, a summary (income, expense, balance, limit utilization %), per-line spent (`lines: [{ lineId, spent }]`, match lineId against get_trackers lines) and `otherSpent` for spending that matches no line. Amounts are decimals.

List trackers: spending watchers over a date range with an optional limit, holding hand-picked transactions plus those their category and tag rules link. They are not the period-based Budget plan (lines, assigned amounts, Ready to Assign), which no tool exposes. Filter by status (active, archived, closed). Returns tracker name, limit amount, status, date range, rule categories and tags, rulesEnabled (rules auto-link matching transactions of the owner), rulesCleanup (rule links that stop matching are removed), and lines: named category sets with their own optional limit (name, limitAmount as de…

List the transaction automation rules (rules engine) of the user, ordered by evaluation order. Call it before updating, deleting, or reordering a rule to get its id. Returned fields: `position` is the 0-based evaluation order (rules run top to bottom on each newly synced or imported bank transaction and the first rule that applies an action wins), `isEnabled` whether the rule runs at all, `matchCount` and `lastMatchedAt` how often and when it last fired, and `pausedReason` which is non-null when a referenced category, tag, payee, or account was deleted (fix the rule and re-enable it). Automati…

List all transaction groups for the user. Groups bundle related transactions (e.g. split expenses). When includeTransactions is true, each group contains the full transaction list; otherwise returns aggregate counts and date ranges.

List upcoming subscription payments sorted by next expected payment date (soonest first). Returns subscription name, expected amount, currency, next payment date, and category. Only active subscriptions with an expectedAmount are included.

Get the user's base currency, configured currencies with exchange rates, and basic profile info. Call this first to understand the user's currency context.

Retrieve a single venture deal by id, including its platform and currency. Pass includeEvents=true to also embed the deal's event history (sorted asc). Obtain the dealId from list_venture_deals.

Compute aggregated metrics for a venture deal: cost basis, current value (latest NAV), total distributions, absolute and percent P&L, TVPI (total value to paid-in), DPI (distributions to paid-in), and IRR. IRR returns null for degenerate cash flows (e.g. no inflows yet). Pass asOfDate (YYYY-MM-DD) to compute metrics as of a specific date.

Retrieve a single venture event by id, including its link rows (bank transactions linked to this event). Obtain the eventId from list_venture_events.

Retrieve a single venture platform by id. Returns full record including default fee fractions (decimals in [0,1]). Obtain the platformId from list_venture_platforms.

Mark an existing transaction as a refund of another transaction. Provide originalTxId (the transaction being refunded) and refundTxId (the refund transaction). The two transactions must have opposite types (income vs expense). Optionally target a specific split of the original.

Link an existing regular transaction to an investment portfolio as a cash transfer. An expense transaction moves cash from its account into the portfolio; an income transaction moves cash from the portfolio to its account. The transaction must not already be a transfer or linked to a portfolio. Returns the created portfolio transfer.

Link one or more transactions to a subscription to mark them as payment instances. Use matchSource="manual" for user-initiated linking. If the subscription has a categoryId and matchSource="rule", the category is applied to the transactions automatically. Requires finance:write scope.

Link two existing transactions as a transfer pair. The two transactions must be in different accounts and have opposite types (one income, one expense). Provide baseTxId (the source/expense side) and oppositeTxId (the destination/income side).

Cash movement history of a portfolio: account↔portfolio transfers, direct deposits/withdrawals, linked bank transactions, and currency exchanges. Each entry names the source/destination portfolio or account. Sorted by date, newest first. Returns { transfers, totalCount }.

List auto-detected subscription candidates sorted by confidence score. Call detect_subscription_candidates first to generate fresh candidates. Use status filter to see only pending, accepted, or dismissed candidates.

Smart-tracking state of a tracker the user owns. pending: transactions the AI suggests linking, each with a suggestion id, score (0-1), the AI reason, and a transaction summary; accept or reject them by suggestion id with accept_tracker_suggestions / reject_tracker_suggestions. aiMatched: transactions the AI linked or the user accepted, still linked, with their reason. scan: status (idle, queued, running), startedAt, lastScannedAt, and pausedReason (archived, no_start_date, ended, plan, allowance, unavailable) when scanning cannot run; plan means the plan does not include smart tracking and th…

List the user's venture deals (private/illiquid investments through SPVs, syndicates, or direct vehicles). Returns each deal's id, name, status (outstanding | partial_exit | fully_exited | written_off), platform, currency, principal, entry fee, fee fractions, dates, and target company. Use the returned id with get_venture_deal, get_venture_deal_metrics, list_venture_events, and update_venture_deal.

List events for a venture deal in chronological order (oldest first). Each event has a type (initial_investment | capital_call | distribution | nav_update | exit | writedown | fee_payment), date, amounts, cashFlowMode, and embedded link rows (when the event is tied to bank transactions). Use the returned event ids with get_venture_event, update_venture_event, and delete_venture_event.

List the user's venture investment platforms (SPV syndicators, fund managers). Returns each platform's id, name, website, description, and default fee fractions (entry fee, management fee, carry, hurdle). Fee values are decimals in [0,1] — e.g. 0.085 means 8.5%. Use the returned id with get_venture_platform, create_venture_deal, and update_venture_platform.

Merge a source Payee into a target Payee. Transactions and aliases move to the target; the target wins silently on defaultCategoryId conflict; the source is deleted. Use to dedupe near-duplicates like "Amazon" and "AMZN MKT". Requires finance:delete scope.

Dry-run a set of automation conditions against up to the last 1000 eligible existing transactions and return { matchedCount, scannedCount, matches } where matches is capped at 5 sample transactions. Nothing is modified. Use it to sanity-check conditions before create_transaction_automation or update_transaction_automation. Note that a live automation fires on its own only for newly synced or imported bank transactions that are not transfers and not planned; existing transactions change only when the user runs "Apply to past transactions" for a saved rule in the app.

Reject smart-tracking suggestions of a tracker the user owns: pending ones are dismissed, and AI-linked or accepted ones are also unlinked from the tracker. The AI will not suggest these transactions again. Suggestion ids come from list_tracker_suggestions (pending or aiMatched). Returns resolvedCount.

Remove a tag from one or more transactions. Use when the user wants to untag transactions. Returns the count of removed tag links.

Remove transactions from a group. If removal would leave fewer than 2 transactions, pass force=true to dissolve the group entirely (transactions are kept). Requires finance:write scope.

Unlink one or more transactions from a tracker. Does not delete the transactions themselves. Returns nothing on success.

Reorder the transaction automation rules of the user. Rules are evaluated top to bottom on each newly synced or imported bank transaction and the first rule that applies an action wins, so ordering decides which rule takes precedence when several match. Returns the rules in their new order. Requires finance:write scope.

Search for securities (stocks, ETFs, crypto, etc.) by ticker symbol or company name. Call this before create_investment_transaction to resolve a human-readable ticker (e.g. "AAPL") into a securityId. If portfolioId is provided, each result includes isInPortfolio to indicate whether the security is already tracked in that portfolio.

Search and filter transactions. Returns transaction amount (original + base currency), category, account, note, date, type, and tags. Use date filters to limit results. Default: last 30 days, 50 items.

Split a transaction across multiple categories. Provide the transactionId and an array of splits whose amounts sum to the transaction total. Replaces any existing splits on the transaction.

Activate or deactivate a subscription. Inactive subscriptions are excluded from upcoming payment calculations and summary totals. Requires finance:write scope.

Move cash from a regular account into an investment portfolio. Creates an expense transaction on the account and increases the portfolio cash balance. Use link_transaction_to_portfolio instead when the bank transaction already exists.

Withdraw cash from an investment portfolio into a regular account. Creates an income transaction on the account and decreases the portfolio cash balance. Use link_transaction_to_portfolio instead when the bank transaction already exists.

Remove the refund link between two transactions. DESTRUCTIVE: both transactions will no longer be marked as refund-linked. Requires both originalTxId and refundTxId that were previously linked.

Remove the portfolio link from a transaction: deletes the portfolio transfer, reverses the portfolio cash balance change, and restores the transaction to a regular income/expense. Succeeds even if the transaction has no portfolio link.

Unlink transactions from a subscription without deleting them. The link record is marked as unlinked and excluded from subscription history. Requires finance:write scope.

Unlink transfer transactions by their shared transferId (UUID string). Both transactions in the pair will become independent income/expense entries. Use search_transactions to find the transferId of a linked pair.

Update an existing category by ID. Use when the user wants to rename, recolor, or change the icon of a category. Returns the updated category records.

Update a savings goal. Only passed fields change; accounts replaces the whole set. Use status to pause, archive or restore a goal. Fails when an account would pass 100% shared across non-archived goals, the new currency has no exchange rate, or fixed amounts alone fall short of the target. Needs the Goals feature on the plan or an active trial. Returns the goal in the get_goals shape.

Update an existing investment transaction — correct the date, quantity, price, fees, category, or label. Obtain the transactionId from get_investment_transactions. Only provided fields are changed; the holding recalculation runs automatically after every update.

Rename a Payee or set/clear its defaultCategoryId. Renaming preserves the previous canonical name as an alias so historical matches still resolve.

Update an existing portfolio's name, type, description, or enabled state. Use when the user wants to rename, recategorize, or disable one of their portfolios. Obtain the portfolioId from get_portfolios first. Only the fields provided are changed.

Update fields on an existing subscription or bill. Only provided fields are changed. To toggle active state use toggle_subscription_active instead. Requires finance:write scope.

Update an existing tag by ID. Use when the user wants to rename, recolor, or change the icon/description of a tag. Returns the updated tag.

Update the name, date range, spending limit, or rules (categories, tags, auto-add) of an existing tracker. Only passed fields change; limitAmount null removes the limit. With rules on, every update re-checks all transactions against them. Lines are managed with create_tracker_line, update_tracker_line and delete_tracker_line. Changing smart-tracking fields or dates rescans the tracker and fails while a scan is already queued or running. Returns the updated tracker record.

Update a tracker line: name, categories, limit, or position. Only passed fields change. A transaction lands in at most one line — the first line by position whose category set (expanded to children) contains its category; spending matching no line counts as "other". Requires manage access to the tracker. Returns the updated line.

Update an existing transaction by ID. All fields except id are optional — only provide what you want to change. Pass tagIds: null to clear all tags, or tagIds: [] to do the same. Pass splits: null to clear all splits. Pass payeeId: null to clear the payee. Use originalAmount + originalCurrencyCode to record what the purchase cost in its invoice currency when that differs from the account currency.

Update a transaction automation rule. Only provided fields change; conditions and actions are replaced wholesale, not merged. Setting isEnabled to true or changing conditions/actions re-validates every referenced category, tag, payee, and account and clears pausedReason, so this is how a rule paused by a deleted reference is repaired. Position is not changed here, use reorder_transaction_automations. Requires finance:write scope.

Update the name or note of an existing transaction group. To change group membership use add_transactions_to_group or remove_transactions_from_group. Requires finance:write scope.

Update a venture deal. Only provided fields change. Once any event exists on the deal, the terms (principal, entryFee, entryFeePct, carryPct, hurdlePct, investmentDate, currencyCode) are locked — changing them would silently stale the carry math. Delete the events first if the user needs to fix terms. Status can be overridden manually (auto-progression normally derives it from events). Fee percentages are decimal fractions in [0,1].

Update a venture event. Only provided fields change. eventDate must stay on/after the initial_investment date (and moving an initial_investment past existing later events is rejected). Override semantics for gpCarryAmount / lpNetAmount: • Omit the field → no change. • Pass a string value → set the manual override; flips the corresponding *Overridden flag to true. • Pass null → currently treated the same as omitting (no semantic clear). To clear an existing override, use `resetOverrides: true` instead. The event type cannot be changed — delete and recreate instead.

Update an existing venture platform's name, website, description, or default fees. Only provided fields change. Updating default fees does NOT retroactively change fees on existing deals — those are snapshotted at deal creation. Fee fractions are decimals in [0,1].