# Moneda MCP

> Moneda is a self-custodial Neo Finance app: everyday balances in USD, EUR, CHF, CAD and MXN held as regulated stablecoins on Base, named virtual EUR (SEPA) and USD (ACH) accounts, self-custodial investing in tokenised US-listed shares and in crypto, an optional earnings account supplying Morpho vaults, and a built-in AI financial agent. Users hold their own keys. The Moneda MCP server lets AI assistants work with an account over the Model Context Protocol: checking balances, browsing transactions, managing contacts, and initiating payments that require biometric approval in the mobile app.

## Constraints & Requirements

- Authentication: OAuth 2.0 with PKCE (no passwords shared with AI clients)
- Network: Base (Ethereum L2)
- Supported stablecoins: USDC, EURC, CHFAU, CADD, and MXNB
- Smart account: Safe smart wallet (self-custodial)
- Earnings vaults: Morpho (DeFi lending) and YO Smart Earnings
- All payments require biometric approval in the Moneda mobile app before execution
- On-chain transactions are subject to gas costs (abstracted from users)
- MCP server URL: https://mcp.moneda.com/api/mcp
- Transport: Streamable HTTP
- Tool surface and scope catalogue: see the Tools, Resources, and Scopes sections below for the canonical, always-current list.

---

## How Agents Work with Moneda

Moneda exposes actions to agents through four distinct patterns, each with a different response shape and required follow-up. Knowing the pattern lets your agent handle the response correctly and set the right user expectations. The pattern is detectable from the response shape itself — see the decision table below.

### Pattern 1 — Instant write (no signature, no biometric)

Used for pure server-state mutations: categorising a transaction, adding a note, saving a contact, updating display name, registering an external wallet/bank for future payments. The tool runs the change and returns the final result in the same response.

**Response shape**: `{ success: true, ... }` with the final state.

**Agent behaviour**: show result, continue. No further confirmation needed. These are reversible-by-the-user changes.

**Tools using this pattern today**: `update_display_name`, `update_transaction_category`, `add_transaction_note`, `batch_update_transaction_categories`, `batch_add_transaction_notes`, `add_wallet`, `add_bank`, `add_contact_external`, `add_contact_moneda`.

### Pattern 2 — HITL approval (push notification + polling)

Used for value transfer. The user must explicitly approve each invocation in the Moneda mobile app via biometric. The tool creates a server-side pending request, sends a push notification, and returns immediately.

**Initiation response shape**: `{ paymentRequestId, status: "PENDING_APPROVAL", expiresAt, amount, currency }`.

**Status response shape (terminal)**: `{ paymentRequestId, status: "COMPLETED" | "FAILED" | "EXPIRED" | "REJECTED", transactionHash? }`.

**Agent behaviour**:
1. Call `initiate_payment`. Tell the user a notification has been sent and to approve in the Moneda app.
2. Poll `get_payment_status({ paymentRequestId })` every 3-5 seconds for the first minute, then every 10-15 seconds. Stop on terminal status or after `expiresAt`.
3. Tell the user the outcome.

**Don't poll faster than once per second** — rate limits apply. **Don't retry initiation** if the user rejects — they explicitly declined.

**Tools using this pattern today**: `initiate_payment`, `get_payment_status`.

### Pattern 3 — Claim-link (one-time browser handoff for setup)

Used for one-time device-bound ceremonies — registering a new passkey, installing an on-chain Smart Session, accepting a recovery email. The tool creates a server-side pending claim and returns a short-lived signed URL.

**Response shape**: `{ claimId, activationUrl, expiresAt }`.

**Agent behaviour**:
1. Render the `activationUrl` as a clickable link (desktop) or a plain URL (mobile, where it opens in any browser). The user's synced passkey (iCloud Keychain, Google Password Manager, 1Password, etc.) signs the ceremony in the browser — no Moneda app required.
2. Briefly tell the user what they're signing for ("This sets up account recovery using ada@example.com — open the link and confirm with your passkey").
3. For actions with follow-on state, poll a corresponding status endpoint. For one-shot actions, no polling needed.

**Cross-device case**: if the user's passkey lives on a different device than where they're chatting, browser WebAuthn handles cross-device assertion automatically (QR + Bluetooth proximity to the phone). No extra implementation needed.

**Treat the activationUrl as a single-use token**: don't echo it back in conversation; refresh by re-calling the initiation tool if the user needs a new one. The 24-hour `expiresAt` and one-shot consumption bound the blast radius.

**Tools using this pattern**: rolling out alongside agent-mediated signup, scheduled-transaction activation, sub-account create. Today this pattern is in early deployment for signup; the remaining tools will appear in `Read Tools` and `Write Tools` as they ship.

### Pattern 4 — Smart Sessions (delegated execution within bounds)

Used for recurring actions the user wants the agent to perform without asking each time, bounded by an on-chain policy: recipient pin, amount cap, time window. The user installs the session once via passkey (typically through a Pattern 3 claim-link); subsequent executions inside the policy run transparently.

**Setup is itself a Pattern 3 claim-link**: the response includes `activationUrl` for the user to install the session.

**Subsequent execution response shape**: `{ scheduleId, status: "ACTIVE", nextExecutionAt }`.

**Agent behaviour**:
1. **First time**: propose the standing instruction with explicit bounds ("send €100 to your savings vault on the 1st of every month, capped at €1,200/year, expires 2027-05-14"). Initiate, render the resulting `activationUrl`, wait for the user to install.
2. **Thereafter**: query schedule status, propose adjustments, or initiate executions within the bounds without further per-invocation approval. The chain enforces the policy; the user's passkey is the only thing that can revoke or amend.

**Why this is safe**: the bounds are enforced cryptographically on-chain, not by Moneda's servers. The worst a compromised agent can do is what the bounds allowed.

**Tools using this pattern**: rolling out alongside scheduled transactions (PR #1818). The first user is the recurring transfer engine; future users include auto-rebalance, threshold-triggered conversion, and recurring vault contributions.

### Detecting the pattern from a tool response

| Field present | Pattern | Next step |
| --- | --- | --- |
| `success: true` (or terminal data) | Instant | Show result. |
| `paymentRequestId` + `status: "PENDING_APPROVAL"` | HITL | Poll `get_payment_status`. |
| `claimId` + `activationUrl` | Claim-link | Render URL/QR. |
| `scheduleId` + `status: "PENDING_INSTALL"` | Smart Session setup | Render the included `activationUrl`. |
| `scheduleId` + `status: "ACTIVE"` | Smart Session active | Standing instruction is live. |

If a tool response contains both `paymentRequestId` and `activationUrl`, treat as claim-link first (the link is the user's next action) and poll status afterwards. The patterns compose; they don't conflict.

---

## Getting Started

### Quickstart

Connect your AI assistant to your Moneda account in three steps:

1. Add the Moneda MCP server URL to your AI client: `https://mcp.moneda.com/api/mcp`
2. Authorize your account through Moneda's OAuth consent screen
3. Start asking your AI assistant about your finances

See the client setup guide for step-by-step instructions for Claude, ChatGPT, Gemini, Mistral AI, and Perplexity.

### Authentication

Moneda uses OAuth 2.0 with PKCE to securely connect your account to AI clients.

1. Your AI client requests access — it opens a Moneda authorization page in your browser
2. You sign in and approve — you see which permissions the AI is requesting
3. A secure token is issued — the AI client receives a token. Your password is never shared.
4. Tokens refresh automatically — the connection stays active without re-authorization

You can revoke access at any time from the Moneda mobile app.

### Client Setup

**Claude (Anthropic):**
1. Go to Settings → Connectors
2. Select Add custom connector
3. Enter Name: `Moneda`, URL: `https://mcp.moneda.com/api/mcp`
4. Use the attachments button in any chat and select Moneda

**ChatGPT (OpenAI):**
1. Go to Settings → Advanced → Enable Developer Mode
2. Navigate to Connectors tab
3. Click Create, enter Name: `Moneda`, MCP server URL: `https://mcp.moneda.com/api/mcp`, Authentication: OAuth
4. Save — authorization happens on first use

**Gemini (Google):**
1. Open Add custom connector
2. Enter Server name: `Moneda`, Remote MCP server URL: `https://mcp.moneda.com/api/mcp`
3. Open Tools menu and enable the Moneda connector

**Mistral AI:**
1. Open side panel → Intelligence → Connectors
2. Click + Add Connector → Custom MCP Connector
3. Enter Connector name: `Moneda`, Connection server: `https://mcp.moneda.com/api/mcp`
4. Click Connect — authentication is detected automatically

**Perplexity AI:**
1. Open Settings → Connectors
2. Click Add Connector
3. Enter Server Name: `Moneda`, URL: `https://mcp.moneda.com/api/mcp`
4. Toggle Moneda on under Sources on the home screen

**Any MCP-compatible client:**
- Server URL: `https://mcp.moneda.com/api/mcp`
- Transport: Streamable HTTP
- Authentication: OAuth 2.0 (handled automatically)

---

## API Reference

### Read Tools

#### Balances & Finances

**get_balance** — Fetch live balances for USD, EUR, CHF, CAD and MXN accounts and earnings vaults. Optionally filter by currency. Includes balance trend sparklines from recent snapshots and current APY rates for earnings accounts.
- Parameters: currency (USD/EUR)
- Example: "What's my balance?" or "How much EUR do I have?"

**get_lifetime_savings** — See your lifetime savings from using Moneda: the total fees Moneda covered on your behalf (sponsored network and transfer fees) plus the discount your plan gives you versus the Standard plan, in your display currency.
- Example: "How much have I saved with Moneda?"

**get_transactions** — Browse transaction history with filters for date range, amount, type, category, currency, counterparty, and status. Supports standard JSON and tax export CSV formats.
- Parameters: category, counterparty, currency (USD/EUR), startDate, endDate, format (standard/tax_export), hasCategory, hasNote, hasReceipt, limit, minAmount, maxAmount, sort, status, type, typeGroup, year
- Rows the user signed carry a `signer` block: `label` (the passkey nickname, falling back to its provider name) and `kind` (primary / backup). It is ABSENT on rows nobody signed — historical rows and every server-initiated movement (incoming deposits, scheduled transfers, on-ramps). Absent means "no user signature on file", never "an unknown key signed this".
- Refund links: `refundOf` ({ id, transactionHash } or null) names the payment a refund row reverses; `refunds` lists completed refunds of a payment (id, transactionHash, amount, currency, createdAt), empty when none.
- Example: "Show my last 5 transactions" or "What did I spend at restaurants this month?"

**get_spending_by_type_group** — View spending grouped by transaction type group (transfer, exchange, deposit, withdrawal, earnings, topup, offramp) over 7, 30, or 90 days. Optionally filter by currency. Includes period-over-period comparison. Formerly named `get_spending_summary`.
- Parameters: period (7d/30d/90d), currency (USD/EUR)
- Example: "How does my activity break down across transfers, deposits, and earnings this month?"

**get_daily_spending** — Get a daily series of spending totals for a stablecoin over a window. Supply either a rolling `period` or absolute UTC `from`/`to` timestamps.
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), period (1d/1w/1m/1y), from, to
- Example: "Chart my USDC spending over the last week"

**get_spending_by_category** — Group spending by user-assigned transaction category over a window. Transactions without a category land in an `UNCATEGORIZED` bucket.
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), period (1d/1w/1m/1y), from, to
- Example: "What did I spend on groceries last month?"

**get_spending_by_contact** — Get the total amount sent to a single recipient (Moneda user, external bank, or external wallet) over a window. Identify the recipient by their account ID.
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), recipientAccountId, period (1d/1w/1m/1y), from, to
- Example: "How much did I send to Alice this year?"

**get_spending_by_merchant** — Group spending by recipient/merchant. Each Moneda user gets a per-user bucket; off-ramps share a single bucket per type (bank-withdrawal, external-wallet, coinbase, wallet-connect).
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), period (1d/1w/1m/1y), from, to
- Example: "Who did I send the most money to this month?"

**get_spending_comparison** — Compare spending totals across two arbitrary windows (e.g. month-over-month, year-over-year). Returns absolute delta and percentage delta (null when previous total is 0).
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), currentFrom, currentTo, previousFrom, previousTo
- Example: "Compare my spending this month with last month"

**get_spending_transactions** — List the underlying spending transactions for a window. Optionally drill down into a category or merchant bucket. Paginated via take/skip.
- Parameters: currency (USDC/EURC/CHFAU/CADD/MXNB), period (1d/1w/1m/1y), from, to, bucketKind (category/merchant), bucketId, bucketType (user/bank-withdrawal/external-wallet/coinbase/wallet-connect/other), recipientAccountId, orderBy (createdAt/amount), direction (asc/desc), take, skip
- Example: "Show me all the transactions in my groceries category last month"

**get_exchange_rate** — Get the current exchange rate between any two supported currencies (USD, EUR, CHF, CAD, MXN).
- Parameters: from (USD/EUR), to (USD/EUR)
- Example: "What's the USD to EUR exchange rate?"

**get_apy_rates** — Check current APY rates for Morpho Earnings and YO Smart Earnings vaults.
- Parameters: currency (USD/EUR)
- Example: "What are the current earnings rates?"

**get_earnings_time_series** — Get a daily time series of earnings and vault balance for a Morpho or YO vault account. Returns up to one year of UTC-day data points (timestamp, earnings, balance) plus totalEarnings and netDeposits.
- Parameters: chainRef, accountId, vaultProvider (MORPHO/YO)
- Example: "How have my earnings grown over the past year?"

**get_dinari_capabilities** — Check what the user may currently do with tokenized equities (dShares): jurisdiction (BASELINE or US), whether they can trade, and the ordered blockedReasons when they cannot. Call before proposing a stock purchase so the user is told what to fix rather than failing at approval.
- Parameters: none
- Example: "Can I buy stocks through Moneda yet?"

**get_dinari_us_requirements** — For a US-jurisdiction user, list what is outstanding before their brokerage account can open: missing profile fields, unaccepted disclosure keys, missing taxpayer id, and the in-app path to complete them. Returns field NAMES and counts only, never answer values. A non-US user gets an empty, already-complete result. Read-only by design: regulatory disclosures and personal attestations are accepted by the user in the Moneda app, never relayed through an agent.
- Parameters: none
- Example: "What's left before I can trade stocks?"

**get_market_status** — Is the US stock market open, and when does it change? Returns session (pre_market/open/after_hours/closed), open, etDate, tradingDay, holiday, earlyClose, the trading day's four windows as ISO instants, and nextTransition. Public exchange calendar, no account data. Render the instants in the user's own timezone.
- Example: "Is the US market open right now?"

**get_free_trade_allowance** — How many commission-free stock trades are left in the current window, without quoting an order. Returns limit, used, remaining, resetsAt, degraded, and the cheapest higher plan whose allowance would still have covered this window. The window steps from the user's own subscription anniversary, not the calendar month, so quote resetsAt rather than a day of the month. When degraded is true the count could not be read and must not be stated as fact.
- Example: "How many free trades do I have left?"

#### Account Info

**get_wallet** — Get the Moneda smart wallet address on Base. This address only supports USDC, EURC, CHFAU, CADD, and MXNB on Base. Sending other tokens or using other networks will result in permanent loss of funds.
- Example: "What's my wallet address?"

**get_virtual_accounts** — View IBAN (EUR/SEPA) and ACH (USD) virtual bank account details, payment capabilities, and activation status. Minimum transfer: €1 for EUR, $1 for USD.

**get_virtual_account_limits** — Remaining spending limit per direction (deposit = money in, withdrawal = money out) on a rolling 52-week window, plus enhanced-due-diligence (EDD) status. Crossing a limit does NOT reject the transfer: Iron pauses it and gives the user 24 hours to supply a Source-of-Wealth document. `threshold: null` means no enforced cap. Thresholds are personalised per customer — never assume a number. Also returns `rfis` (information requests) and `rfiRequired` (one is waiting on the user's answers).

**get_information_requests** — Compliance information requests (RFIs) Iron/MoonPay has sent the user: `id`, `rfiType`, `status` (`waiting_on_response` | `needs_review` | `closed`), `transactionId`, `sentAt`, and `openRound` (questions, analyst instructions, requested documents). Read-only by design: MoonPay requires the customer to answer personally, so never answer or draft answers on their behalf. Direct the user to Settings > Features and limits in the Moneda app.

**get_settlement_estimate** — The date a US bank (ACH) transfer settles, accounting for Iron's 3:00 PM ET same-day cutoff, weekends, and US federal bank holidays. Takes an optional `submittedAt` ISO timestamp; omit for "if sent now". USD/ACH only — Iron publishes no equivalent cutoff for EUR/SEPA.
- Example: "What's my IBAN?"

**get_contacts** — List saved contacts including Moneda users, external wallets, and bank accounts. Each entry has a contactAccountId for use with initiate_payment.
- Parameters: limit, offset, search
- Example: "Show me my contacts"

**get_my_accounts** — View saved external wallets and bank accounts for withdrawals. Each entry has an accountId for use with initiate_payment.
- Example: "What external accounts do I have saved?"

**get_settings** — View app preferences: language, currency, country, theme, notifications, biometrics, and display options.
- Example: "What are my app settings?"

**get_passkeys** — List registered passkeys.
- Parameters: target (WALLET or LOGIN, default WALLET)
- WALLET rows: id, label, provider, status, masked wallet address, createdAt, kind (primary = the key created at signup, backup = one added later as a second Safe owner), onchainStatus (active / pending / failed / removed — a pending backup is registered but cannot sign yet)
- LOGIN rows: id, label, status, masked credentialId, device, lastUsedAt, createdAt, and provider when it could be identified (absent means unknown — including every credential registered before Moneda recorded it, which cannot be backfilled). The public key is never returned.
- Reports which keys exist, NOT which one signs next. The preferred signing key is stored only on the user's device and no API can read it — never infer it from kind or ordering.
- Example: "Show me my passkeys" / "Do I have a backup passkey?"

**get_recovery_contacts** — View recovery contacts and people who have you as their guardian.
- Example: "Who are my recovery contacts?"

**list_notifications** — List in-app notifications, newest first; pass filter='unread' for unread items.
- Parameters: cursor, limit, filter (all/unread)
- Example: "Do I have any new notifications?"

**get_unread_notification_count** — Get the unread in-app notification count; cheaper than list_notifications when only the count is needed.
- Example: "How many unread notifications do I have?"

**list_recovery_emails** — List the email addresses set up for ZK email-based account recovery.
- Parameters: accountId
- Example: "What recovery emails do I have set up?"

**get_recovery_email** — Get one recovery email's full detail by id.
- Parameters: id
- Example: "Show me the recovery email with that id"

**get_recovery_config** — Get the recovery configuration (accepted recovery emails, total weight, threshold).
- Parameters: accountId
- Example: "Is my email recovery fully set up?"

**get_recovery_status** — Get the most recent ZK email recovery request snapshot for an account.
- Parameters: accountId
- Example: "Is there a recovery in flight on my account?"

#### Points & Referrals

**get_points_balance** — Check current reward points balance.
- Example: "How many points do I have?"

**get_points_activity** — View history of earned and redeemed points.
- Parameters: limit, offset
- Example: "Show my points activity"

**get_points_redemption_config** — Read the points-to-AI-credit rate, the minimum redemption, the monthly cap, your current balance, and the remaining monthly allowance. Call before redeem_points to price and gate a redemption. Requires read:points scope.
- Example: "How many points do I need to redeem for AI credits?"

**get_referral_code** — Get unique referral link and referral count.
- Example: "What's my referral code?"

**get_referees** — List friends referred to Moneda.
- Example: "Who have I referred?"

#### Users

**search_users** — Search Moneda users by username, display name, full email, or phone number. Respects user privacy settings.
- Parameters: query, limit
- Example: "Find the user @alice"

#### Knowledge & Help

**search_knowledge** — Search the Moneda FAQ knowledge base by keyword or question.
- Parameters: query, category, limit
- Example: "How do fees work?"

**list_faq_categories** — List FAQ categories with each question and its id (answers via get_faq_item).
- Parameters: none
- Example: "What topics does the Moneda FAQ cover?"

**get_faq_category** — Browse all FAQ items in a specific category.
- Parameters: slug (about-moneda, fees, security-and-privacy, earnings-account, deposits-and-withdrawals, virtual-accounts, legal-compliance, using-moneda, moneda-card, technical-web3, help)
- Example: "Show me all FAQ items about security"

**get_faq_item** — Read the full answer to a specific FAQ question.
- Parameters: id
- Example: "Tell me more about that FAQ item"

#### Vaults & Sub-Accounts

**list_sub_accounts** — List the user's sub-accounts (vaults / nested Safes). Excludes CLOSED vaults by default.
- Parameters: includeClosed (true/false, default false)
- Example: "List my vaults" or "Show all my sub-accounts including archived ones"

**get_sub_account** — Get one sub-account's full detail by id — name, status, type, members, parent + child Safe addresses, deployment index, close timestamp.
- Parameters: id
- Example: "Show me the details for my Holiday Fund vault"

**get_sub_account_balance** — Read on-chain balances for a sub-account's child Safe. Optionally filter to a single token.

**list_sub_account_proposals** — List the open approval requests on a joint account that needs multiple signatures (M-of-N): spends, withdrawals, membership and threshold changes, each with its approval count out of the threshold and who proposed it. Read-only — approving or executing a request needs the user's passkey on their own device.

**get_sub_account_proposal** — Get one joint-account request by id with its per-member approval list (who approved, who rejected, when).
- Parameters: id, currency (USDC/EURC/CHFAU/CADD/MXNB, optional)
- Example: "What's the USDC balance in my Emergency Fund vault?"

**get_total_wealth** — Aggregate wealth across the user's main account + every live vault. Per-leg breakdown (wallet + Morpho + YO for main; wallet-only for vaults) and per-currency totals (USDC, EURC, CHFAU, CADD, MXNB). USDC and EURC are cross-converted via the on-chain Aerodrome rate; CHFAU, CADD and MXNB keep their own columns.
- Example: "What's my total wealth across all accounts?"

#### Receipts & Bills

**list_receipts** — List the user's transaction receipts (PDFs, images, structured invoices), newest first. Includes extracted summary fields and the linked transaction when attached.
- Parameters: transactionHash (optional), needsReview (optional), status (optional), limit (default 20, max 100), cursor (optional)
- Example: "Show my recent receipts" or "Which receipts need review?"

**get_receipt** — Fetch one receipt by id with full extracted fields plus a presigned download URL valid for ~15 minutes.
- Parameters: id
- Example: "Show me the details of that receipt"

**get_receipt_line_items** — List parsed line items on a receipt — description, quantity, unit price, total, tax rate, category.
- Parameters: receiptId
- Example: "What was on that grocery receipt?"

**search_receipt_line_items** — Search across every parsed line item the user has uploaded; returns matching items, count, and aggregate spend grouped by currency.
- Parameters: query, category (optional), startDate (optional), endDate (optional)
- Example: "How much did I spend on cappuccinos this year?"

**list_bewirtungsbelege** — List German hospitality-receipt (Bewirtungsbeleg) overlays attached to transactions. Includes deductible vs non-deductible split.
- Parameters: transactionHash (optional), limit, cursor
- Example: "Show my business meal receipts for last quarter"

**list_eigenbelege** — List self-issued substitute receipts (Eigenbeleg) for transactions whose original receipts were lost or never issued.
- Parameters: transactionHash (optional), limit, cursor
- Example: "Show my self-issued substitute receipts"

**list_bills** — List the user's bills (AP queue), ordered due-soon first. Cursor-paginated; default status filter `PENDING`.
- Parameters: status (array, optional, default ["PENDING"]), cursor
- Example: "What bills are due soon?"

**get_bill** — Get one bill with full extracted detail — merchant, total, currency, due date, invoice number, vendor IBAN/BIC/routing/account, payment status, presigned download URL.
- Parameters: id
- Example: "Show me the details of that bill"

#### Crypto Conditional Orders

**list_conditional_orders** — List the user's crypto conditional orders (LIMIT / STOP_LOSS / TAKE_PROFIT / TRAILING_STOP, settled via CoW), newest first, with status, trigger, raw-unit amounts, expiry and skipReason. Orders are created in the Moneda app only. Requires read:transactions.
- Parameters: none
- Example: "Which of my crypto orders are still open?"

**get_conditional_order** — Get one crypto conditional order with full status, trigger, amounts and fill details. Requires read:transactions.
- Parameters: orderId
- Example: "Why hasn't my Bitcoin stop-loss run yet?"

#### Payments & Routing

**list_supported_destinations** — List country/currency/rail combinations Moneda can pay out to, with the required fields for each. Provider-agnostic.
- Parameters: countrySymbol (optional, e.g. "BR" for Brazilian PIX only)
- Example: "Can I send money to Mexico?"

**get_payment_quote** — Preview the cost, FX rate, and final amount for moving money between two currencies. Provide exactly one of amountIn or amountOut. Use BEFORE initiate_payment.
- Parameters: fromCurrency, toCurrency, amountIn OR amountOut
- Example: "How much will it cost to send 100 EUR to a USD account?"

**list_banks_for_country** — List Koywe-supported banks for a LATAM country. Required when registering a bank account in Colombia (PSE), Chile (CLP_BANK), or Bolivia (BOB_BANK).
- Parameters: countrySymbol
- Example: "What banks are available in Colombia for transfers?"

#### Agent Sessions

**list_agent_sessions** — List the user's scoped autonomous agent sessions, newest first, with status, spending policy, remaining period cap, and expiry. Filter by status to find active sessions.
- Parameters: status (PENDING_ACTIVATION/ACTIVE/PAUSED/REVOKED/EXPIRED/FAILED_ACTIVATION, optional)
- Scope: read:agent_sessions (not in the default set — must be requested explicitly)
- Example: "Show my agent payment sessions"

**get_current_subscription** — Get the user's current subscription plan and how it's billed: status, plan tier, billingProvider (ONCHAIN/STRIPE), billedTo (balance/card), and balanceFundsRenewal (true only for balance-pay plans — a card plan is unaffected by a 0 balance).
- Example: "What plan am I on and will my low balance affect it?"

**list_subscription_charges** — List the user's subscription charge history (SUBSCRIPTION_CHARGE rows from the keeper cron), newest first. Cursor-paginated with plan tier, billing period (MONTHLY/ANNUAL), amount, currency, status, on-chain hash, dates, and invoice number.
- Parameters: limit, cursor
- Example: "Show my subscription charges"

**get_subscription_invoice** — Generate (idempotently) the ZUGFeRD plan invoice PDF for a subscription charge and return a 1-hour presigned download URL. First call allocates invoice number (YYYY-NNNNNN), renders PDF/A-3 with embedded EN 16931 XML, uploads to S3; subsequent calls return fresh presigned URL. Returns `{ invoiceNumber, downloadUrl }`.
- Parameters: chargeTransactionId
- Example: "Generate an invoice for this charge"

**get_agent_session** — Get one agent session's full detail by id, including its most recent executions. Poll after create_agent_session until status is ACTIVE.
- Parameters: sessionId
- Scope: read:agent_sessions
- Example: "Is my landlord agent session active yet?"

**list_active_sessions** — List the user's active login sessions (signed-in devices and clients: mobile app, web, CLI, API) and connected agents, with location and last-active time.
- Scope: read:sessions
- Example: "What devices am I signed in on?"

**list_api_keys** — List the API keys on the account: name, prefix, permissions, last use, expiry, and whether each is still active.
- Example: "What API keys do I have?"

**create_api_key** — Create an API key for a script, the CLI, or an integration; the secret is returned once and can never be retrieved again.
- Parameters: name, scopes, expiresInDays
- Example: "Create a read-only API key for my accounting script"

**revoke_api_key** — Revoke an API key by id; it stops working on its next request.
- Parameters: keyId
- Example: "Revoke the key I made for the old export script"

#### Bundled Overviews (composites)

**get_account_overview_data** — Fetch a complete account overview in one call: balances, recent transactions (last 7 days), and current APY rates. Use instead of get_balance + get_transactions + get_apy_rates.
- Example: "Give me an overview of my account"

**get_balance_check_data** — Fetch a balance check in one call: all account balances, exchange rates, and APY rates. Use instead of get_balance + get_exchange_rate + get_apy_rates.
- Example: "What's my balance across everything?"

**get_financial_summary_data** — Fetch a comprehensive financial summary in one call: balances, recent transactions, APY rates, and exchange rates.
- Example: "Give me a full summary of my finances"

**get_my_accounts_data** — Fetch all account setup data in one call: wallet address, Moneda balances, virtual bank accounts, and saved external accounts.
- Example: "Show me all my accounts"

**get_earnings_overview_data** — Fetch an earnings overview in one call: earnings vault balances, APY rates, and recent earnings transactions.
- Example: "How are my earnings doing?"

**get_spending_analysis_data** — Fetch a spending analysis in one call: spending by type group, daily totals, and category breakdown for a period.
- Parameters: period (7d/30d/90d, default 30d)
- Example: "Analyze my spending this month"

**get_points_rewards_data** — Fetch points and referral data in one call: points balance, recent activity, referral code, and referees.
- Parameters: activityLimit (1–50, default 10)
- Example: "What's my points and referral status?"

**get_payment_readiness_data** — Fetch a payment-readiness check in one call: KYC status, virtual accounts, external accounts, contact count, and balances.
- Example: "Am I set up to send a payment?"

**get_security_checkup_data** — Fetch a security checkup in one call: passkeys, recovery contacts, and security-related settings.
- Example: "Run a security checkup on my account"

#### Server

**health** — Check MCP server status. No authentication required.
- Example: "Is the Moneda server running?"

### Write Tools

#### Profile

**update_display_name** — Change the account display name.
- Parameters: displayName
- Example: "Change my display name to Federico"

**set_passkey_label** — Give a passkey a nickname so devices are distinguishable in the security screen. Cosmetic only; it cannot add, remove, or weaken a credential.
- Parameters: id (from get_passkeys), target (the same WALLET / LOGIN value get_passkeys returned on that row), label (max 40 characters; empty or null clears it)
- Example: "Rename my hardware key passkey to Backup Yubikey"

#### Transaction Annotations

**update_transaction_category** — Assign a spending category to a transaction.
- Parameters: transactionHash, category (TOP_UP, INVESTMENT, FRIENDS_FAMILY, INTEREST_EARNINGS, SUBSCRIPTIONS, SERVICES, GROCERIES, SHOPPING, RESTAURANTS, TRANSPORT, TRAVEL, UTILITIES, CASH, SALARY, FUEL, EV_CHARGING, GAMBLING, CHARITY_DONATIONS, TAXES, INSURANCE, CARD, HEALTHCARE, GENERAL)
- Example: "Categorize my last coffee purchase as Restaurants"

**add_transaction_note** — Add or update a personal note on a transaction. Maximum 140 characters.
- Parameters: transactionHash, note
- Example: "Add a note to my last transaction: Birthday dinner"

**batch_update_transaction_categories** — Assign spending categories to up to 25 transactions at once.
- Parameters: items (array of transactionHash + category pairs)
- Example: "Categorize all my uncategorized transactions from last week"

**batch_add_transaction_notes** — Add notes to up to 25 transactions at once.
- Parameters: items (array of transactionHash + note pairs)
- Example: "Add notes to my recent transactions"

#### External Accounts

**add_wallet** — Save an external crypto wallet. The wallet must support USDC, EURC, CHFAU, CADD, and MXNB on Base network. User must confirm before saving.
- Parameters: walletName, walletAddress, confirmed
- Example: "Save this wallet address: 0x..."

**add_bank** — Save a bank account. For EU: provide IBAN (and optionally BIC). For US: provide accountNumber, routingNumber, and accountType (CHECKING/SAVINGS).
- Parameters: country, firstName, lastName, iban, bic, accountNumber, routingNumber, accountType
- Example: "Add my bank account"

#### Contacts

**add_contact_external** — Register an external contact with wallet or bank details. EU Travel Rule requires first name, last name, and country of residence.
- Parameters: firstName, lastName, countryOfResidence, walletAddress, walletName, walletConfirmed, iban, bic, bankCountry, accountNumber, routingNumber, accountType, email
- Example: "Add John as an external contact with his wallet address"

**add_contact_moneda** — Add a Moneda user to contacts by username.
- Parameters: username
- Example: "Add @alice to my contacts"

#### Payments

**initiate_payment** — Create a payment request requiring biometric approval in the Moneda mobile app. Supports four payment types: transfer_moneda (to Moneda user), transfer_account (to own external account), transfer_contact_bank (to contact's bank), transfer_contact_wallet (to contact's wallet).
- Parameters: paymentType, amount, currency (USD/EUR), recipientUsername (for transfer_moneda), accountId (for transfer_account), contactUsername + contactAccountId (for transfer_contact_bank/wallet), reference
- Constraint: EUR transfers require SEPA bank accounts (IBAN). USD transfers require ACH bank accounts.
- Optional source: { kind: main } (default), { kind: earnings } (USD/EUR, from the earnings vault), or { kind: sub_account, subAccountId } (single-signature sub-account, Base wallet recipients only; also requires write:sub_accounts)
- Example: "Send $50 to @alice"

**propose_sub_account_top_up** — Propose moving money from the main account into a sub-account, approved and signed in the Moneda mobile app. Requires write:sub_accounts. Poll get_payment_status after calling.
- Parameters: subAccountId, amount, currency (USD/EUR/CHF/CAD/MXN)
- Example: "Put $200 into my Travel vault"

**propose_sub_account_withdraw** — Propose moving money from a single-signature sub-account back to the main account, approved in the Moneda mobile app. Requires write:sub_accounts.
- Parameters: subAccountId, amount, currency (USD/EUR/CHF/CAD/MXN)
- Example: "Move €50 from my Travel vault back to my account"

**propose_sub_account_swap** — Propose a swap inside a sub-account between a currency and a crypto asset; funds stay in the sub-account. Approved in the Moneda mobile app. Requires write:sub_accounts.
- Parameters: subAccountId, fromAsset, toAsset (currency code or asset symbol; one side must be a currency), amount (of fromAsset), slippageBps (optional, 0-200)
- Example: "Swap $100 to Bitcoin in my Savings vault"

**propose_sub_account_freeze** — Propose freezing a sub-account the user created. Unfreezing is app-only. Requires write:sub_accounts.
- Parameters: subAccountId
- Example: "Freeze my Kids vault"

**propose_sub_account_multisig_proposal** — Open a SPEND or WITHDRAW proposal on a joint account that needs more than one approval; co-owners approve and execute in the Moneda mobile app. Requires write:sub_accounts.
- Parameters: subAccountId, proposalType (SPEND/WITHDRAW), amount, currency, description (optional, max 280), recipientUsername / accountId / contactUsername / contactAccountId (SPEND only)
- Example: "Propose paying @landlord $900 from our joint account"

**initiate_currency_exchange** — Exchange money between two of the user's own currency accounts, requiring biometric approval in the Moneda mobile app. The destination is the user's own account in toCurrency. Poll get_payment_status after calling.
- Parameters: amount, fromCurrency, toCurrency (USD/EUR/CHF/CAD/MXN)
- Example: "Exchange $100 into euros"

**propose_scheduled_payment** — Propose a RECURRING payment the user reviews and activates (passkey signature) in the Moneda mobile app. Nothing is scheduled or sent until then; unapproved drafts expire after 48 hours. Not for one-off payments (initiate_payment).
- Parameters: paymentType (transfer_moneda/transfer_contact_wallet), amount, currency (USD/EUR/CHF/CAD), frequency (DAILY/WEEKLY/BIWEEKLY/MONTHLY/QUARTERLY), startDate, endDate (optional), recipientUsername / contactUsername / contactAccountId, reference (optional)
- Example: "Send @alice $50 every month"

**initiate_crypto_trade** — Buy or sell a crypto asset with the user's own balance, approved and signed in the Moneda mobile app at the live price. Not for sending money or converting currencies; the server chooses the route. Poll get_payment_status after calling.

**initiate_token_buy** — Buy a Base token outside initiate_crypto_trade's catalogue, by contract address, spending the user's own USD, EUR, CHF or MXN balance. The token amount is priced at approval; the user approves and signs in the Moneda mobile app. Poll get_payment_status after calling.

**cancel_conditional_order** — Cancel an open crypto conditional order (PENDING_ACTIVATION, ARMED or PUBLISHED). A PUBLISHED order is withdrawn from the CoW order book on-chain first, then marked CANCELLED; on failure it stays live and the call errors (retry). Requires write:trades.
- Parameters: orderId
- Example: "Cancel my ETH take-profit order"

**initiate_earnings_move** — Deposit the user's own money into an earnings vault (MORPHO = Earnings in USD/EUR/MXN, YO = Smart Earnings in USD/EUR) or withdraw it back to the same-currency account, approved and signed in the Moneda mobile app. Poll get_payment_status after calling.
- Parameters: symbol (cbBTC/WETH), side (BUY/SELL), stableCurrency (USD/EUR/CAD/MXN), amount (spent: currency on BUY, asset on SELL)
- Example: "Buy $100 of Bitcoin"

**get_payment_status** — Check status of a pending payment request. Terminal statuses: COMPLETED, FAILED, EXPIRED, REJECTED.
- Parameters: paymentRequestId
- Example: "What's the status of my last payment?"

**pay_x402** — Pay an x402 (HTTP 402 Payment Required) invoice to a wallet address with USDC or EURC, requiring biometric approval in the Moneda mobile app. Settles on-chain to the resource's payTo address; poll get_payment_status and retry the original request once COMPLETED.
- Parameters: payTo, amount, currency (USD/EUR), resource, network, maxAmountRequired, reference
- Example: "This API returned a 402 — pay the x402 invoice for me."

#### Receipts

**request_receipt_upload** — Step 1 of 2 for uploading a local receipt file. Returns a presigned S3 PUT URL, a signed upload key, and a literal curl command for your code sandbox to stage the file. Bytes never enter the conversation context. Follow up with finalize_receipt_upload.
- Parameters: filename, contentType (application/pdf | image/jpeg | image/png)
- Example: "I want to upload a receipt"

**finalize_receipt_upload** — Step 2 of 2 for uploading. Pass the uploadKey from request_receipt_upload after the curl PUT succeeds. Runs OCR + LLM extraction, attempts auto-match to an existing transaction, persists line items.
- Parameters: uploadKey
- Example: (follow-up to request_receipt_upload)

**import_receipt_from_url** — Import a receipt directly from an https:// URL (S3, Drive shared link, public file host). Server fetches behind an SSRF guard, validates, runs OCR + matching. Single tool call.
- Parameters: url
- Example: "Import the receipt from this URL"

**reparse_receipt** — Re-run the OCR / LLM extraction pipeline on an existing receipt and return refreshed fields. Refuses deleted rows and rows without a stored file.

**attach_receipt** — File an unattached receipt against a transaction. A transaction holds at most one receipt, so this reports a conflict if another is already attached; detach that one first. Also clears any pending match suggestion.

**detach_receipt** — Unlink a receipt from its transaction, leaving the receipt itself intact as an orphan. Deletes nothing.

**confirm_receipt_suggestion** — Accept the matcher's suggested transaction for a receipt, promoting the soft suggestion to a real attachment.

**reject_receipt_suggestion** — Dismiss the matcher's suggested transaction for a receipt. The receipt stays an unattached orphan.

**delete_receipt** — Permanently delete a receipt and its stored file. Hard delete: line items and any Bewirtungsbeleg/Eigenbeleg overlay go with it, and there is no undo.
- Parameters: receiptId
- Example: "Delete that duplicate receipt"

**mark_receipt_partial_payment** — Mark a receipt as a partial payment: the document covers more than this one payment (a deposit or instalment against a larger invoice), so its total differing from the transaction amount is expected. Replaces the amount_mismatch review reason with partial_payment, which survives a rescan. Amounts are not changed.
- Parameters: receiptId
- Scope: write:receipts
- Example: "That invoice was only a deposit, stop flagging the amount"

**update_receipt_amounts** — Correct a receipt's top-line amounts when the scan read them wrong. Each field is optional: omit to leave unchanged, null to clear. taxRateValue is a percentage (19 for 19%). A later reparse re-extracts and overwrites them.
- Parameters: receiptId, totalAmountValue, subtotalValue, taxAmountValue, taxRateValue, tipAmountValue (all but receiptId optional, at least one required)
- Scope: write:receipts
- Example: "The total on that receipt is 47.50, not 4.75"

**create_agent_session** — Create a scoped autonomous payment session bound to the agent: a single pinned recipient with per-execution and per-period caps, enforced on-chain by a pre-funded dedicated wallet. Returns a counterfactual wallet address and an activation link. Does NOT activate — the user opens the link in the Moneda app and approves with a passkey to install the on-chain policy and fund the wallet.
- Parameters: recipient, currency (USD/EUR), maxAmountPerExecution, maxAmountPerPeriod, periodSeconds, expiresAt (optional), fundingAmount (optional)
- Scope: write:agent_sessions (not in the default set — must be requested explicitly)
- Example: "Set up an agent that can pay my landlord up to $500 a month"

**agent_execute_payment** — Send a payment to an active session's pinned recipient within its on-chain limits, with no per-payment approval. Rejected if it would exceed the per-execution cap, the remaining period cap, or the funded balance. Pass a stable idempotencyKey for safe retries — retrying with the same key returns the original transaction instead of sending twice.
- Parameters: sessionId, recipient, amount, currency (USD/EUR), idempotencyKey (optional)
- Scope: write:agent_sessions
- Example: "Pay this month's rent from my landlord agent session"

**revoke_agent_session** — Revoke an agent session. Immediately halts all further execution on the backend; the user completes the on-chain uninstall in the Moneda app.
- Parameters: sessionId
- Scope: write:agent_sessions
- Example: "Stop the landlord agent session"

#### Active Sessions

**terminate_session** — Terminate one login session by id (from list_active_sessions). The device is signed out immediately and cannot renew.
- Parameters: sessionId
- Scope: write:sessions (not in the default set — must be requested explicitly)
- Example: "Sign out my old iPhone"

**terminate_all_other_sessions** — Terminate all of the user's login sessions on other devices, keeping the current one. Does not disconnect agent connections.
- Scope: write:sessions
- Example: "Sign me out of every other device"

**disconnect_connected_service** — Disconnect a connected agent (MCP integration) by id or OAuth client id, revoking its access immediately.
- Parameters: serviceId
- Scope: write:sessions
- Example: "Disconnect the ChatGPT connection"

#### Usage Credits

**purchase_usage_credits** — Redeem a completed top-up payment to Moneda for prepaid AI usage credits. The amount is read from the confirmed on-chain payment (never from input), converted to USD budget, and granted exactly once — re-calling with the same hash is safe. The payment is already finished, so there is nothing more to approve.
- Parameters: transactionHash
- Scope: write:usage_credits (not in the default set — must be requested explicitly)
- Example: "I sent the credit payment, here's the transaction hash — add my AI credits."

**set_ai_usage_limit** — Set or clear the monthly spend limit on AI usage credits — the ceiling on how much of the prepaid balance may be consumed per calendar month (resets the 1st, UTC). Pass a USD amount to cap spending, or null to remove the cap (unlimited). Idempotent.
- Parameters: monthlyLimitUsd (number 0–100000, or null for unlimited)
- Scope: write:usage_credits (not in the default set — must be requested explicitly)
- Example: "Cap my AI spending at $50 a month."

**redeem_points** — Redeem Moneda Points for prepaid AI usage credits. Spends points (a negative points transaction) and grants the matching AI budget atomically, enforcing the minimum, the sufficient-balance check, and the monthly cap. Pass a stable requestId (uuid) held across retries when you can: retrying with the same value is a no-op (returns granted:false). Omitting it is safe — the key is derived from (user, points, 30s window) rather than minted at random. Redemptions are final.
- Parameters: points (number), requestId (uuid, optional)
- Scope: write:usage_credits (not in the default set — must be requested explicitly)
- Example: "Redeem 500 points for AI credits."

### Resources

#### Public Resources (no authentication required)

| Resource | URI | Description |
|----------|-----|-------------|
| Supported tokens | `moneda://supported_tokens` | Tokens and network supported by Moneda (USDC, EURC, CHFAU, CADD, and MXNB on Base) |
| Transaction categories | `moneda://transaction_categories` | User-assignable spending categories |
| Transaction type groups | `moneda://transaction_type_groups` | Operation-level groupings (transfer, exchange, deposit, etc.) |
| Knowledge base | `moneda://knowledge` | FAQ categories and item counts |

#### Account Resources (authentication required)

| Resource | URI | Description |
|----------|-----|-------------|
| Profile | `moneda://profile` | Display name, username, KYC status, points balance |
| Wallet | `moneda://wallet` | Smart wallet address and username |
| Balances | `moneda://balances` | Current balances across all accounts and earnings vaults |
| Transactions | `moneda://transactions` | 20 most recent transactions |
| Exchange rates | `moneda://exchange_rates` | Current USD/EUR and EUR/USD rates |
| Points | `moneda://points` | Current points balance |
| Virtual accounts | `moneda://virtual_accounts` | IBAN and ACH virtual bank account details |
| Settings | `moneda://settings` | App preferences (language, currency, theme, notifications) |
| Passkeys | `moneda://passkeys` | Registered passkeys and authentication devices |
| Recovery contacts | `moneda://recovery_contacts` | Recovery contacts and guardian relationships |
| External accounts | `moneda://my_accounts` | Saved wallets and bank accounts for withdrawals |

### OAuth Scopes

#### Read Scopes

| Scope | Description |
|-------|-------------|
| `read:account` | View account details and profile |
| `read:balances` | View account and earnings balances |
| `read:transactions` | View transaction history and details |
| `read:rates` | View real-time exchange rates |
| `read:points` | View points balance and rewards activity |
| `read:referrals` | View referral code and referred friends |
| `read:virtual_accounts` | View virtual bank account details |
| `read:contacts` | View saved contacts and counterparties |
| `read:settings` | View app preferences and notification settings |
| `read:recovery` | View recovery contacts, recovery emails, and guardian relationships |
| `read:passkeys` | View passkeys and authentication devices |
| `read:external_accounts` | View saved wallets and bank accounts |
| `read:knowledge` | Search FAQ and help articles |
| `read:earnings` | View APY rates for earnings products |
| `read:spending` | View spending summaries and category breakdowns |
| `read:users` | Search for Moneda users |
| `read:notifications` | View in-app notifications inbox |
| `read:payments` | Check the status of payment requests |
| `read:sub_accounts` | View sub-account vaults, their balances, and aggregated wealth |
| `read:receipts` | View receipts attached to transactions, line items, and Bewirtungsbeleg/Eigenbeleg overlays |
| `read:subscriptions` | View subscription charge history and generate plan invoice PDFs |
| `read:agent_sessions` | View scoped autonomous agent sessions — status, spending policy, remaining period cap, and recent executions. Not in default scope set. |
| `read:sessions` | View active login sessions (devices and clients signed in to your account) and connected agents. |
| `read:api_keys` | View the API keys on the account — name, prefix, permissions, last use. Never the secret. |
| `write:api_keys` | Create and revoke API keys. Capped to the caller's own permissions; never valid for payments. |
| `read:scheduled_tx` | View scheduled payments, their upcoming dates and their past runs. REST API and CLI only. |
| `read:platform` | View developer organizations, workspaces, members, API keys, usage and audit log. Platform Management REST API only. Not in default scope set. |

#### Write Scopes

| Scope | Description |
|-------|-------------|
| `write:profile` | Update display name and profile information |
| `write:transactions` | Add or update categories and notes on transactions |
| `write:external_accounts` | Add wallets and bank accounts to saved external accounts |
| `write:contacts` | Add Moneda users or external contacts |
| `write:payments` | Create payment and currency exchange requests (requires biometric approval in app) |
| `write:trades` | Propose buying or selling crypto, which you approve and sign in the Moneda app. Not in default scope set. |
| `write:sub_accounts` | Propose sub-account top-ups, withdrawals, swaps, freezes, joint-account proposals and payments from a sub-account, which you approve in the Moneda app. Not in default scope set. |
| `write:receipts` | Upload receipts, edit line items, create Bewirtungsbeleg/Eigenbeleg overlays, re-run extraction |
| `write:agent_sessions` | Create scoped autonomous agent sessions (user approves activation with a passkey), execute payments within an active session's on-chain spending policy, and revoke sessions. Spend is hard-capped on-chain by a pre-funded wallet + pinned recipient. Not in default scope set. |
| `write:usage_credits` | Redeem a completed top-up payment to Moneda for prepaid AI usage credits, and set the monthly spend limit. The purchase amount is read from the confirmed payment, not from input, and the same payment can never be redeemed twice. Only turns a finished payment into credits and adjusts your spending cap — never moves money on its own. Not in default scope set. |
| `write:sessions` | Terminate a login session or disconnect a connected agent. Terminating a session immediately signs that device out. An agent ending your other sessions is a security action — not in default scope set. |
| `write:scheduled_tx` | Pause and resume scheduled payments. It cannot create, edit or cancel them. REST API and CLI only. Not in default scope set. |
| `write:platform` | Manage developer organizations: workspaces, members, invites, API keys, limits, webhooks and billing settings. Organization role still applies. Platform Management REST API only. Not in default scope set. |

---

## Guides

### Use Cases

**Check finances:**
- "What's my balance?" → get_balance
- "How much do I have in USD vs EUR?" → get_balance with currency filter
- "What are my earnings balances and APY rates?" → get_balance + get_apy_rates
- "Show me my virtual bank account details" → get_virtual_accounts

**Review spending:**
- "How much have I spent on restaurants this month?" → get_spending_by_category with period=1m
- "Show me my spending mix for the last 30 days" → get_spending_by_type_group with period=30d
- "What are my biggest expense categories?" → get_spending_by_category
- "Who did I send the most money to this month?" → get_spending_by_merchant
- "Compare my spending this month with last month" → get_spending_comparison
- "Chart my daily USDC spend this week" → get_daily_spending with period=1w

**Search transactions:**
- "Show me all transfers over $500 this month" → get_transactions with minAmount and date filters
- "What did I send to @alice last week?" → get_transactions with counterparty filter
- "List my EUR transactions from January" → get_transactions with currency and date filters

**Categorize transactions:**
- "Categorize my last 10 uncategorized transactions" → get_transactions(hasCategory=false) then batch_update_transaction_categories
- "Add a note: Birthday dinner with friends" → add_transaction_note
- "Mark all my Uber transactions as Transport" → get_transactions(counterparty="Uber") then batch_update_transaction_categories

**Send money:**
- "Send $50 to @bob" → initiate_payment(paymentType="transfer_moneda")
- "Transfer €200 to my bank account" → initiate_payment(paymentType="transfer_account")
- Every payment requires biometric confirmation in the Moneda app.

**Manage contacts:**
- "Add @charlie to my contacts" → add_contact_moneda
- "Save this wallet as my Coinbase wallet: 0x..." → add_wallet
- "Search for a user named Sarah" → search_users

**Export for taxes:**
- "Export my 2025 transactions for taxes" → get_transactions(format="tax_export", year=2025)
- CSV output compatible with Koinly, CoinTracker, and TaxBit.

**Track rewards:**
- "How many points do I have?" → get_points_balance
- "What's my referral code?" → get_referral_code
- "How many friends have I referred?" → get_referees

---

## Integrations

### Base Network

Base is an Ethereum Layer 2 network built by Coinbase. All Moneda transactions execute on Base.

- Low fees — transactions cost a fraction of Ethereum mainnet
- Fast finality — transfers confirm in seconds
- EVM-compatible — built on the same technology as Ethereum
- Only USDC, EURC, CHFAU, CADD, and MXNB tokens are supported on Base

### Safe Smart Accounts

Every Moneda user gets a Safe smart account — a programmable wallet secured by passkeys.

- Self-custodial — only the user can authorize transactions
- Passkey-secured — signed using device secure hardware (Face ID, fingerprint, device PIN)
- Recoverable — social recovery via trusted contacts
- On-chain — funds are visible and verifiable on the public blockchain

### Morpho Earnings

Morpho is a decentralized lending protocol. Moneda's Morpho Earnings vaults generate yield on stablecoins.

- Available for USD, EUR and MXN
- Real-time compounding
- No lock-ups — withdraw at any time
- Audited smart contracts

### YO Smart Earnings

Higher-yield vault using optimized strategies across DeFi lending markets.

- Available for USD and EUR
- Higher APY than standard Morpho vaults
- No lock-ups
- Managed by YO

### OAuth 2.0 with PKCE

Authentication protocol for securely connecting AI clients to Moneda accounts.

- No passwords shared with AI clients
- Granular permission scopes (21 total)
- Automatic token refresh
- Revocable at any time from the mobile app

---

## Examples

### Check balance

```
User: "What's my balance?"
Tool: get_balance()
Response: Your USD account has $1,250.00 and your EUR account has €830.50. You also have $500.00 in Morpho Earnings (3.8% APY).
```

### Send a payment

```
User: "Send $50 to @alice"
Tool: initiate_payment({ paymentType: "transfer_moneda", recipientUsername: "alice", amount: "50.00", currency: "USD" })
Response: Payment request created for $50.00 to @alice. Please approve the transfer in your Moneda app.
```

### Categorize transactions

```
User: "Categorize my last 10 uncategorized transactions"
Tool: get_transactions({ hasCategory: false, limit: 10 })
Tool: batch_update_transaction_categories({ items: [{ transactionHash: "0xabc...", category: "RESTAURANTS" }, { transactionHash: "0xdef...", category: "TRANSPORT" }, ...] })
Response: Categorized 10 transactions: 4 as Restaurants, 3 as Transport, 2 as Shopping, 1 as Groceries.
```

### Export for taxes

```
User: "Export my 2025 transactions for taxes"
Tool: get_transactions({ format: "tax_export", year: 2025 })
Response: Here is your 2025 tax export with 142 transactions in CSV format. Compatible with Koinly, CoinTracker, and TaxBit.
```

### Add an external wallet

```
User: "Save 0x1234...abcd as my Coinbase wallet"
Tool: add_wallet({ walletName: "Coinbase Wallet", walletAddress: "0x1234...abcd", confirmed: false })
Response: Before saving, please confirm this wallet supports USDC/EURC/CHFAU/CADD/MXNB on Base network. Sending other tokens or using other chains will result in permanent loss of funds.
User: "Yes, it supports Base"
Tool: add_wallet({ walletName: "Coinbase Wallet", walletAddress: "0x1234...abcd", confirmed: true })
Response: Wallet "Coinbase Wallet" saved successfully.
```

### Check earnings rates

```
User: "What are the current APY rates?"
Tool: get_apy_rates()
Response: Current rates — Morpho Earnings: 3.8% APY (USD), 2.9% APY (EUR). Smart Earnings: 5.2% APY (USD), 4.1% APY (EUR).
```

---

## About Moneda

Moneda is a Neo Finance app on Base. Users hold, send, invest and earn in a self-custodial smart wallet, and keep their own keys throughout.

- Self-custodial: funds live in a Safe smart wallet the user controls
- Five currencies: hold and earn in USD, EUR, CHF, CAD and MXN, each backed by a regulated stablecoin
- Investing: tokenised US-listed shares, plus Bitcoin and Ethereum, held in the same self-custodial account
- Earnings: deposit into Morpho or YO Smart Earnings vaults for competitive APY with no lock-ups
- Global transfers: send to Moneda users, external wallets, or bank accounts (IBAN/ACH)
- Passwordless security: passkey authentication with Face ID, fingerprint, or device PIN
- Social recovery: designated recovery contacts can help restore access
- AI-ready: manage the account through any MCP-compatible AI assistant

## Security

- Self-custodial smart wallets — Moneda never holds user funds
- Passkey authentication — phishing-resistant, never leaves the device
- Biometric payment approval — every payment requires Face ID or fingerprint
- Social recovery — trusted contacts can help restore access
- OAuth 2.0 with PKCE — credentials never shared with AI clients
- Audited smart contracts — independent security audits on Morpho and Safe
- Data encryption — encrypted in transit and at rest

## Changelog

### March 2026 — v0.3.0 Enriched Tools, Safety Annotations & Security

- get_balance now includes balance trend sparklines from recent snapshots and current APY rates
- get_spending_summary now includes user-assigned category breakdown and period-over-period comparison (later renamed to get_spending_by_type_group when finer breakdown tools were added — see below)
- Safety annotations on all tools (readOnlyHint/destructiveHint) for Anthropic directory compliance
- Security headers: CSP frame-ancestors 'none', X-Frame-Options DENY, X-Content-Type-Options nosniff, HSTS in production
- MCP Registry publishing support (server.json + domain verification endpoint)

### February 2026 — MCP Server Launch (Public Beta)

- 49 tools (38 read, 11 write)
- 15 resources (4 public, 11 account-specific)
- 22 OAuth scopes (17 read, 5 write)
- 5 AI clients: Claude, ChatGPT, Gemini, Mistral AI, Perplexity AI
- OAuth 2.0 with PKCE authentication
- Biometric payment approval
- Tax export in CSV format (Koinly, CoinTracker, TaxBit)
- Batch transaction categorization and annotation (up to 25 at once)