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:
| Surface | How it gets the tools |
|---|---|
Built-in assistant, anthropic provider | Tool definitions in every Messages API request (Agent internals) |
Built-in assistant, claude-code / codex providers | The wallet MCP server is the CLI's only tool |
| MCP over stdio | bin/wallet-mcp.mjs (MCP & API) |
| MCP over Streamable HTTP | POST /api/mcp |
| Plain HTTP | GET /api/tools, POST /api/tools/<name> (HTTP API) |
How a call runs
callTool(ctx, name, input) is the single entry point:
- Lookup. Only enabled tools are callable. With
WALLET_AGENT_READONLY=1, write tools are removed from every surface, so a call to one fails withUnknown or disabled tool. - 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). - 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. - Result. Results with the user's money are labelled with their currency (
labelCurrency()): objects without acurrencygetbaseCurrency, and arrays become{ baseCurrency, items }. Calculators, conversions, SQL and file reads are left as they are. The value then goes throughpresent(): fields ending inCentsbecome currency units without the suffix (balanceCents: 123456→balance: 1234.56), dates become ISO strings, anduserIdand binary buffers are dropped. Errors thrown by services are returned as the message text, flagged as an error. - Cache. After any write tool, the user's SQL sandbox is dropped so the next
query_sqlsees 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.
| Tool | What it does | Access |
|---|---|---|
get_overview | Financial overview | read |
get_net_worth | Net worth breakdown | read |
get_net_worth_history | Net worth history | read |
get_net_worth_moves | What moved net worth | read |
list_jobs | Jobs and end-of-service gratuity | read |
list_accounts | List accounts | read |
get_account | Account details | read |
list_transactions | List transactions | read |
get_spending_by_category | Spending by category | read |
get_budget_status | Budget status | read |
get_cashflow | Monthly cash flow | read |
list_categories | Categories & rules | read |
list_reminders | List reminders | read |
list_holdings | Investment holdings | read |
list_connections | List brokerage connections | read |
list_investment_activity | Investment activity | read |
get_investment_income | Investment income | read |
search_symbol | Find a market symbol | read |
convert_currency | Convert currency | read |
query_sql | Read-only SQL | read |
simulate_mortgage | Mortgage / purchase simulator | read |
borrowing_capacity | Borrowing capacity | read |
simulate_buy_vs_rent | Buy vs rent | read |
project_net_worth | Net worth projection | read |
list_uploads | Uploaded files | read |
read_upload | Read an uploaded file | read |
import_csv_upload | Import a CSV upload | write |
import_transactions | Import transactions | write |
record_balance | Record account balance | write |
add_transaction | Add transaction | write |
categorize_transactions | Categorize transactions | write |
save_rule | Add or change a categorization rule | write |
delete_rule | Delete a rule | write |
split_transaction | Split a transaction | write |
tag_transactions | Tag transactions | write |
create_category | Create category | write |
set_budget | Set monthly budget | write |
create_account | Create account | write |
list_companies | Companies you own | read |
save_company | Add or update a company | write |
set_company_financials | Enter a company's month | write |
get_tax_report | Tax estimate for a year | read |
set_tax_input | Set a tax input | write |
log_stay | Log time spent in a country | write |
list_stays | Stays per country | read |
share_account | Share an account with a partner | write |
list_members | Members of this wallet | read |
list_changes | Recent changes (audit trail) | read |
list_goals | Savings goals | read |
save_goal | Add or update a goal | write |
delete_goal | Delete a goal | write |
get_investment_analytics | Investment analytics | read |
list_recurring | Recurring payments | read |
detect_recurring | Detect recurring payments | write |
save_recurring | Add or update a recurring payment | write |
delete_recurring | Delete a recurring payment | write |
record_recurring_payment | Record a recurring payment | write |
match_transfers | Match transfers between your accounts | write |
save_job | Add or update a job | write |
add_loan_event | Record an early repayment or a new rate | write |
update_account | Update account | write |
upsert_holding | Add or update a holding | write |
delete_holding | Remove a holding | write |
refresh_prices | Refresh market prices | write |
sync_connection | Sync a brokerage connection | write |
sync_broker_history | Import brokerage history | write |
create_reminder | Create reminder | write |
Read tools
get_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
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.
| Parameter | Type | Description |
|---|---|---|
date | string | YYYY-MM-DD, default today |
Input JSON Schema
{
"type": "object",
"properties": {
"date": {
"description": "YYYY-MM-DD, default today",
"type": "string"
}
}
}get_net_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).
| Parameter | Type | Description |
|---|---|---|
granularity | "month" | "day" | |
months | integer | For granularity 'month' |
days | integer | For granularity 'day' |
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
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'.
| Parameter | Type | Description |
|---|---|---|
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
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.
| Parameter | Type | Description |
|---|---|---|
includeArchived | boolean |
Input JSON Schema
{
"type": "object",
"properties": {
"includeArchived": {
"default": false,
"type": "boolean"
}
}
}list_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.
| Parameter | Type | Description |
|---|---|---|
includeArchived | boolean |
Input JSON Schema
{
"type": "object",
"properties": {
"includeArchived": {
"default": false,
"type": "boolean"
}
}
}get_account
One account with its full balance history (snapshots, in the account currency).
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"accountId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"accountId"
]
}list_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.
| Parameter | Type | Description |
|---|---|---|
from | string | |
to | string | |
accountId | integer | |
categoryId | integer | "none" | |
search | string | Case-insensitive text in the bank label or payee |
tag | string | Only transactions with this tag |
limit | integer | |
offset | integer |
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
Total spending per expense category (base currency, or `currency`) over a date range (default: current month), largest first.
| Parameter | Type | Description |
|---|---|---|
from | string | |
to | string | |
currency | string |
Input JSON Schema
{
"type": "object",
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"currency": {
"type": "string"
}
}
}get_budget_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).
| Parameter | Type | Description |
|---|---|---|
month | string | YYYY-MM |
currency | string | Show 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
Income, expenses, net savings and savings rate per month (base currency, or `currency`) for the last N months; transfers excluded.
| Parameter | Type | Description |
|---|---|---|
months | integer | |
currency | string |
Input JSON Schema
{
"type": "object",
"properties": {
"months": {
"default": 12,
"type": "integer",
"minimum": 1,
"maximum": 60
},
"currency": {
"type": "string"
}
}
}list_categories
Transaction categories (ids, kind), auto-categorization rules and monthly budgets.
No parameters.
Input JSON Schema
{
"type": "object",
"properties": {}
}list_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
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).
| Parameter | Type | Description |
|---|---|---|
accountId | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"accountId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
}list_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
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).
| Parameter | Type | Description |
|---|---|---|
accountId | integer | |
kind | "trade" | "dividend" | "deposit" | "withdrawal" | "interest" | "fee" | "other" | |
ticker | string | Broker ticker (AAPL_US_EQ) or Yahoo symbol (AAPL) |
limit | integer | |
offset | integer |
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
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).
| Parameter | Type | Description |
|---|---|---|
months | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"months": {
"default": 12,
"type": "integer",
"minimum": 1,
"maximum": 120
}
}
}search_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.
| Parameter | Type | Description |
|---|---|---|
queryrequired | string |
Input JSON Schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"query"
]
}convert_currency
Convert an amount between currencies (ISO codes, plus BTC/ETH/XAU…) with the stored daily rates.
| Parameter | Type | Description |
|---|---|---|
amountrequired | number | |
fromrequired | string | |
torequired | string | |
date | string |
Input JSON Schema
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"date": {
"type": "string"
}
},
"required": [
"amount",
"from",
"to"
]
}query_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
| Parameter | Type | Description |
|---|---|---|
sqlrequired | string | A single SELECT (or WITH … SELECT) statement |
Input JSON Schema
{
"type": "object",
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"description": "A single SELECT (or WITH … SELECT) statement"
}
},
"required": [
"sql"
]
}simulate_mortgage
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.
| Parameter | Type | Description |
|---|---|---|
pricerequired | number | Property price (net seller price) |
notaryFeesPct | number | Notary fees as % of price (~7.5% existing, ~2.5% new build in France) |
agencyFees | number | Agency fees paid by the buyer, if not in price |
renovation | number | Works budget financed with the purchase |
downPayment | number | Personal contribution (apport) |
annualRatePct | number | Nominal loan rate, % per year |
insuranceRatePct | number | Borrower insurance, % of initial capital per year |
durationYears | integer | |
guaranteeFeesPct | number | Loan guarantee (caution / hypothèque) as % of the loan |
bankFees | number | Bank arrangement fees (frais de dossier) |
monthlyNetIncome | number | Household net monthly income, for the debt-to-income ratio |
otherMonthlyDebts | number | Other monthly loan payments |
appreciationPct | number | Expected property value growth, % per year |
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
Maximum loan and property price affordable for a given income under a debt-to-income cap.
| Parameter | Type | Description |
|---|---|---|
monthlyNetIncomerequired | number | Household net monthly income |
otherMonthlyDebts | number | |
maxDebtRatioPct | number | |
annualRatePct | number | |
insuranceRatePct | number | |
durationYears | integer | |
downPayment | number | |
notaryFeesPct | number | |
guaranteeFeesPct | number |
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
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.
| Parameter | Type | Description |
|---|---|---|
pricerequired | number | Property price (net seller price) |
notaryFeesPct | number | Notary fees as % of price (~7.5% existing, ~2.5% new build in France) |
agencyFees | number | Agency fees paid by the buyer, if not in price |
renovation | number | Works budget financed with the purchase |
downPayment | number | Personal contribution (apport) |
annualRatePct | number | Nominal loan rate, % per year |
insuranceRatePct | number | Borrower insurance, % of initial capital per year |
durationYears | integer | |
guaranteeFeesPct | number | Loan guarantee (caution / hypothèque) as % of the loan |
bankFees | number | Bank arrangement fees (frais de dossier) |
appreciationPct | number | Expected property value growth, % per year |
monthlyRentrequired | number | Rent for an equivalent home, per month |
rentIncreasePct | number | Yearly rent increase, % |
propertyTaxYearly | number | Property tax (taxe foncière), per year |
coOwnershipMonthly | number | Building charges (charges de copropriété), per month |
maintenancePct | number | Upkeep, % of property value per year |
sellingCostsPct | number | Costs when selling, % of value |
investmentReturnPct | number | Return on invested savings, % per year |
portfolioTaxPct | number | Tax on investment gains when cashing out (e.g. 30 flat tax, 17.2 PEA after 5y) |
horizonYears | integer |
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
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.
| Parameter | Type | Description |
|---|---|---|
startingNetWorth | number | Net worth today |
monthlyContribution | number | Amount saved/invested per month |
contributionGrowthPct | number | Yearly growth of the monthly contribution, % |
annualReturnPct | number | Expected blended return, % per year |
volatilityPct | number | Annual volatility for the Monte Carlo band (0 = deterministic only) |
inflationPct | number | |
horizonYears | integer | |
annualExpenses | number | Yearly spending in today's money, to compute a financial-independence target |
withdrawalRatePct | number | |
events | object[] | |
events[].yearrequired | integer | Years from now (0 = this year) |
events[].amountrequired | number | Positive = inflow (inheritance, bonus), negative = outflow (wedding, car) |
events[].label | string | |
simulations | integer | |
seed | integer |
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
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
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.
| Parameter | Type | Description |
|---|---|---|
uploadIdrequired | string | |
offset | integer | |
maxChars | integer |
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
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.
| Parameter | Type | Description |
|---|---|---|
months | integer | Months of P&L to return |
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
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.
| Parameter | Type | Description |
|---|---|---|
yearrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"year": {
"type": "integer",
"minimum": 2000,
"maximum": 2100
}
},
"required": [
"year"
]
}list_stays
Logged stays, and days per country for a year.
| Parameter | Type | Description |
|---|---|---|
yearrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"year": {
"type": "integer",
"minimum": 2000,
"maximum": 2100
}
},
"required": [
"year"
]
}list_members
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
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.
| Parameter | Type | Description |
|---|---|---|
limit | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 500
}
}
}list_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.
| Parameter | Type | Description |
|---|---|---|
includeArchived | boolean |
Input JSON Schema
{
"type": "object",
"properties": {
"includeArchived": {
"default": false,
"type": "boolean"
}
}
}get_investment_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.
| Parameter | Type | Description |
|---|---|---|
days | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"days": {
"default": 365,
"type": "integer",
"minimum": 30,
"maximum": 1830
}
}
}list_recurring
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.
| Parameter | Type | Description |
|---|---|---|
days | integer |
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
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.
| Parameter | Type | Description |
|---|---|---|
uploadIdrequired | string | |
accountId | integer | Account the statement belongs to |
currency | string | Currency of the amounts (default: the account's) |
mapping | object | |
mapping.daterequired | string | Header of the date column |
mapping.descriptionrequired | string | Header of the label/description column |
mapping.amount | string | Header of a single signed amount column |
mapping.debit | string | Header of the money-out column (when there is no single amount column) |
mapping.credit | string | Header of the money-in column |
mapping.dateFormat | "auto" | "dmy" | "mdy" | "ymd" | |
mapping.invertSign | boolean | True when the export shows spending as positive numbers |
dryRun | boolean | Parse and preview without importing |
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
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.
| Parameter | Type | Description |
|---|---|---|
accountId | integer | |
currency | string | Default currency of the rows (default: the account's) |
rowsrequired | object[] | |
rows[].daterequired | string | |
rows[].amountrequired | number | |
rows[].descriptionrequired | string | |
rows[].currency | string | |
rows[].category | string | Existing 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
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.
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | integer | |
balancerequired | number | |
date | string | |
note | string |
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
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.
| Parameter | Type | Description |
|---|---|---|
date | string | |
amountrequired | number | |
currency | string | |
descriptionrequired | string | |
categoryId | integer | |
accountId | integer | |
notes | string |
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
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.
| Parameter | Type | Description |
|---|---|---|
transactionIdsrequired | integer[] | |
categoryIdrequired | integer | |
rememberPattern | string |
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
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.
| Parameter | Type | Description |
|---|---|---|
patternrequired | string | Text to look for in the bank label (case-insensitive) |
categoryIdrequired | integer | |
matchType | "contains" | "starts" | "exact" | |
accountId | integer | null | Only for this account |
direction | "in" | "out" | null | Only money in, or only money out |
minAmount | number | null | Only when the amount (absolute) is at least this |
maxAmount | number | null | Only when the amount (absolute) is at most this |
renameTo | string | null | Show the payee under this name |
addTag | string | null | Add this tag |
id | integer | |
apply | boolean |
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
Delete a categorization rule. Transactions it filed keep their category.
| Parameter | Type | Description |
|---|---|---|
idrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id"
]
}split_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.
| Parameter | Type | Description |
|---|---|---|
transactionIdrequired | integer | |
partsrequired | object[] | |
parts[].categoryIdrequired | integer | null | |
parts[].amountrequired | number | |
parts[].note | string | null |
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
Add and/or remove free tags (e.g. trip-japan, reimbursable) on transactions. list_transactions filters by tag.
| Parameter | Type | Description |
|---|---|---|
transactionIdsrequired | integer[] | |
add | string[] | |
remove | string[] |
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
Create a transaction category.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | |
kindrequired | "income" | "expense" | "transfer" | |
icon | string | null |
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
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.
| Parameter | Type | Description |
|---|---|---|
categoryIdrequired | integer | |
monthlyAmountrequired | number | |
currency | string |
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
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).
| Parameter | Type | Description |
|---|---|---|
namerequired | string | |
institution | string | null | |
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 |
currency | string | Account currency (default: your base currency) |
ownershipPct | number | |
includeInNetWorth | boolean | |
linkedAccountId | integer | null | |
loanParams | object | null | |
loanParams.principalrequired | number | |
loanParams.annualRatePctrequired | number | |
loanParams.durationMonthsrequired | integer | |
loanParams.startDaterequired | string | |
loanParams.insuranceRatePct | number | |
loanParams.events | object[] | Early repayments and rate renegotiations since the start |
loanParams.events[].daterequired | string | |
loanParams.events[].typerequired | "prepayment" | "rate_change" | |
loanParams.events[].amount | number | |
loanParams.events[].ratePct | number | |
loanParams.events[].keep | "duration" | "payment" | |
gratuityParams | object | null | For 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.role | string | null | |
gratuityParams.startDaterequired | string | |
gratuityParams.endDate | string | null | Last day of work; empty while the job is ongoing |
gratuityParams.salariesrequired | object[] | |
gratuityParams.salaries[].fromrequired | string | |
gratuityParams.salaries[].monthlyrequired | number | |
gratuityParams.scenario | "resignation" | "termination" | |
gratuityParams.custom | object | null | |
gratuityParams.custom.daysPerYearrequired | number | |
gratuityParams.custom.minYears | number | |
gratuityParams.custom.capMonths | number | null | |
companyParams | object | null | For a company (type company): its country, legal form and how to value it |
companyParams.countryrequired | string | |
companyParams.legalForm | string | null | |
companyParams.valuation | "book" | "revenue_multiple" | "profit_multiple" | "manual" | |
companyParams.multiple | number | null | |
companyParams.fiscalYearStartMonth | integer | null | |
companyId | integer | null | The company this account belongs to (its bank, brokerage, loan) |
country | string | null | ISO country the account is in (FR for a French flat): decides where its income is taxed |
notes | string | null | |
initialBalance | number | Current 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
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.
| Parameter | Type | Description |
|---|---|---|
accountId | integer | Existing company to update; omit to add one |
namerequired | string | |
currency | string | Currency its books are in, e.g. AED |
ownershipPct | number | Your share of the company |
paramsrequired | object | |
params.countryrequired | string | |
params.legalForm | string | null | |
params.valuation | "book" | "revenue_multiple" | "profit_multiple" | "manual" | |
params.multiple | number | null | |
params.fiscalYearStartMonth | integer | null | |
initialValue | number | For manual valuation: today's value of 100% of the company |
notes | string | null |
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
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.
| Parameter | Type | Description |
|---|---|---|
companyIdrequired | integer | |
monthrequired | string | |
revenuerequired | number | |
expensesrequired | number | |
note | string |
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
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.
| Parameter | Type | Description |
|---|---|---|
yearrequired | integer | |
keyrequired | string | |
valuerequired | string |
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
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).
| Parameter | Type | Description |
|---|---|---|
countryrequired | string | |
fromDaterequired | string | |
toDaterequired | string | |
note | string | null |
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
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.
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | integer | |
memberIdrequired | string | |
role | "view" | "edit" | |
sharePct | number | |
remove | boolean |
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
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.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | |
icon | string | null | |
targetrequired | number | |
currency | string | |
targetDate | string | null | |
accountIds | integer[] | Accounts that count towards it; empty = the whole net worth |
monthly | number | null | Planned monthly contribution; empty = your average savings |
id | integer |
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
Delete a goal. Its accounts are untouched.
| Parameter | Type | Description |
|---|---|---|
idrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id"
]
}detect_recurring
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
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.
| Parameter | Type | Description |
|---|---|---|
name | string | |
pattern | string | Text the bank label contains (default: from the name) |
accountId | integer | null | |
categoryId | integer | null | |
amount | number | Expected amount, signed: negative for money out (rent), positive for money in (salary) |
currency | string | |
cadence | "weekly" | "biweekly" | "monthly" | "quarterly" | "yearly" | |
nextDate | string | Next date it is expected |
tolerancePct | number | |
windowDays | integer | |
status | "active" | "suggested" | "paused" | "dismissed" | |
id | integer |
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
Delete a recurring item. Transactions already matched to it stay, unlinked.
| Parameter | Type | Description |
|---|---|---|
idrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id"
]
}record_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.
| Parameter | Type | Description |
|---|---|---|
idrequired | integer | |
date | string | |
amount | number |
Input JSON Schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"date": {
"type": "string"
},
"amount": {
"type": "number"
}
},
"required": [
"id"
]
}match_transfers
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.
| Parameter | Type | Description |
|---|---|---|
dryRun | boolean | |
from | string | |
to | string | |
days | integer | Max days between the two sides |
tolerancePct | number | Max difference after conversion, % |
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
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.
| Parameter | Type | Description |
|---|---|---|
accountId | integer | Existing job to update; omit to add a job |
employerrequired | string | |
role | string | null | |
countryrequired | "AE" | "AE_DIFC" | "SA" | "QA" | "FR" | "CUSTOM" | AE (UAE mainland), AE_DIFC (DIFC, DEWS), SA (Saudi Arabia), QA (Qatar), FR (France), CUSTOM |
startDaterequired | string | |
endDate | string | null | Last day of work; omit while the job is ongoing |
currency | string | Salary currency, e.g. AED (default: base currency) |
monthlySalary | number | Monthly salary the law uses (UAE/Qatar: basic only), from the start date |
salaries | object[] | Full salary history (raises), replacing monthlySalary; each step applies from its date |
salaries[].fromrequired | string | |
salaries[].monthlyrequired | number | |
scenario | "resignation" | "termination" | Exit counted in net worth (default resignation, the conservative one) |
custom | object | null | |
custom.daysPerYearrequired | number | |
custom.minYears | number | |
custom.capMonths | number | null | |
includeInNetWorth | boolean |
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
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.
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | integer | |
daterequired | string | |
typerequired | "prepayment" | "rate_change" | |
amount | number | |
ratePct | number | |
keep | "duration" | "payment" |
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
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).
| Parameter | Type | Description |
|---|---|---|
name | string | |
institution | string | null | |
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 |
currency | string | Account currency (default: your base currency) |
ownershipPct | number | |
includeInNetWorth | boolean | |
linkedAccountId | integer | null | |
loanParams | object | null | |
loanParams.principalrequired | number | |
loanParams.annualRatePctrequired | number | |
loanParams.durationMonthsrequired | integer | |
loanParams.startDaterequired | string | |
loanParams.insuranceRatePct | number | |
loanParams.events | object[] | Early repayments and rate renegotiations since the start |
loanParams.events[].daterequired | string | |
loanParams.events[].typerequired | "prepayment" | "rate_change" | |
loanParams.events[].amount | number | |
loanParams.events[].ratePct | number | |
loanParams.events[].keep | "duration" | "payment" | |
gratuityParams | object | null | For 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.role | string | null | |
gratuityParams.startDaterequired | string | |
gratuityParams.endDate | string | null | Last day of work; empty while the job is ongoing |
gratuityParams.salariesrequired | object[] | |
gratuityParams.salaries[].fromrequired | string | |
gratuityParams.salaries[].monthlyrequired | number | |
gratuityParams.scenario | "resignation" | "termination" | |
gratuityParams.custom | object | null | |
gratuityParams.custom.daysPerYearrequired | number | |
gratuityParams.custom.minYears | number | |
gratuityParams.custom.capMonths | number | null | |
companyParams | object | null | For a company (type company): its country, legal form and how to value it |
companyParams.countryrequired | string | |
companyParams.legalForm | string | null | |
companyParams.valuation | "book" | "revenue_multiple" | "profit_multiple" | "manual" | |
companyParams.multiple | number | null | |
companyParams.fiscalYearStartMonth | integer | null | |
companyId | integer | null | The company this account belongs to (its bank, brokerage, loan) |
country | string | null | ISO country the account is in (FR for a French flat): decides where its income is taxed |
notes | string | null | |
accountIdrequired | integer | |
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
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.
| Parameter | Type | Description |
|---|---|---|
accountIdrequired | integer | Account that holds the position (brokerage, PEA, crypto wallet…) |
symbol | string | null | Yahoo Finance symbol: AAPL, VOO, CW8.PA (Paris), VWCE.DE (Xetra), BTC-USD, GC=F (gold). Omit for manual assets. |
name | string | Display name (defaults to the symbol) |
assetType | "stock" | "etf" | "fund" | "bond" | "crypto" | "commodity" | "cash" | "other" | |
quantityrequired | number | Units / shares / coins / ounces held |
currency | string | Quote currency (default: the account's currency) |
costBasis | number | null | Average purchase price per unit, in the quote currency |
manualPrice | number | null | Price per unit when there's no market symbol (or to override it) |
purchaseDate | string | null | 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 |
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
Remove a position (e.g. fully sold).
| Parameter | Type | Description |
|---|---|---|
holdingIdrequired | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"holdingId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"holdingId"
]
}refresh_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
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.
| Parameter | Type | Description |
|---|---|---|
connectionId | integer |
Input JSON Schema
{
"type": "object",
"properties": {
"connectionId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
}sync_broker_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.
| Parameter | Type | Description |
|---|---|---|
connectionId | integer | |
full | boolean |
Input JSON Schema
{
"type": "object",
"properties": {
"connectionId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"full": {
"default": false,
"type": "boolean"
}
}
}create_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.
| Parameter | Type | Description |
|---|---|---|
titlerequired | string | |
message | string | null | |
kind | "custom" | "balance_update" | "statement" | "monthly_report" | |
accountId | integer | null | For balance_update: the account to update |
frequencyrequired | "once" | "weekly" | "monthly" | "quarterly" | "yearly" | |
dayOfMonth | integer | null | |
dayOfWeek | integer | null | 1 = Monday … 7 = Sunday |
monthOfYear | integer | null | |
date | string | null | |
timeOfDay | string | |
nagEveryHours | integer | Re-send every N hours until marked done |
enabled | boolean |
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"
]
}