walletdocs

Reference

Agent tools

Every tool in the registry the assistant, the MCP server and the REST API share, with its parameters. Generated from the code at build time.

All agent surfaces expose one registry, TOOLS in src/server/agent/tools.ts:

SurfaceHow it gets the tools
Built-in assistant, anthropic providerTool definitions in every Messages API request (Agent internals)
Built-in assistant, claude-code / codex providersThe wallet MCP server is the CLI's only tool
MCP over stdiobin/wallet-mcp.mjs (MCP & API)
MCP over Streamable HTTPPOST /api/mcp
Plain HTTPGET /api/tools, POST /api/tools/<name> (HTTP API)

How a call runs

callTool(ctx, name, input) is the single entry point:

  1. Lookup. Only enabled tools are callable. With WALLET_AGENT_READONLY=1, write tools are removed from every surface, so a call to one fails with Unknown or disabled tool.
  2. Validation. The input is parsed with the tool's zod schema. Defaults below are applied and failures come back as Invalid input: … (HTTP 400 on /api/tools).
  3. Run. The tool calls services with ctx.userId. Every tool acts for exactly one user: the signed-in user, the bearer token's or local default user (WALLET_USER_ID, else the owner), or the Telegram chat's linked user.
  4. Result. Results with the user's money are labelled with their currency (labelCurrency()): objects without a currency get baseCurrency, and arrays become { baseCurrency, items }. Calculators, conversions, SQL and file reads are left as they are. The value then goes through present(): fields ending in Cents become currency units without the suffix (balanceCents: 123456 → balance: 1234.56), dates become ISO strings, and userId and binary buffers are dropped. Errors thrown by services are returned as the message text, flagged as an error.
  5. Cache. After any write tool, the user's SQL sandbox is dropped so the next query_sql sees the change.

MCP clients also see each tool's title and a readOnlyHint annotation that matches the access column below.

# List every enabled tool with its JSON Schema, then call one directly (no LLM involved)
curl localhost:3000/api/tools
curl -X POST localhost:3000/api/tools/get_budget_status \
  -H 'Content-Type: application/json' -d '{"month":"2026-09"}'

Index

67 tools: 34 read-only, 33 write. Generated from src/server/agent/tools.ts at build time.

ToolWhat it doesAccess
get_overviewFinancial overviewread
get_net_worthNet worth breakdownread
get_net_worth_historyNet worth historyread
get_net_worth_movesWhat moved net worthread
list_jobsJobs and end-of-service gratuityread
list_accountsList accountsread
get_accountAccount detailsread
list_transactionsList transactionsread
get_spending_by_categorySpending by categoryread
get_budget_statusBudget statusread
get_cashflowMonthly cash flowread
list_categoriesCategories & rulesread
list_remindersList remindersread
list_holdingsInvestment holdingsread
list_connectionsList brokerage connectionsread
list_investment_activityInvestment activityread
get_investment_incomeInvestment incomeread
search_symbolFind a market symbolread
convert_currencyConvert currencyread
query_sqlRead-only SQLread
simulate_mortgageMortgage / purchase simulatorread
borrowing_capacityBorrowing capacityread
simulate_buy_vs_rentBuy vs rentread
project_net_worthNet worth projectionread
list_uploadsUploaded filesread
read_uploadRead an uploaded fileread
import_csv_uploadImport a CSV uploadwrite
import_transactionsImport transactionswrite
record_balanceRecord account balancewrite
add_transactionAdd transactionwrite
categorize_transactionsCategorize transactionswrite
save_ruleAdd or change a categorization rulewrite
delete_ruleDelete a rulewrite
split_transactionSplit a transactionwrite
tag_transactionsTag transactionswrite
create_categoryCreate categorywrite
set_budgetSet monthly budgetwrite
create_accountCreate accountwrite
list_companiesCompanies you ownread
save_companyAdd or update a companywrite
set_company_financialsEnter a company's monthwrite
get_tax_reportTax estimate for a yearread
set_tax_inputSet a tax inputwrite
log_stayLog time spent in a countrywrite
list_staysStays per countryread
share_accountShare an account with a partnerwrite
list_membersMembers of this walletread
list_changesRecent changes (audit trail)read
list_goalsSavings goalsread
save_goalAdd or update a goalwrite
delete_goalDelete a goalwrite
get_investment_analyticsInvestment analyticsread
list_recurringRecurring paymentsread
detect_recurringDetect recurring paymentswrite
save_recurringAdd or update a recurring paymentwrite
delete_recurringDelete a recurring paymentwrite
record_recurring_paymentRecord a recurring paymentwrite
match_transfersMatch transfers between your accountswrite
save_jobAdd or update a jobwrite
add_loan_eventRecord an early repayment or a new ratewrite
update_accountUpdate accountwrite
upsert_holdingAdd or update a holdingwrite
delete_holdingRemove a holdingwrite
refresh_pricesRefresh market priceswrite
sync_connectionSync a brokerage connectionwrite
sync_broker_historyImport brokerage historywrite
create_reminderCreate reminderwrite

Read tools

get_overview

read-onlyFinancial overview

Snapshot of the user's finances in their base currency: net worth (total, assets, liabilities, per asset class), change over 1 month / YTD / 1 year, this month's budget status, the last 6 months of cash flow, upcoming reminders and a list of things that need attention. Start here for any broad question.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

get_net_worth

read-onlyNet worth breakdown

Net worth on a date (default today) with every account: balance in its own currency, owned share, and contribution in the base currency. Loans amortize automatically; accounts with holdings are valued at market prices.

ParameterTypeDescription
datestringYYYY-MM-DD, default today
Input JSON Schema
{
  "type": "object",
  "properties": {
    "date": {
      "description": "YYYY-MM-DD, default today",
      "type": "string"
    }
  }
}

get_net_worth_history

read-onlyNet worth history

Net worth over time (total and per asset class, base currency). granularity 'month' gives month-ends for the last N months plus today; 'day' gives every day for the last N days (investment accounts use their daily market snapshot).

ParameterTypeDescription
granularity"month" | "day"default "month"
monthsintegerFor granularity 'month'1 to 240 · default 24
daysintegerFor granularity 'day'1 to 1830 · default 90
Input JSON Schema
{
  "type": "object",
  "properties": {
    "granularity": {
      "default": "month",
      "type": "string",
      "enum": [
        "month",
        "day"
      ]
    },
    "months": {
      "default": 24,
      "description": "For granularity 'month'",
      "type": "integer",
      "minimum": 1,
      "maximum": 240
    },
    "days": {
      "default": 90,
      "description": "For granularity 'day'",
      "type": "integer",
      "minimum": 1,
      "maximum": 1830
    }
  }
}

get_net_worth_moves

read-onlyWhat moved net worth

How net worth changed over 1 day, 1 week, 1 month, the year to date and 1 year (amount and %), with the accounts behind each change, biggest first. Each mover has a driver: 'balance' (a new balance was recorded), 'market' (prices of holdings), 'loan' (repayment schedule) or 'job' (end-of-service gratuity accruing) or 'fx' (same balance in its own currency, only the exchange rate moved). Movers add up to the change. Use it to answer 'why did my net worth go up/down'.

ParameterTypeDescription
period"1d" | "1w" | "1m" | "ytd" | "1y"One period only; default all
Input JSON Schema
{
  "type": "object",
  "properties": {
    "period": {
      "description": "One period only; default all",
      "type": "string",
      "enum": [
        "1d",
        "1w",
        "1m",
        "ytd",
        "1y"
      ]
    }
  }
}

list_jobs

read-onlyJobs and end-of-service gratuity

The user's jobs with the end-of-service gratuity (EOSG) accrued under each job's country's labour law: years of service, amount owed if they resigned today and if they were let go today, how it was computed, the figure counted in net worth, accrual per day, and the next date the rule improves (e.g. UAE 5-year step from 21 to 30 days a year). Amounts are in the job's currency. Statutory minimums: contracts can be more generous.

ParameterTypeDescription
includeArchivedbooleandefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "includeArchived": {
      "default": false,
      "type": "boolean"
    }
  }
}

list_accounts

read-onlyList accounts

All accounts with type, asset class, currency, current balance (own currency and base currency), ownership share, whether the value comes from holdings or a loan schedule, and when the balance was last updated.

ParameterTypeDescription
includeArchivedbooleandefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "includeArchived": {
      "default": false,
      "type": "boolean"
    }
  }
}

get_account

read-onlyAccount details

One account with its full balance history (snapshots, in the account currency).

ParameterTypeDescription
accountIdrequiredinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "accountId"
  ]
}

list_transactions

read-onlyList transactions

Transactions, newest first, with category, account, currency, payee (display name), tags, splitCount, recurringId and the amount converted to the base currency. Filter by date range, account, category ("none" = uncategorized), tag or a text search.

ParameterTypeDescription
fromstring
tostring
accountIdinteger
categoryIdinteger | "none"
searchstringCase-insensitive text in the bank label or payee
tagstringOnly transactions with this tag
limitinteger1 to 500 · default 50
offsetinteger≥ 0 · default 0
Input JSON Schema
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "categoryId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "const": "none"
        }
      ]
    },
    "search": {
      "description": "Case-insensitive text in the bank label or payee",
      "type": "string"
    },
    "tag": {
      "description": "Only transactions with this tag",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  }
}

get_spending_by_category

read-onlySpending by category

Total spending per expense category (base currency, or `currency`) over a date range (default: current month), largest first.

ParameterTypeDescription
fromstring
tostring
currencystring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    }
  }
}

get_budget_status

read-onlyBudget status

For a month (default current): income, expenses, savings rate, and each category's budget vs spending with a status (ok / ahead_of_pace / over / unbudgeted). Each envelope has its own currency (line.currency; budget/spent/remaining are in it, spending in other currencies converted at each transaction's date) and spentByCurrency shows what was actually paid in which currency. Income, expenses, totals and display* fields are in `currency` (default: base currency).

ParameterTypeDescription
monthstringYYYY-MM
currencystringShow income, expenses and totals in this currency, e.g. AED
Input JSON Schema
{
  "type": "object",
  "properties": {
    "month": {
      "description": "YYYY-MM",
      "type": "string"
    },
    "currency": {
      "description": "Show income, expenses and totals in this currency, e.g. AED",
      "type": "string"
    }
  }
}

get_cashflow

read-onlyMonthly cash flow

Income, expenses, net savings and savings rate per month (base currency, or `currency`) for the last N months; transfers excluded.

ParameterTypeDescription
monthsinteger1 to 60 · default 12
currencystring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "months": {
      "default": 12,
      "type": "integer",
      "minimum": 1,
      "maximum": 60
    },
    "currency": {
      "type": "string"
    }
  }
}

list_categories

read-onlyCategories & rules

Transaction categories (ids, kind), auto-categorization rules and monthly budgets.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

list_reminders

read-onlyList reminders

Telegram reminders with their schedule, next run time and whether they're waiting to be acknowledged.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

list_holdings

read-onlyInvestment holdings

Positions (stocks, ETFs, funds, bonds, crypto, commodities) with quantity, latest price, market value, gain vs cost basis, plus totals by asset type and currency (base currency).

ParameterTypeDescription
accountIdinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  }
}

list_connections

read-onlyList brokerage connections

Brokerage accounts synced automatically (e.g. Trading 212): which wallet account each one fills, how many positions it holds, when it last synced and the last error. Synced holdings are overwritten on every sync (hourly), so change positions at the broker, not with upsert_holding. Connections are added in Settings → Brokerage connections; credentials are never exposed.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

list_investment_activity

read-onlyInvestment activity

Past trades, dividends, deposits, withdrawals, interest and fees imported from connected brokerages (e.g. Trading 212), newest first, with totals of the whole filtered set in the base currency (bought, sold, dividends, interest, deposited, withdrawn, fees, realised P/L). Amounts are in the account currency; cashCents is the signed effect on the account's cash (a buy is negative).

ParameterTypeDescription
accountIdinteger
kind"trade" | "dividend" | "deposit" | "withdrawal" | "interest" | "fee" | "other"
tickerstringBroker ticker (AAPL_US_EQ) or Yahoo symbol (AAPL)
limitinteger1 to 200 · default 50
offsetinteger≥ 0 · default 0
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "kind": {
      "type": "string",
      "enum": [
        "trade",
        "dividend",
        "deposit",
        "withdrawal",
        "interest",
        "fee",
        "other"
      ]
    },
    "ticker": {
      "description": "Broker ticker (AAPL_US_EQ) or Yahoo symbol (AAPL)",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  }
}

get_investment_income

read-onlyInvestment income

Dividends, interest on cash and realised gains per month (base currency), with totals over the window and this year to date, from imported brokerage history. Also money put in vs what it is worth now, the time-weighted return (deposits taken out) and the annual money-weighted return (XIRR).

ParameterTypeDescription
monthsinteger1 to 120 · default 12
Input JSON Schema
{
  "type": "object",
  "properties": {
    "months": {
      "default": 12,
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    }
  }
}

search_symbol

read-onlyFind a market symbol

Look up the market symbol of a stock, ETF, fund, crypto or commodity by name or ISIN (e.g. "MSCI World Amundi", "Apple", "gold"). Use the returned symbol with upsert_holding.

ParameterTypeDescription
queryrequiredstring1 to 80 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  },
  "required": [
    "query"
  ]
}

convert_currency

read-onlyConvert currency

Convert an amount between currencies (ISO codes, plus BTC/ETH/XAU…) with the stored daily rates.

ParameterTypeDescription
amountrequirednumber
fromrequiredstring
torequiredstring
datestring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number"
    },
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "date": {
      "type": "string"
    }
  },
  "required": [
    "amount",
    "from",
    "to"
  ]
}

query_sql

read-onlyRead-only SQL

Run a read-only SQLite SELECT over the user's own data for analysis the other tools don't cover. Returns at most 500 rows.

Tables (only your data; amounts are INTEGER cents in the row's currency; dates are TEXT 'YYYY-MM-DD'):

  • accounts(id, name, institution, type, asset_class ['cash','investments','retirement','real_estate','crypto','commodities','other','liabilities'], currency, ownership_pct, include_in_net_worth, archived_at, linked_account_id, loan_params JSON, gratuity_params JSON [a job: country, startDate, endDate, salaries — its balance is the end-of-service gratuity, computed, never stored], notes)
  • balance_snapshots(id, account_id, date, balance_cents, note, source) — one row per account per day, in the account currency; liabilities store the amount owed as a positive number
  • holdings(id, account_id, symbol, name, asset_type, quantity REAL, currency, cost_basis REAL per unit, manual_price REAL, connection_id, external_id) — connection_id set = synced from a brokerage, overwritten by the next sync
  • prices(symbol, date, close REAL, currency) — daily closes of held symbols
  • fx_rates(currency, date, per_usd REAL) — units of currency per 1 USD
  • transactions(id, account_id, date, amount_cents [negative = spending], currency, description [bank label], payee [display name], tags JSON array, category_id, recurring_id, notes, source)
  • transaction_splits(id, transaction_id, category_id, amount_cents) — parts of a split payment; when present they replace the transaction's category in totals
  • categories(id, name, kind ['income','expense','transfer'], icon)
  • category_rules(id, pattern, category_id, match_type, account_id, direction, min_amount_cents, max_amount_cents, rename_to, add_tag) — rule: label match + optional conditions → category (+ payee rename, tag)
  • budgets(id, category_id, amount_cents, currency) — monthly envelope; currency NULL = the base currency
  • reminders(id, title, message, kind, account_id, frequency, day_of_month, day_of_week, month_of_year, date, time_of_day, nag_every_hours, enabled, next_run_at [ms epoch])
  • recurring(id, name, pattern, account_id, category_id, amount_cents [signed], currency, cadence, next_date, status ['active','suggested','paused','dismissed'], last_matched_date, last_change_pct) — expected payments; transactions.recurring_id links the real ones
  • simulations(id, name, type, params JSON); settings(key, value) — key 'currency' = base currency
  • broker_activity(id, account_id, kind ['trade','dividend','deposit','withdrawal','interest','fee','other'], external_id, at [ISO timestamp], date, ticker, symbol, name, quantity REAL [trades; negative = sale], price REAL [per unit, price_currency], price_currency, cash_cents [signed effect on the account's cash, account currency; a buy is negative], currency, realized_cents [realised P/L of a sale]) — imported broker history
ParameterTypeDescription
sqlrequiredstringA single SELECT (or WITH … SELECT) statementmin 1 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "A single SELECT (or WITH … SELECT) statement"
    }
  },
  "required": [
    "sql"
  ]
}

simulate_mortgage

read-onlyMortgage / purchase simulator

Simulate buying a property with a mortgage (defaults follow French rules: notary fees, borrower insurance on initial capital, guarantee fees, 35% debt-to-income cap — override for other countries). Returns loan amount, monthly payment, total credit cost, APR, debt ratio and a yearly amortization/equity table.

ParameterTypeDescription
pricerequirednumberProperty price (net seller price)> 0
notaryFeesPctnumberNotary fees as % of price (~7.5% existing, ~2.5% new build in France)0 to 20 · default 7.5
agencyFeesnumberAgency fees paid by the buyer, if not in price≥ 0 · default 0
renovationnumberWorks budget financed with the purchase≥ 0 · default 0
downPaymentnumberPersonal contribution (apport)≥ 0 · default 0
annualRatePctnumberNominal loan rate, % per year0 to 25 · default 3.3
insuranceRatePctnumberBorrower insurance, % of initial capital per year0 to 3 · default 0.3
durationYearsinteger1 to 35 · default 25
guaranteeFeesPctnumberLoan guarantee (caution / hypothèque) as % of the loan0 to 5 · default 1.2
bankFeesnumberBank arrangement fees (frais de dossier)≥ 0 · default 1000
monthlyNetIncomenumberHousehold net monthly income, for the debt-to-income ratio≥ 0
otherMonthlyDebtsnumberOther monthly loan payments≥ 0 · default 0
appreciationPctnumberExpected property value growth, % per year-20 to 20 · default 2
Input JSON Schema
{
  "type": "object",
  "properties": {
    "price": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Property price (net seller price)"
    },
    "notaryFeesPct": {
      "default": 7.5,
      "description": "Notary fees as % of price (~7.5% existing, ~2.5% new build in France)",
      "type": "number",
      "minimum": 0,
      "maximum": 20
    },
    "agencyFees": {
      "default": 0,
      "description": "Agency fees paid by the buyer, if not in price",
      "type": "number",
      "minimum": 0
    },
    "renovation": {
      "default": 0,
      "description": "Works budget financed with the purchase",
      "type": "number",
      "minimum": 0
    },
    "downPayment": {
      "default": 0,
      "description": "Personal contribution (apport)",
      "type": "number",
      "minimum": 0
    },
    "annualRatePct": {
      "default": 3.3,
      "description": "Nominal loan rate, % per year",
      "type": "number",
      "minimum": 0,
      "maximum": 25
    },
    "insuranceRatePct": {
      "default": 0.3,
      "description": "Borrower insurance, % of initial capital per year",
      "type": "number",
      "minimum": 0,
      "maximum": 3
    },
    "durationYears": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 35
    },
    "guaranteeFeesPct": {
      "default": 1.2,
      "description": "Loan guarantee (caution / hypothèque) as % of the loan",
      "type": "number",
      "minimum": 0,
      "maximum": 5
    },
    "bankFees": {
      "default": 1000,
      "description": "Bank arrangement fees (frais de dossier)",
      "type": "number",
      "minimum": 0
    },
    "monthlyNetIncome": {
      "description": "Household net monthly income, for the debt-to-income ratio",
      "type": "number",
      "minimum": 0
    },
    "otherMonthlyDebts": {
      "default": 0,
      "description": "Other monthly loan payments",
      "type": "number",
      "minimum": 0
    },
    "appreciationPct": {
      "default": 2,
      "description": "Expected property value growth, % per year",
      "type": "number",
      "minimum": -20,
      "maximum": 20
    }
  },
  "required": [
    "price"
  ]
}

borrowing_capacity

read-onlyBorrowing capacity

Maximum loan and property price affordable for a given income under a debt-to-income cap.

ParameterTypeDescription
monthlyNetIncomerequirednumberHousehold net monthly income> 0
otherMonthlyDebtsnumber≥ 0 · default 0
maxDebtRatioPctnumber1 to 60 · default 35
annualRatePctnumber0 to 25 · default 3.3
insuranceRatePctnumber0 to 3 · default 0.3
durationYearsinteger1 to 35 · default 25
downPaymentnumber≥ 0 · default 0
notaryFeesPctnumber0 to 20 · default 7.5
guaranteeFeesPctnumber0 to 5 · default 1.2
Input JSON Schema
{
  "type": "object",
  "properties": {
    "monthlyNetIncome": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Household net monthly income"
    },
    "otherMonthlyDebts": {
      "default": 0,
      "type": "number",
      "minimum": 0
    },
    "maxDebtRatioPct": {
      "default": 35,
      "type": "number",
      "minimum": 1,
      "maximum": 60
    },
    "annualRatePct": {
      "default": 3.3,
      "type": "number",
      "minimum": 0,
      "maximum": 25
    },
    "insuranceRatePct": {
      "default": 0.3,
      "type": "number",
      "minimum": 0,
      "maximum": 3
    },
    "durationYears": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 35
    },
    "downPayment": {
      "default": 0,
      "type": "number",
      "minimum": 0
    },
    "notaryFeesPct": {
      "default": 7.5,
      "type": "number",
      "minimum": 0,
      "maximum": 20
    },
    "guaranteeFeesPct": {
      "default": 1.2,
      "type": "number",
      "minimum": 0,
      "maximum": 5
    }
  },
  "required": [
    "monthlyNetIncome"
  ]
}

simulate_buy_vs_rent

read-onlyBuy vs rent

Compare buying (mortgage, ownership costs, appreciation, selling costs) against renting and investing the difference, year by year. Returns both net worths per year and the break-even year.

ParameterTypeDescription
pricerequirednumberProperty price (net seller price)> 0
notaryFeesPctnumberNotary fees as % of price (~7.5% existing, ~2.5% new build in France)0 to 20 · default 7.5
agencyFeesnumberAgency fees paid by the buyer, if not in price≥ 0 · default 0
renovationnumberWorks budget financed with the purchase≥ 0 · default 0
downPaymentnumberPersonal contribution (apport)≥ 0 · default 0
annualRatePctnumberNominal loan rate, % per year0 to 25 · default 3.3
insuranceRatePctnumberBorrower insurance, % of initial capital per year0 to 3 · default 0.3
durationYearsinteger1 to 35 · default 25
guaranteeFeesPctnumberLoan guarantee (caution / hypothèque) as % of the loan0 to 5 · default 1.2
bankFeesnumberBank arrangement fees (frais de dossier)≥ 0 · default 1000
appreciationPctnumberExpected property value growth, % per year-20 to 20 · default 2
monthlyRentrequirednumberRent for an equivalent home, per month> 0
rentIncreasePctnumberYearly rent increase, %-5 to 15 · default 2
propertyTaxYearlynumberProperty tax (taxe foncière), per year≥ 0 · default 1200
coOwnershipMonthlynumberBuilding charges (charges de copropriété), per month≥ 0 · default 150
maintenancePctnumberUpkeep, % of property value per year0 to 5 · default 1
sellingCostsPctnumberCosts when selling, % of value0 to 15 · default 5
investmentReturnPctnumberReturn on invested savings, % per year-10 to 20 · default 5
portfolioTaxPctnumberTax on investment gains when cashing out (e.g. 30 flat tax, 17.2 PEA after 5y)0 to 60 · default 0
horizonYearsinteger1 to 40 · default 20
Input JSON Schema
{
  "type": "object",
  "properties": {
    "price": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Property price (net seller price)"
    },
    "notaryFeesPct": {
      "default": 7.5,
      "description": "Notary fees as % of price (~7.5% existing, ~2.5% new build in France)",
      "type": "number",
      "minimum": 0,
      "maximum": 20
    },
    "agencyFees": {
      "default": 0,
      "description": "Agency fees paid by the buyer, if not in price",
      "type": "number",
      "minimum": 0
    },
    "renovation": {
      "default": 0,
      "description": "Works budget financed with the purchase",
      "type": "number",
      "minimum": 0
    },
    "downPayment": {
      "default": 0,
      "description": "Personal contribution (apport)",
      "type": "number",
      "minimum": 0
    },
    "annualRatePct": {
      "default": 3.3,
      "description": "Nominal loan rate, % per year",
      "type": "number",
      "minimum": 0,
      "maximum": 25
    },
    "insuranceRatePct": {
      "default": 0.3,
      "description": "Borrower insurance, % of initial capital per year",
      "type": "number",
      "minimum": 0,
      "maximum": 3
    },
    "durationYears": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 35
    },
    "guaranteeFeesPct": {
      "default": 1.2,
      "description": "Loan guarantee (caution / hypothèque) as % of the loan",
      "type": "number",
      "minimum": 0,
      "maximum": 5
    },
    "bankFees": {
      "default": 1000,
      "description": "Bank arrangement fees (frais de dossier)",
      "type": "number",
      "minimum": 0
    },
    "appreciationPct": {
      "default": 2,
      "description": "Expected property value growth, % per year",
      "type": "number",
      "minimum": -20,
      "maximum": 20
    },
    "monthlyRent": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Rent for an equivalent home, per month"
    },
    "rentIncreasePct": {
      "default": 2,
      "description": "Yearly rent increase, %",
      "type": "number",
      "minimum": -5,
      "maximum": 15
    },
    "propertyTaxYearly": {
      "default": 1200,
      "description": "Property tax (taxe foncière), per year",
      "type": "number",
      "minimum": 0
    },
    "coOwnershipMonthly": {
      "default": 150,
      "description": "Building charges (charges de copropriété), per month",
      "type": "number",
      "minimum": 0
    },
    "maintenancePct": {
      "default": 1,
      "description": "Upkeep, % of property value per year",
      "type": "number",
      "minimum": 0,
      "maximum": 5
    },
    "sellingCostsPct": {
      "default": 5,
      "description": "Costs when selling, % of value",
      "type": "number",
      "minimum": 0,
      "maximum": 15
    },
    "investmentReturnPct": {
      "default": 5,
      "description": "Return on invested savings, % per year",
      "type": "number",
      "minimum": -10,
      "maximum": 20
    },
    "portfolioTaxPct": {
      "default": 0,
      "description": "Tax on investment gains when cashing out (e.g. 30 flat tax, 17.2 PEA after 5y)",
      "type": "number",
      "minimum": 0,
      "maximum": 60
    },
    "horizonYears": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 40
    }
  },
  "required": [
    "price",
    "monthlyRent"
  ]
}

project_net_worth

read-onlyNet worth projection

Project net worth over N years with monthly contributions, expected return, inflation, one-off events and a Monte Carlo p10/p50/p90 band. Any omitted parameter is filled from the user's data: current net worth, average monthly savings over the last 6 months, and a return/volatility blended from the current asset allocation.

ParameterTypeDescription
startingNetWorthnumberNet worth today
monthlyContributionnumberAmount saved/invested per month
contributionGrowthPctnumberYearly growth of the monthly contribution, %-20 to 30
annualReturnPctnumberExpected blended return, % per year-20 to 30
volatilityPctnumberAnnual volatility for the Monte Carlo band (0 = deterministic only)0 to 100
inflationPctnumber-5 to 20
horizonYearsinteger1 to 60
annualExpensesnumberYearly spending in today's money, to compute a financial-independence target≥ 0
withdrawalRatePctnumber1 to 10
eventsobject[]
events[].yearrequiredintegerYears from now (0 = this year)≥ 0
events[].amountrequirednumberPositive = inflow (inheritance, bonus), negative = outflow (wedding, car)
events[].labelstringdefault ""
simulationsinteger0 to 2000
seedinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "startingNetWorth": {
      "description": "Net worth today",
      "type": "number"
    },
    "monthlyContribution": {
      "description": "Amount saved/invested per month",
      "type": "number"
    },
    "contributionGrowthPct": {
      "description": "Yearly growth of the monthly contribution, %",
      "type": "number",
      "minimum": -20,
      "maximum": 30
    },
    "annualReturnPct": {
      "description": "Expected blended return, % per year",
      "type": "number",
      "minimum": -20,
      "maximum": 30
    },
    "volatilityPct": {
      "description": "Annual volatility for the Monte Carlo band (0 = deterministic only)",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "inflationPct": {
      "description": "",
      "type": "number",
      "minimum": -5,
      "maximum": 20
    },
    "horizonYears": {
      "description": "",
      "type": "integer",
      "minimum": 1,
      "maximum": 60
    },
    "annualExpenses": {
      "description": "Yearly spending in today's money, to compute a financial-independence target",
      "type": "number",
      "minimum": 0
    },
    "withdrawalRatePct": {
      "description": "",
      "type": "number",
      "minimum": 1,
      "maximum": 10
    },
    "events": {
      "description": "",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "year": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Years from now (0 = this year)"
          },
          "amount": {
            "type": "number",
            "description": "Positive = inflow (inheritance, bonus), negative = outflow (wedding, car)"
          },
          "label": {
            "default": "",
            "type": "string"
          }
        },
        "required": [
          "year",
          "amount"
        ]
      }
    },
    "simulations": {
      "description": "",
      "type": "integer",
      "minimum": 0,
      "maximum": 2000
    },
    "seed": {
      "description": "",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  }
}

list_uploads

read-onlyUploaded files

Files the user dropped into the chat (bank CSV exports, PDF statements, screenshots), newest first.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

read_upload

read-onlyRead an uploaded file

Text content of an uploaded file: CSV/TXT/OFX as-is, PDF statements via text extraction. Long files are paged with offset/maxChars. Use it to understand a statement before importing it.

ParameterTypeDescription
uploadIdrequiredstring
offsetinteger≥ 0 · default 0
maxCharsinteger500 to 60000 · default 20000
Input JSON Schema
{
  "type": "object",
  "properties": {
    "uploadId": {
      "type": "string"
    },
    "offset": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "maxChars": {
      "default": 20000,
      "type": "integer",
      "minimum": 500,
      "maximum": 60000
    }
  },
  "required": [
    "uploadId"
  ]
}

list_companies

read-onlyCompanies you own

The user's companies as net-worth assets: country and legal form, valuation method (book = its own accounts' net value; revenue_multiple / profit_multiple = trailing-12-month figure × multiple; manual), value of 100% and the user's share (company currency and base currency), its own accounts (bank, brokerage, loans — counted through the company, never twice), revenue, expenses and profit per month and over the last 12 months, and the margin.

ParameterTypeDescription
monthsintegerMonths of P&L to return1 to 120 · default 24
Input JSON Schema
{
  "type": "object",
  "properties": {
    "months": {
      "default": 24,
      "description": "Months of P&L to return",
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    }
  }
}

get_tax_report

read-onlyTax estimate for a year

Estimate a year's taxes from the user's data, by country: personal income tax where they live (UAE: none; France: barème with parts) and on French-source income for non-residents (20%/30% minimum rate + 17.2% social charges on rent), French rental income (micro-foncier 30% or réel with loan interest from the schedule), IFI on French real estate above 1.3 M€, and corporate tax for each company where it is (UAE 9% above AED 375k with Small Business Relief / Qualifying Free Zone; France IS 15%/25%). Also days spent per country and residency notes. Every line cites its law; inputs it can't infer are listed in `inputs` and set with set_tax_input. An estimate, not a filing.

ParameterTypeDescription
yearrequiredinteger2000 to 2100
Input JSON Schema
{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 2000,
      "maximum": 2100
    }
  },
  "required": [
    "year"
  ]
}

list_stays

read-onlyStays per country

Logged stays, and days per country for a year.

ParameterTypeDescription
yearrequiredinteger2000 to 2100
Input JSON Schema
{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 2000,
      "maximum": 2100
    }
  },
  "required": [
    "year"
  ]
}

list_members

read-onlyMembers of this wallet

The other people with an account on this wallet (id and name), to share accounts with.

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

list_changes

read-onlyRecent changes (audit trail)

What changed in the user's data and who did it (the user, the assistant, Telegram or a partner on a shared account), newest first.

ParameterTypeDescription
limitinteger1 to 500 · default 50
Input JSON Schema
{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  }
}

list_goals

read-onlySavings goals

The user's goals: target amount and currency, optional date, the accounts that count (none = whole net worth), current progress and %, what's left, the monthly amount needed to arrive on the date, the pace used (planned monthly, or average savings) and the projected date, and whether it's on track.

ParameterTypeDescription
includeArchivedbooleandefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "includeArchived": {
      "default": false,
      "type": "boolean"
    }
  }
}

get_investment_analytics

read-onlyInvestment analytics

Analytics of the portfolio held today, from daily prices in the base currency (exchange rates included): returns over 1M/3M/6M/YTD/1Y, annual volatility, max drawdown (peak, trough, recovery), Sharpe at 0% risk-free, best/worst day, % of up days, month-by-month returns, per-position weight, returns and 1-year change, allocation by type / currency / region (from the listing exchange) / account, and concentration (top position, top 5, effective number of positions). It describes current positions, not past trades.

ParameterTypeDescription
daysinteger30 to 1830 · default 365
Input JSON Schema
{
  "type": "object",
  "properties": {
    "days": {
      "default": 365,
      "type": "integer",
      "minimum": 30,
      "maximum": 1830
    }
  }
}

list_recurring

read-onlyRecurring payments

Salary, rent, subscriptions and other scheduled money: each item (expected amount and currency, cadence, next date, last matched payment, last price change), suggestions detected from history waiting to be accepted, the next 30 days of expected payments (late = expected and not arrived), monthly totals in the base currency, and a cash forecast. Items are expectations matched against real transactions — they never create transactions on their own.

ParameterTypeDescription
daysinteger1 to 365 · default 30
Input JSON Schema
{
  "type": "object",
  "properties": {
    "days": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  }
}

Write tools

Hidden from every surface when WALLET_AGENT_READONLY=1. After a write, the agent's SQL sandbox for that user is dropped so the next query_sql sees the change.

import_csv_upload

writeImport a CSV upload

Import every row of an uploaded bank CSV as transactions (server-side, any size). Without a mapping the columns are guessed; check the returned preview and re-run with an explicit mapping if dates/amounts/signs look wrong. Duplicates from earlier imports are skipped and categorization rules applied.

ParameterTypeDescription
uploadIdrequiredstring
accountIdintegerAccount the statement belongs to
currencystringCurrency of the amounts (default: the account's)
mappingobject
mapping.daterequiredstringHeader of the date column
mapping.descriptionrequiredstringHeader of the label/description column
mapping.amountstringHeader of a single signed amount column
mapping.debitstringHeader of the money-out column (when there is no single amount column)
mapping.creditstringHeader of the money-in column
mapping.dateFormat"auto" | "dmy" | "mdy" | "ymd"default "auto"
mapping.invertSignbooleanTrue when the export shows spending as positive numbersdefault false
dryRunbooleanParse and preview without importingdefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "uploadId": {
      "type": "string"
    },
    "accountId": {
      "description": "Account the statement belongs to",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "currency": {
      "description": "Currency of the amounts (default: the account's)",
      "type": "string"
    },
    "mapping": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Header of the date column"
        },
        "description": {
          "type": "string",
          "description": "Header of the label/description column"
        },
        "amount": {
          "description": "Header of a single signed amount column",
          "type": "string"
        },
        "debit": {
          "description": "Header of the money-out column (when there is no single amount column)",
          "type": "string"
        },
        "credit": {
          "description": "Header of the money-in column",
          "type": "string"
        },
        "dateFormat": {
          "default": "auto",
          "type": "string",
          "enum": [
            "auto",
            "dmy",
            "mdy",
            "ymd"
          ]
        },
        "invertSign": {
          "default": false,
          "description": "True when the export shows spending as positive numbers",
          "type": "boolean"
        }
      },
      "required": [
        "date",
        "description"
      ]
    },
    "dryRun": {
      "default": false,
      "description": "Parse and preview without importing",
      "type": "boolean"
    }
  },
  "required": [
    "uploadId"
  ]
}

import_transactions

writeImport transactions

Bulk-add transactions you extracted yourself (e.g. from a PDF statement or a screenshot). Amounts are signed (negative = spending). Duplicates are skipped; `category` is matched to an existing category name, otherwise rules apply.

ParameterTypeDescription
accountIdinteger
currencystringDefault currency of the rows (default: the account's)
rowsrequiredobject[]1 to 2000 items
rows[].daterequiredstring
rows[].amountrequirednumber
rows[].descriptionrequiredstring1 to 300 chars
rows[].currencystring
rows[].categorystringExisting category name
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "currency": {
      "description": "Default currency of the rows (default: the account's)",
      "type": "string"
    },
    "rows": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300
          },
          "currency": {
            "type": "string"
          },
          "category": {
            "description": "Existing category name",
            "type": "string"
          }
        },
        "required": [
          "date",
          "amount",
          "description"
        ]
      }
    }
  },
  "required": [
    "rows"
  ]
}

record_balance

writeRecord account balance

Set an account's balance (in the account's currency) for a date (default today), e.g. read from a bank app or statement. For loans, pass the amount still owed. Not needed for accounts valued from holdings.

ParameterTypeDescription
accountIdrequiredinteger
balancerequirednumber
datestring
notestringmax 500 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "balance": {
      "type": "number"
    },
    "date": {
      "type": "string"
    },
    "note": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "accountId",
    "balance"
  ]
}

add_transaction

writeAdd transaction

Add one transaction. Amount is signed: negative for spending, positive for income. Currency defaults to the account's. If categoryId is omitted, categorization rules are applied.

ParameterTypeDescription
datestring
amountrequirednumber
currencystring
descriptionrequiredstringmin 1 chars
categoryIdinteger
accountIdinteger
notesstring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "date": {
      "type": "string"
    },
    "amount": {
      "type": "number"
    },
    "currency": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "minLength": 1
    },
    "categoryId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "notes": {
      "type": "string"
    }
  },
  "required": [
    "amount",
    "description"
  ]
}

categorize_transactions

writeCategorize transactions

Assign a category to transactions. Optionally pass rememberPattern (a lowercase merchant keyword like "carrefour") to create a rule that also categorizes all other matching uncategorized transactions and future imports.

ParameterTypeDescription
transactionIdsrequiredinteger[]max 500 items
categoryIdrequiredinteger
rememberPatternstringmin 2 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "transactionIds": {
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "categoryId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "rememberPattern": {
      "type": "string",
      "minLength": 2
    }
  },
  "required": [
    "transactionIds",
    "categoryId"
  ]
}

save_rule

writeAdd or change a categorization rule

A rule files transactions automatically (on add, on import, and with apply). Match the bank label (contains / starts / exact), optionally only on one account, only money in or out, or within an amount range; then set the category, and optionally rename the payee and add a tag. The most specific matching rule wins, then the longest pattern. Pass id to change a rule; set apply to also file existing uncategorized transactions.

ParameterTypeDescription
patternrequiredstringText to look for in the bank label (case-insensitive)2 to 120 chars
categoryIdrequiredinteger
matchType"contains" | "starts" | "exact"default "contains"
accountIdinteger | nullOnly for this account
direction"in" | "out" | nullOnly money in, or only money out
minAmountnumber | nullOnly when the amount (absolute) is at least this≥ 0
maxAmountnumber | nullOnly when the amount (absolute) is at most this≥ 0
renameTostring | nullShow the payee under this namemax 120 chars
addTagstring | nullAdd this tagmax 40 chars
idinteger
applybooleandefault true
Input JSON Schema
{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Text to look for in the bank label (case-insensitive)"
    },
    "categoryId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "matchType": {
      "default": "contains",
      "type": "string",
      "enum": [
        "contains",
        "starts",
        "exact"
      ]
    },
    "accountId": {
      "description": "Only for this account",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "direction": {
      "description": "Only money in, or only money out",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "in",
            "out"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "minAmount": {
      "description": "Only when the amount (absolute) is at least this",
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "maxAmount": {
      "description": "Only when the amount (absolute) is at most this",
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "renameTo": {
      "description": "Show the payee under this name",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ]
    },
    "addTag": {
      "description": "Add this tag",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 40
        },
        {
          "type": "null"
        }
      ]
    },
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "apply": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "pattern",
    "categoryId"
  ]
}

delete_rule

writeDelete a rule

Delete a categorization rule. Transactions it filed keep their category.

ParameterTypeDescription
idrequiredinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ]
}

split_transaction

writeSplit a transaction

Split one payment over several categories (e.g. a supermarket receipt: groceries + household). Parts are signed like the transaction and must add up to it exactly; budgets then count each part in its category. An empty parts list removes the split.

ParameterTypeDescription
transactionIdrequiredinteger
partsrequiredobject[]
parts[].categoryIdrequiredinteger | null
parts[].amountrequirednumber
parts[].notestring | nullmax 200 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "transactionId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "parts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "categoryId": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "amount": {
            "type": "number"
          },
          "note": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "categoryId",
          "amount"
        ]
      }
    }
  },
  "required": [
    "transactionId",
    "parts"
  ]
}

tag_transactions

writeTag transactions

Add and/or remove free tags (e.g. trip-japan, reimbursable) on transactions. list_transactions filters by tag.

ParameterTypeDescription
transactionIdsrequiredinteger[]max 1000 items
addstring[]
removestring[]
Input JSON Schema
{
  "type": "object",
  "properties": {
    "transactionIds": {
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "add": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "remove": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "transactionIds"
  ]
}

create_category

writeCreate category

Create a transaction category.

ParameterTypeDescription
namerequiredstring1 to 60 chars
kindrequired"income" | "expense" | "transfer"
iconstring | nullmax 8 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "kind": {
      "type": "string",
      "enum": [
        "income",
        "expense",
        "transfer"
      ]
    },
    "icon": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 8
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name",
    "kind"
  ]
}

set_budget

writeSet monthly budget

Set the monthly budget of an expense category, in a currency of your choice (e.g. rent in EUR, groceries in AED; default: keep the envelope's currency, or the base currency for a new one). Spending in other currencies counts at each transaction's exchange rate. 0 removes the budget.

ParameterTypeDescription
categoryIdrequiredinteger
monthlyAmountrequirednumber≥ 0
currencystring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "categoryId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "monthlyAmount": {
      "type": "number",
      "minimum": 0
    },
    "currency": {
      "type": "string"
    }
  },
  "required": [
    "categoryId",
    "monthlyAmount"
  ]
}

create_account

writeCreate account

Create an account (bank, savings, brokerage, crypto wallet, property, loan…) in any currency. For an amortizing loan pass loanParams so its balance is computed automatically. For investment accounts, add positions with upsert_holding instead of a balance. Set country (FR for a French flat) so tax reports know where its income comes from, and companyId when the account belongs to one of the user's companies. Jobs and companies have their own tools (save_job, save_company).

ParameterTypeDescription
namerequiredstring1 to 120 chars
institutionstring | nullmax 120 chars
typerequired"checking" | "savings" | "brokerage" | "pea" | "life_insurance" | "employee_savings" | "retirement" | "end_of_service" | "crypto" | "precious_metals" | "real_estate" | "company" | "vehicle" | "other_asset" | "mortgage" | "loan" | "credit_card" | "other_liability"
assetClass"cash" | "investments" | "retirement" | "real_estate" | "crypto" | "commodities" | "business" | "other" | "liabilities"Override the class implied by the type
currencystringAccount currency (default: your base currency)
ownershipPctnumber0 to 100 · default 100
includeInNetWorthbooleandefault true
linkedAccountIdinteger | null
loanParamsobject | null
loanParams.principalrequirednumber> 0
loanParams.annualRatePctrequirednumber0 to 30
loanParams.durationMonthsrequiredinteger1 to 600
loanParams.startDaterequiredstring
loanParams.insuranceRatePctnumber0 to 5
loanParams.eventsobject[]Early repayments and rate renegotiations since the startmax 100 items
loanParams.events[].daterequiredstring
loanParams.events[].typerequired"prepayment" | "rate_change"
loanParams.events[].amountnumber> 0
loanParams.events[].ratePctnumber0 to 30
loanParams.events[].keep"duration" | "payment"
gratuityParamsobject | nullFor a job (type end_of_service): country, dates and salary the gratuity is computed from
gratuityParams.countryrequired"AE" | "AE_DIFC" | "SA" | "QA" | "FR" | "CUSTOM"
gratuityParams.rolestring | nullmax 120 chars
gratuityParams.startDaterequiredstring
gratuityParams.endDatestring | nullLast day of work; empty while the job is ongoing
gratuityParams.salariesrequiredobject[]min 1 items
gratuityParams.salaries[].fromrequiredstring
gratuityParams.salaries[].monthlyrequirednumber≥ 0
gratuityParams.scenario"resignation" | "termination"default "resignation"
gratuityParams.customobject | null
gratuityParams.custom.daysPerYearrequirednumber0 to 366
gratuityParams.custom.minYearsnumber0 to 20 · default 1
gratuityParams.custom.capMonthsnumber | null0 to 600
companyParamsobject | nullFor a company (type company): its country, legal form and how to value it
companyParams.countryrequiredstring2 to 2 chars
companyParams.legalFormstring | nullmax 60 chars
companyParams.valuation"book" | "revenue_multiple" | "profit_multiple" | "manual"default "book"
companyParams.multiplenumber | null0 to 100
companyParams.fiscalYearStartMonthinteger | null1 to 12
companyIdinteger | nullThe company this account belongs to (its bank, brokerage, loan)
countrystring | nullISO country the account is in (FR for a French flat): decides where its income is taxed2 to 2 chars
notesstring | nullmax 2000 chars
initialBalancenumberCurrent balance in the account currency, recorded as of today
Input JSON Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "institution": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ]
    },
    "type": {
      "type": "string",
      "enum": [
        "checking",
        "savings",
        "brokerage",
        "pea",
        "life_insurance",
        "employee_savings",
        "retirement",
        "end_of_service",
        "crypto",
        "precious_metals",
        "real_estate",
        "company",
        "vehicle",
        "other_asset",
        "mortgage",
        "loan",
        "credit_card",
        "other_liability"
      ]
    },
    "assetClass": {
      "description": "Override the class implied by the type",
      "type": "string",
      "enum": [
        "cash",
        "investments",
        "retirement",
        "real_estate",
        "crypto",
        "commodities",
        "business",
        "other",
        "liabilities"
      ]
    },
    "currency": {
      "description": "Account currency (default: your base currency)",
      "type": "string"
    },
    "ownershipPct": {
      "default": 100,
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "includeInNetWorth": {
      "default": true,
      "type": "boolean"
    },
    "linkedAccountId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "loanParams": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "principal": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "annualRatePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 30
            },
            "durationMonths": {
              "type": "integer",
              "minimum": 1,
              "maximum": 600
            },
            "startDate": {
              "type": "string"
            },
            "insuranceRatePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "events": {
              "description": "Early repayments and rate renegotiations since the start",
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "prepayment",
                      "rate_change"
                    ]
                  },
                  "amount": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "ratePct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 30
                  },
                  "keep": {
                    "type": "string",
                    "enum": [
                      "duration",
                      "payment"
                    ]
                  }
                },
                "required": [
                  "date",
                  "type"
                ]
              }
            }
          },
          "required": [
            "principal",
            "annualRatePct",
            "durationMonths",
            "startDate"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "gratuityParams": {
      "description": "For a job (type end_of_service): country, dates and salary the gratuity is computed from",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country": {
              "type": "string",
              "enum": [
                "AE",
                "AE_DIFC",
                "SA",
                "QA",
                "FR",
                "CUSTOM"
              ]
            },
            "role": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 120
                },
                {
                  "type": "null"
                }
              ]
            },
            "startDate": {
              "type": "string"
            },
            "endDate": {
              "description": "Last day of work; empty while the job is ongoing",
              "type": [
                "string",
                "null"
              ]
            },
            "salaries": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string"
                  },
                  "monthly": {
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "from",
                  "monthly"
                ]
              }
            },
            "scenario": {
              "default": "resignation",
              "type": "string",
              "enum": [
                "resignation",
                "termination"
              ]
            },
            "custom": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "daysPerYear": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 366
                    },
                    "minYears": {
                      "default": 1,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 20
                    },
                    "capMonths": {
                      "anyOf": [
                        {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 600
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "daysPerYear"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "country",
            "startDate",
            "salaries"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "companyParams": {
      "description": "For a company (type company): its country, legal form and how to value it",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "legalForm": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 60
                },
                {
                  "type": "null"
                }
              ]
            },
            "valuation": {
              "default": "book",
              "type": "string",
              "enum": [
                "book",
                "revenue_multiple",
                "profit_multiple",
                "manual"
              ]
            },
            "multiple": {
              "anyOf": [
                {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100
                },
                {
                  "type": "null"
                }
              ]
            },
            "fiscalYearStartMonth": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 12
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "country"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "companyId": {
      "description": "The company this account belongs to (its bank, brokerage, loan)",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "country": {
      "description": "ISO country the account is in (FR for a French flat): decides where its income is taxed",
      "anyOf": [
        {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "initialBalance": {
      "description": "Current balance in the account currency, recorded as of today",
      "type": "number"
    }
  },
  "required": [
    "name",
    "type"
  ]
}

save_company

writeAdd or update a company

Add a company the user owns (omit accountId) or update one. params.country is where it is taxed (AE, FR…), params.valuation picks how it is valued: 'book' (its own accounts' net value — then attach its bank/brokerage/loan accounts with companyId on create_account/update_account), 'revenue_multiple' or 'profit_multiple' (with params.multiple), or 'manual' (with initialValue for 100%). ownershipPct is the user's share.

ParameterTypeDescription
accountIdintegerExisting company to update; omit to add one
namerequiredstring1 to 120 chars
currencystringCurrency its books are in, e.g. AED3 to 10 chars
ownershipPctnumberYour share of the company0 to 100
paramsrequiredobject
params.countryrequiredstring2 to 2 chars
params.legalFormstring | nullmax 60 chars
params.valuation"book" | "revenue_multiple" | "profit_multiple" | "manual"default "book"
params.multiplenumber | null0 to 100
params.fiscalYearStartMonthinteger | null1 to 12
initialValuenumberFor manual valuation: today's value of 100% of the company
notesstring | nullmax 2000 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "description": "Existing company to update; omit to add one",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "currency": {
      "description": "Currency its books are in, e.g. AED",
      "type": "string",
      "minLength": 3,
      "maxLength": 10
    },
    "ownershipPct": {
      "description": "Your share of the company",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "params": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "legalForm": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "valuation": {
          "default": "book",
          "type": "string",
          "enum": [
            "book",
            "revenue_multiple",
            "profit_multiple",
            "manual"
          ]
        },
        "multiple": {
          "anyOf": [
            {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            {
              "type": "null"
            }
          ]
        },
        "fiscalYearStartMonth": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1,
              "maximum": 12
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "country"
      ]
    },
    "initialValue": {
      "description": "For manual valuation: today's value of 100% of the company",
      "type": "number"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name",
    "params"
  ]
}

set_company_financials

writeEnter a company's month

Record a company's revenue and expenses for one month (YYYY-MM, company currency, both positive), e.g. from the accountant, when its bank isn't imported. Added to what its accounts' transactions show. Zeros clear the month.

ParameterTypeDescription
companyIdrequiredinteger
monthrequiredstring
revenuerequirednumber≥ 0
expensesrequirednumber≥ 0
notestringmax 300 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "companyId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "month": {
      "type": "string"
    },
    "revenue": {
      "type": "number",
      "minimum": 0
    },
    "expenses": {
      "type": "number",
      "minimum": 0
    },
    "note": {
      "type": "string",
      "maxLength": 300
    }
  },
  "required": [
    "companyId",
    "month",
    "revenue",
    "expenses"
  ]
}

set_tax_input

writeSet a tax input

Set what the tax estimate can't infer, for one year (or year 0 for every year): residence (ISO country, e.g. AE), homeOrJobInUae (true/false), fr.parts (family parts, e.g. 2 for a couple), fr.rental.regime (micro|reel), fr.rental.gross / fr.rental.expenses / fr.rental.interest (EUR, to override what was computed), fr.socialRate (standard|eea), fr.otherIncome, ifi.base (EUR), company.<id>.sbr / company.<id>.qfzp (true/false), company.<id>.rate (%), company.<id>.profit, other.<CC>.rate (% for income from a country without rules). An empty value clears it.

ParameterTypeDescription
yearrequiredinteger0 to 2100
keyrequiredstring
valuerequiredstring
Input JSON Schema
{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2100
    },
    "key": {
      "type": "string"
    },
    "value": {
      "type": "string"
    }
  },
  "required": [
    "year",
    "key",
    "value"
  ]
}

log_stay

writeLog time spent in a country

Record a stay (inclusive dates) in a country, for the tax-residency day count (UAE: 183 days, or 90 with a home or job there; France: séjour principal).

ParameterTypeDescription
countryrequiredstring2 to 2 chars
fromDaterequiredstring
toDaterequiredstring
notestring | nullmax 200 chars
Input JSON Schema
{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "fromDate": {
      "type": "string"
    },
    "toDate": {
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "country",
    "fromDate",
    "toDate"
  ]
}

share_account

writeShare an account with a partner

Share one of the user's accounts with another member of this wallet (memberId from list_members): it shows in their accounts and net worth at sharePct of it. role 'edit' lets them record balances; 'view' doesn't. remove: true stops sharing. Transactions stay private.

ParameterTypeDescription
accountIdrequiredinteger
memberIdrequiredstring
role"view" | "edit"default "view"
sharePctnumber0 to 100 · default 50
removebooleandefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "memberId": {
      "type": "string"
    },
    "role": {
      "default": "view",
      "type": "string",
      "enum": [
        "view",
        "edit"
      ]
    },
    "sharePct": {
      "default": 50,
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "remove": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "accountId",
    "memberId"
  ]
}

save_goal

writeAdd or update a goal

Add a goal (omit id) or change one: name, target and currency, optional targetDate, accountIds that hold it (empty = whole net worth), optional planned monthly contribution.

ParameterTypeDescription
namerequiredstring1 to 120 chars
iconstring | nullmax 8 chars
targetrequirednumber> 0
currencystring
targetDatestring | null
accountIdsinteger[]Accounts that count towards it; empty = the whole net worthmax 50 items · default []
monthlynumber | nullPlanned monthly contribution; empty = your average savings≥ 0
idinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "icon": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 8
        },
        {
          "type": "null"
        }
      ]
    },
    "target": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "currency": {
      "type": "string"
    },
    "targetDate": {
      "type": [
        "string",
        "null"
      ]
    },
    "accountIds": {
      "default": [],
      "description": "Accounts that count towards it; empty = the whole net worth",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "monthly": {
      "description": "Planned monthly contribution; empty = your average savings",
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "name",
    "target"
  ]
}

delete_goal

writeDelete a goal

Delete a goal. Its accounts are untouched.

ParameterTypeDescription
idrequiredinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ]
}

detect_recurring

writeDetect recurring payments

Scan the last 18 months for payments that repeat (same payee and account, regular interval, similar amount) and store them as suggestions. Accept one with save_recurring (status active) or dismiss it (status dismissed).

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

save_recurring

writeAdd or update a recurring payment

Add a recurring item (omit id) or change one (id): salary (+amount), rent or a subscription (−amount), with its cadence and next expected date. Use status 'active' to accept a suggestion, 'paused' or 'dismissed' to stop it. Statements are matched to it automatically; nothing is created on a schedule.

ParameterTypeDescription
namestring1 to 120 chars
patternstringText the bank label contains (default: from the name)2 to 120 chars
accountIdinteger | null
categoryIdinteger | null
amountnumberExpected amount, signed: negative for money out (rent), positive for money in (salary)
currencystring
cadence"weekly" | "biweekly" | "monthly" | "quarterly" | "yearly"
nextDatestringNext date it is expected
tolerancePctnumber0 to 100
windowDaysinteger0 to 31
status"active" | "suggested" | "paused" | "dismissed"
idinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "pattern": {
      "description": "Text the bank label contains (default: from the name)",
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "accountId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "categoryId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "type": "number",
      "description": "Expected amount, signed: negative for money out (rent), positive for money in (salary)"
    },
    "currency": {
      "type": "string"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "weekly",
        "biweekly",
        "monthly",
        "quarterly",
        "yearly"
      ]
    },
    "nextDate": {
      "type": "string",
      "description": "Next date it is expected"
    },
    "tolerancePct": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "windowDays": {
      "type": "integer",
      "minimum": 0,
      "maximum": 31
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "suggested",
        "paused",
        "dismissed"
      ]
    },
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  }
}

delete_recurring

writeDelete a recurring payment

Delete a recurring item. Transactions already matched to it stay, unlinked.

ParameterTypeDescription
idrequiredinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ]
}

record_recurring_payment

writeRecord a recurring payment

Write the transaction for a recurring item that no statement will bring (cash rent, an account you don't import). If a statement later contains the same payment (same account and amount, within 5 days), the import takes this row over instead of duplicating it.

ParameterTypeDescription
idrequiredinteger
datestring
amountnumber
Input JSON Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "date": {
      "type": "string"
    },
    "amount": {
      "type": "number"
    }
  },
  "required": [
    "id"
  ]
}

match_transfers

writeMatch transfers between your accounts

Find money moved between the user's own accounts — an uncategorized outflow on one account and an inflow on another within a few days, equal once converted (within ~2% for FX spread and fees, e.g. AED sent to a EUR account) — and file both sides under Transfers so budgets and cash flow stop counting them as spending and income. Runs automatically after imports; use dryRun to just list the pairs.

ParameterTypeDescription
dryRunbooleandefault false
fromstring
tostring
daysintegerMax days between the two sides0 to 10 · default 3
tolerancePctnumberMax difference after conversion, %0 to 10 · default 2
Input JSON Schema
{
  "type": "object",
  "properties": {
    "dryRun": {
      "default": false,
      "type": "boolean"
    },
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "days": {
      "default": 3,
      "description": "Max days between the two sides",
      "type": "integer",
      "minimum": 0,
      "maximum": 10
    },
    "tolerancePct": {
      "default": 2,
      "description": "Max difference after conversion, %",
      "type": "number",
      "minimum": 0,
      "maximum": 10
    }
  }
}

save_job

writeAdd or update a job

Add a job (or update one with accountId) so its end-of-service gratuity accrues in net worth under the country's law. Countries: AE (UAE mainland: 21 days of basic a year for 5 years then 30, from 1 year, cap 2 years' pay), AE_DIFC (DEWS 5.83%/8.33% of basic a month), SA (half/full month a year, reduced on resignation), QA (3 weeks of basic a year), FR (indemnité légale on dismissal), CUSTOM (days a year). Give the salary the law uses — UAE and Qatar use BASIC salary without allowances — and its currency (e.g. AED). Pass salaries[] for raises. When the gratuity is paid out, archive the account.

ParameterTypeDescription
accountIdintegerExisting job to update; omit to add a job
employerrequiredstring1 to 120 chars
rolestring | nullmax 120 chars
countryrequired"AE" | "AE_DIFC" | "SA" | "QA" | "FR" | "CUSTOM"AE (UAE mainland), AE_DIFC (DIFC, DEWS), SA (Saudi Arabia), QA (Qatar), FR (France), CUSTOM
startDaterequiredstring
endDatestring | nullLast day of work; omit while the job is ongoing
currencystringSalary currency, e.g. AED (default: base currency)3 to 10 chars
monthlySalarynumberMonthly salary the law uses (UAE/Qatar: basic only), from the start date≥ 0
salariesobject[]Full salary history (raises), replacing monthlySalary; each step applies from its date
salaries[].fromrequiredstring
salaries[].monthlyrequirednumber≥ 0
scenario"resignation" | "termination"Exit counted in net worth (default resignation, the conservative one)
customobject | null
custom.daysPerYearrequirednumber
custom.minYearsnumberdefault 1
custom.capMonthsnumber | null
includeInNetWorthboolean
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "description": "Existing job to update; omit to add a job",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "employer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "role": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ]
    },
    "country": {
      "type": "string",
      "enum": [
        "AE",
        "AE_DIFC",
        "SA",
        "QA",
        "FR",
        "CUSTOM"
      ],
      "description": "AE (UAE mainland), AE_DIFC (DIFC, DEWS), SA (Saudi Arabia), QA (Qatar), FR (France), CUSTOM"
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "description": "Last day of work; omit while the job is ongoing",
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "description": "Salary currency, e.g. AED (default: base currency)",
      "type": "string",
      "minLength": 3,
      "maxLength": 10
    },
    "monthlySalary": {
      "description": "Monthly salary the law uses (UAE/Qatar: basic only), from the start date",
      "type": "number",
      "minimum": 0
    },
    "salaries": {
      "description": "Full salary history (raises), replacing monthlySalary; each step applies from its date",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string"
          },
          "monthly": {
            "type": "number",
            "minimum": 0
          }
        },
        "required": [
          "from",
          "monthly"
        ]
      }
    },
    "scenario": {
      "description": "Exit counted in net worth (default resignation, the conservative one)",
      "type": "string",
      "enum": [
        "resignation",
        "termination"
      ]
    },
    "custom": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "daysPerYear": {
              "type": "number"
            },
            "minYears": {
              "default": 1,
              "type": "number"
            },
            "capMonths": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "required": [
            "daysPerYear"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "includeInNetWorth": {
      "type": "boolean"
    }
  },
  "required": [
    "employer",
    "country",
    "startDate"
  ]
}

add_loan_event

writeRecord an early repayment or a new rate

For a loan with a schedule: record an early repayment (type prepayment, amount) or a renegotiated rate (type rate_change, ratePct) on a date. keep 'duration' keeps the end date and lowers the payment; keep 'payment' keeps the payment and ends the loan sooner. The balance, remaining interest and end date follow.

ParameterTypeDescription
accountIdrequiredinteger
daterequiredstring
typerequired"prepayment" | "rate_change"
amountnumber> 0
ratePctnumber0 to 30
keep"duration" | "payment"default "duration"
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "date": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "prepayment",
        "rate_change"
      ]
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "ratePct": {
      "type": "number",
      "minimum": 0,
      "maximum": 30
    },
    "keep": {
      "default": "duration",
      "type": "string",
      "enum": [
        "duration",
        "payment"
      ]
    }
  },
  "required": [
    "accountId",
    "date",
    "type"
  ]
}

update_account

writeUpdate account

Change an account's name, institution, type, currency, ownership share, loan terms, country, company or notes. Changing the currency of an account with recorded balances needs currencyChange: 'relabel' (the currency was wrong, keep the numbers) or 'convert' (it really changed: each past balance is converted at its date's rate).

ParameterTypeDescription
namestring1 to 120 chars
institutionstring | nullmax 120 chars
type"checking" | "savings" | "brokerage" | "pea" | "life_insurance" | "employee_savings" | "retirement" | "end_of_service" | "crypto" | "precious_metals" | "real_estate" | "company" | "vehicle" | "other_asset" | "mortgage" | "loan" | "credit_card" | "other_liability"
assetClass"cash" | "investments" | "retirement" | "real_estate" | "crypto" | "commodities" | "business" | "other" | "liabilities"Override the class implied by the type
currencystringAccount currency (default: your base currency)
ownershipPctnumber0 to 100 · default 100
includeInNetWorthbooleandefault true
linkedAccountIdinteger | null
loanParamsobject | null
loanParams.principalrequirednumber> 0
loanParams.annualRatePctrequirednumber0 to 30
loanParams.durationMonthsrequiredinteger1 to 600
loanParams.startDaterequiredstring
loanParams.insuranceRatePctnumber0 to 5
loanParams.eventsobject[]Early repayments and rate renegotiations since the startmax 100 items
loanParams.events[].daterequiredstring
loanParams.events[].typerequired"prepayment" | "rate_change"
loanParams.events[].amountnumber> 0
loanParams.events[].ratePctnumber0 to 30
loanParams.events[].keep"duration" | "payment"
gratuityParamsobject | nullFor a job (type end_of_service): country, dates and salary the gratuity is computed from
gratuityParams.countryrequired"AE" | "AE_DIFC" | "SA" | "QA" | "FR" | "CUSTOM"
gratuityParams.rolestring | nullmax 120 chars
gratuityParams.startDaterequiredstring
gratuityParams.endDatestring | nullLast day of work; empty while the job is ongoing
gratuityParams.salariesrequiredobject[]min 1 items
gratuityParams.salaries[].fromrequiredstring
gratuityParams.salaries[].monthlyrequirednumber≥ 0
gratuityParams.scenario"resignation" | "termination"default "resignation"
gratuityParams.customobject | null
gratuityParams.custom.daysPerYearrequirednumber0 to 366
gratuityParams.custom.minYearsnumber0 to 20 · default 1
gratuityParams.custom.capMonthsnumber | null0 to 600
companyParamsobject | nullFor a company (type company): its country, legal form and how to value it
companyParams.countryrequiredstring2 to 2 chars
companyParams.legalFormstring | nullmax 60 chars
companyParams.valuation"book" | "revenue_multiple" | "profit_multiple" | "manual"default "book"
companyParams.multiplenumber | null0 to 100
companyParams.fiscalYearStartMonthinteger | null1 to 12
companyIdinteger | nullThe company this account belongs to (its bank, brokerage, loan)
countrystring | nullISO country the account is in (FR for a French flat): decides where its income is taxed2 to 2 chars
notesstring | nullmax 2000 chars
accountIdrequiredinteger
currencyChange"relabel" | "convert"
Input JSON Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "institution": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ]
    },
    "type": {
      "type": "string",
      "enum": [
        "checking",
        "savings",
        "brokerage",
        "pea",
        "life_insurance",
        "employee_savings",
        "retirement",
        "end_of_service",
        "crypto",
        "precious_metals",
        "real_estate",
        "company",
        "vehicle",
        "other_asset",
        "mortgage",
        "loan",
        "credit_card",
        "other_liability"
      ]
    },
    "assetClass": {
      "description": "Override the class implied by the type",
      "type": "string",
      "enum": [
        "cash",
        "investments",
        "retirement",
        "real_estate",
        "crypto",
        "commodities",
        "business",
        "other",
        "liabilities"
      ]
    },
    "currency": {
      "description": "Account currency (default: your base currency)",
      "type": "string"
    },
    "ownershipPct": {
      "default": 100,
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "includeInNetWorth": {
      "default": true,
      "type": "boolean"
    },
    "linkedAccountId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "loanParams": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "principal": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "annualRatePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 30
            },
            "durationMonths": {
              "type": "integer",
              "minimum": 1,
              "maximum": 600
            },
            "startDate": {
              "type": "string"
            },
            "insuranceRatePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "events": {
              "description": "Early repayments and rate renegotiations since the start",
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "prepayment",
                      "rate_change"
                    ]
                  },
                  "amount": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "ratePct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 30
                  },
                  "keep": {
                    "type": "string",
                    "enum": [
                      "duration",
                      "payment"
                    ]
                  }
                },
                "required": [
                  "date",
                  "type"
                ]
              }
            }
          },
          "required": [
            "principal",
            "annualRatePct",
            "durationMonths",
            "startDate"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "gratuityParams": {
      "description": "For a job (type end_of_service): country, dates and salary the gratuity is computed from",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country": {
              "type": "string",
              "enum": [
                "AE",
                "AE_DIFC",
                "SA",
                "QA",
                "FR",
                "CUSTOM"
              ]
            },
            "role": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 120
                },
                {
                  "type": "null"
                }
              ]
            },
            "startDate": {
              "type": "string"
            },
            "endDate": {
              "description": "Last day of work; empty while the job is ongoing",
              "type": [
                "string",
                "null"
              ]
            },
            "salaries": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string"
                  },
                  "monthly": {
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "from",
                  "monthly"
                ]
              }
            },
            "scenario": {
              "default": "resignation",
              "type": "string",
              "enum": [
                "resignation",
                "termination"
              ]
            },
            "custom": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "daysPerYear": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 366
                    },
                    "minYears": {
                      "default": 1,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 20
                    },
                    "capMonths": {
                      "anyOf": [
                        {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 600
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "daysPerYear"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "country",
            "startDate",
            "salaries"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "companyParams": {
      "description": "For a company (type company): its country, legal form and how to value it",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "country": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "legalForm": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 60
                },
                {
                  "type": "null"
                }
              ]
            },
            "valuation": {
              "default": "book",
              "type": "string",
              "enum": [
                "book",
                "revenue_multiple",
                "profit_multiple",
                "manual"
              ]
            },
            "multiple": {
              "anyOf": [
                {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100
                },
                {
                  "type": "null"
                }
              ]
            },
            "fiscalYearStartMonth": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 12
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "country"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "companyId": {
      "description": "The company this account belongs to (its bank, brokerage, loan)",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "country": {
      "description": "ISO country the account is in (FR for a French flat): decides where its income is taxed",
      "anyOf": [
        {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "currencyChange": {
      "type": "string",
      "enum": [
        "relabel",
        "convert"
      ]
    }
  },
  "required": [
    "accountId"
  ]
}

upsert_holding

writeAdd or update a holding

Add a position to an account (or update its quantity/cost if the account already holds that symbol). Use search_symbol to find the symbol. Physical assets without a market (e.g. gold coins, unlisted shares) take a manualPrice instead of a symbol. The latest price is fetched immediately.

ParameterTypeDescription
accountIdrequiredintegerAccount that holds the position (brokerage, PEA, crypto wallet…)
symbolstring | nullYahoo Finance symbol: AAPL, VOO, CW8.PA (Paris), VWCE.DE (Xetra), BTC-USD, GC=F (gold). Omit for manual assets.max 30 chars
namestringDisplay name (defaults to the symbol)max 120 chars
assetType"stock" | "etf" | "fund" | "bond" | "crypto" | "commodity" | "cash" | "other"default "stock"
quantityrequirednumberUnits / shares / coins / ounces held≥ 0
currencystringQuote currency (default: the account's currency)
costBasisnumber | nullAverage purchase price per unit, in the quote currency≥ 0
manualPricenumber | nullPrice per unit when there's no market symbol (or to override it)≥ 0
purchaseDatestring | nullWhen it was bought (average date): the cost is converted to your currency at that day's rate, so gains split into price and currency
Input JSON Schema
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Account that holds the position (brokerage, PEA, crypto wallet…)"
    },
    "symbol": {
      "description": "Yahoo Finance symbol: AAPL, VOO, CW8.PA (Paris), VWCE.DE (Xetra), BTC-USD, GC=F (gold). Omit for manual assets.",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 30
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "description": "Display name (defaults to the symbol)",
      "type": "string",
      "maxLength": 120
    },
    "assetType": {
      "default": "stock",
      "type": "string",
      "enum": [
        "stock",
        "etf",
        "fund",
        "bond",
        "crypto",
        "commodity",
        "cash",
        "other"
      ]
    },
    "quantity": {
      "type": "number",
      "minimum": 0,
      "description": "Units / shares / coins / ounces held"
    },
    "currency": {
      "description": "Quote currency (default: the account's currency)",
      "type": "string"
    },
    "costBasis": {
      "description": "Average purchase price per unit, in the quote currency",
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "manualPrice": {
      "description": "Price per unit when there's no market symbol (or to override it)",
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "purchaseDate": {
      "description": "When it was bought (average date): the cost is converted to your currency at that day's rate, so gains split into price and currency",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "accountId",
    "quantity"
  ]
}

delete_holding

writeRemove a holding

Remove a position (e.g. fully sold).

ParameterTypeDescription
holdingIdrequiredinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "holdingId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "holdingId"
  ]
}

refresh_prices

writeRefresh market prices

Fetch the latest prices for all held symbols now (normally done automatically every few hours).

No parameters.

Input JSON Schema
{
  "type": "object",
  "properties": {}
}

sync_connection

writeSync a brokerage connection

Pull positions, average prices and cash from a connected brokerage now (normally hourly). Omit connectionId to sync every connection. Read-only at the broker: nothing is ever bought or sold. A failure (bad key, rate limit) comes back as ok: false with the error.

ParameterTypeDescription
connectionIdinteger
Input JSON Schema
{
  "type": "object",
  "properties": {
    "connectionId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  }
}

sync_broker_history

writeImport brokerage history

Import past trades, dividends, deposits, withdrawals and interest from a connected brokerage now (normally twice a day), then rebuild the account's value for every past day from them. full: true re-reads the whole history instead of stopping at what is already imported. Read-only at the broker. A long history takes minutes at the broker's rate limit.

ParameterTypeDescription
connectionIdinteger
fullbooleandefault false
Input JSON Schema
{
  "type": "object",
  "properties": {
    "connectionId": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "full": {
      "default": false,
      "type": "boolean"
    }
  }
}

create_reminder

writeCreate reminder

Create a Telegram reminder (e.g. monthly on the 3rd at 19:00: import the bank statement). kind balance_update with accountId lets the user reply with the new balance. nagEveryHours re-sends until acknowledged.

ParameterTypeDescription
titlerequiredstring1 to 120 chars
messagestring | nullmax 1000 chars
kind"custom" | "balance_update" | "statement" | "monthly_report"default "custom"
accountIdinteger | nullFor balance_update: the account to update
frequencyrequired"once" | "weekly" | "monthly" | "quarterly" | "yearly"
dayOfMonthinteger | null1 to 31
dayOfWeekinteger | null1 = Monday … 7 = Sunday1 to 7
monthOfYearinteger | null1 to 12
datestring | null
timeOfDaystringpattern ^([01]\d|2[0-3]):[0-5]\d$ · default "09:00"
nagEveryHoursintegerRe-send every N hours until marked done0 to 168 · default 0
enabledbooleandefault true
Input JSON Schema
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "message": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "kind": {
      "default": "custom",
      "type": "string",
      "enum": [
        "custom",
        "balance_update",
        "statement",
        "monthly_report"
      ]
    },
    "accountId": {
      "description": "For balance_update: the account to update",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "frequency": {
      "type": "string",
      "enum": [
        "once",
        "weekly",
        "monthly",
        "quarterly",
        "yearly"
      ]
    },
    "dayOfMonth": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 31
        },
        {
          "type": "null"
        }
      ]
    },
    "dayOfWeek": {
      "description": "1 = Monday … 7 = Sunday",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 7
        },
        {
          "type": "null"
        }
      ]
    },
    "monthOfYear": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 12
        },
        {
          "type": "null"
        }
      ]
    },
    "date": {
      "type": [
        "string",
        "null"
      ]
    },
    "timeOfDay": {
      "default": "09:00",
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
    },
    "nagEveryHours": {
      "default": 0,
      "description": "Re-send every N hours until marked done",
      "type": "integer",
      "minimum": 0,
      "maximum": 168
    },
    "enabled": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "title",
    "frequency"
  ]
}