# Moneda MCP

> Moneda is a self-custodial stablecoin wallet for USDC, EURC, CHFAU, CADD, and MXNB on Base. The Moneda MCP server lets AI assistants manage Moneda accounts through 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
- OAuth scopes: 36 supported (25 read + 11 write)
- 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

## Getting Started

- [Quickstart](https://docs.moneda.com/getting-started/quickstart): Connect your AI assistant to your Moneda account in three steps.
- [Authentication](https://docs.moneda.com/getting-started/authentication): How OAuth 2.0 with PKCE secures the connection between your AI client and Moneda.
- [Connect Your AI Assistant](https://docs.moneda.com/getting-started/client-setup): Step-by-step setup instructions for Claude, ChatGPT, Gemini, Mistral AI, and Perplexity.

## API Reference

- [Tools Overview](https://docs.moneda.com/tools/overview): Summary of every MCP tool available to AI assistants, grouped by read vs. write.
- [Read Tools](https://docs.moneda.com/tools/read-tools): Tools for fetching balances, transactions, contacts, spending breakdowns, earnings analytics, recovery setup, notifications, sub-accounts, receipts, bills, and account data.
- [Write Tools](https://docs.moneda.com/tools/write-tools): Tools for updating profiles, categorizing transactions, managing contacts, managing receipts, and initiating payments.
- [Agent Tools (SDK)](https://docs.moneda.com/tools/agent-tools): Provider-agnostic `getAgentTools()` descriptor factory from `@moneda/services` — ~10× cheaper than MCP-over-HTTP for in-process agents. TOON-encoded responses, lite projections, Zod schemas.
- [Resources](https://docs.moneda.com/resources): MCP resources providing automatic context to AI assistants (public + account-specific).
- [Scopes](https://docs.moneda.com/scopes): OAuth permission scopes controlling granular access to account data and actions.

## Guides

- [MCP Overview](https://docs.moneda.com/mcp-overview): What Moneda MCP is, which AI clients are supported, and what capabilities are available.
- [Action Patterns](https://docs.moneda.com/mcp-action-patterns): The four patterns Moneda uses to expose actions — instant write, HITL approval, claim-link handoff, Smart Sessions delegation. Includes response shapes and how an agent should react to each.
- [Working with your AI assistant](https://docs.moneda.com/moneda/working-with-ai): Consumer-facing guide to what an AI assistant can do with a Moneda account and when the user must approve.
- [Use Cases](https://docs.moneda.com/use-cases): Real examples of checking balances, categorizing spending, sending payments, exporting taxes, and managing contacts.

## Integrations

- [Integrations](https://docs.moneda.com/integrations): Technical overview of Base network, Safe smart accounts, Morpho earnings vaults, and OAuth 2.0 authentication.

## Tools

### Read Tools
- list_sub_accounts: List the user's sub-account vaults (excludes closed by default; pass includeClosed for archived).
- get_sub_account: Get one sub-account's full detail by id — name, status, type, members, parent + child Safe addresses.
- get_sub_account_balance: Read on-chain balances for a sub-account's child Safe; optionally filter to one currency.
- get_total_wealth: Aggregate wealth across the main account + every live vault, with per-currency totals (USDC, EURC, CHFAU, CADD, MXNB).
- list_receipts: List the user's transaction receipts, newest first, with extracted summary fields (merchant, total, date) and lifecycle status.
- get_receipt: Get a single receipt with full extracted fields and a presigned download URL valid for ~15 minutes.
- get_receipt_line_items: List parsed line items on a receipt — description, quantity, unit price, total, tax rate, category.
- search_receipt_line_items: Search across every line item the user has uploaded; returns matching items + aggregate spend grouped by currency.
- list_bewirtungsbelege: List German hospitality-receipt (Bewirtungsbeleg) overlays attached to transactions.
- list_eigenbelege: List self-issued substitute receipts (Eigenbeleg) for transactions whose original receipts were lost or never issued.
- list_bills: List the user's bills (AP queue), ordered due-soon first; cursor-paginated; default status filter PENDING.
- get_bill: Get a single bill with full extracted detail — merchant, total, currency, due date, invoice number, vendor IBAN/BIC, payment status, presigned download URL.
- list_supported_destinations: List country/currency/rail combinations Moneda can pay out to, with required fields for each.
- get_payment_quote: Preview cost, FX rate, and final amount for moving money between currencies; use BEFORE initiate_payment.
- list_banks_for_country: List Koywe-supported banks for a LATAM country (used for Colombia/PSE, Chile/CLP_BANK, Bolivia/BOB_BANK bank registration).
- list_cards: List the user's cards with PCI-redacted metadata (status, last four digits, expiry, design). Full PAN / CVV / PIN never available via the AI surface.
- get_card: Get detailed metadata for a single card (status, type, program, currency, expiry, design). Safe metadata only — no PAN/CVV/PIN.
- health: Check MCP server status.
- get_balance: Fetch live balances for USD, EUR, CHF, CAD and MXN accounts and earnings vaults. Includes sparkline trends and APY rates.
- get_lifetime_savings: See your lifetime savings from using Moneda — fees Moneda covered on your behalf plus your plan's discount versus Standard.
- get_transactions: Browse transaction history with filters for type, category, currency, dates, counterparty, amount, and status.
- get_spending_by_type_group: View spending grouped by transaction type group (transfer, deposit, etc.) over 7, 30, or 90 days. Includes period comparison. (Formerly get_spending_summary.)
- get_daily_spending: Get a daily series of spending totals for a stablecoin (USDC, EURC, CHFAU, CADD, MXNB) over a rolling window or absolute UTC range.
- get_spending_by_category: View spending grouped by user-assigned transaction category over a window.
- get_spending_by_contact: View total spending sent to a single recipient (Moneda user, bank, or wallet) over a window.
- get_spending_by_merchant: View spending grouped by recipient/merchant — per-user buckets plus per-type off-ramp buckets.
- get_spending_comparison: Compare spending totals across two arbitrary windows with absolute and percentage delta.
- get_spending_transactions: List or drill into the underlying spending transactions for a window or bucket.
- get_exchange_rate: Get the current USD/EUR exchange rate.
- get_apy_rates: Check APY rates for Morpho Earnings and YO Smart Earnings vaults.
- get_earnings_time_series: Get a daily time series of earnings and balance for a Morpho or YO vault account.
- get_dinari_capabilities: Check whether the user can trade tokenized equities (dShares), under which jurisdiction, and why not if they can't.
- get_dinari_us_requirements: List what a US-jurisdiction user still owes before their brokerage account can open. Field names only, never answers; disclosures are accepted in the app.
- get_market_status: Check whether the US stock market is open, which session is running, and when it next changes.
- get_free_trade_allowance: See how many commission-free stock trades are left in the current window and when it resets.
- get_wallet: Get the Moneda smart wallet address on Base (supports USDC, EURC, CHFAU, CADD, and MXNB only).
- get_virtual_accounts: View IBAN (EUR) and ACH (USD) virtual bank account details.
- get_virtual_account_limits: Remaining deposit/withdrawal limit on a rolling 52-week window, per direction, plus whether enhanced due diligence (EDD) is required. Crossing a limit pauses a transfer rather than rejecting it.
- get_settlement_estimate: The date a US bank (ACH) transfer settles, accounting for the 3:00 PM ET cutoff, weekends and US bank holidays.
- get_contacts: List saved Moneda contacts with wallet and bank account details.
- get_my_accounts: View saved external wallets and bank accounts used for withdrawals.
- get_settings: View app preferences including language, currency, theme, and notification settings.
- get_passkeys: List registered passkeys. target=WALLET (default) returns the wallet signing keys with kind (primary / backup) and onchainStatus; target=LOGIN returns the email-login credentials with a masked credential id. Does not report which key signs next (device-local preference).
- get_recovery_contacts: View recovery contacts and guardian relationships for social recovery.
- list_recovery_emails: List email addresses set up for ZK email-based account recovery.
- get_recovery_email: Get one recovery email's full detail by id.
- get_recovery_config: Get the recovery configuration (accepted recovery emails, total weight, threshold).
- get_recovery_status: Get the most recent ZK email recovery request snapshot for an account.
- list_notifications: List in-app notifications, newest first; pass filter='unread' for unread items.
- get_unread_notification_count: Get the unread in-app notification count; cheaper than list_notifications.
- get_points_balance: Check current reward points balance.
- get_points_activity: View history of earned and redeemed reward points.
- get_points_redemption_config: Read the points-to-AI-credit rate, minimum, monthly cap, current balance, and remaining monthly allowance. Requires read:points scope.
- get_referral_code: Get the unique referral link and referral count.
- get_referees: List friends referred to Moneda.
- search_users: Search Moneda users by username, display name, email, or phone number.
- search_knowledge: Search the Moneda FAQ knowledge base by keyword or question.
- get_faq_category: Browse all FAQ items in a specific help category.
- get_faq_item: Read the full answer to a specific FAQ question.
- get_current_subscription: Get the user's current plan and how it's billed (status, tier, ONCHAIN/STRIPE, and whether the wallet balance funds the next renewal).
- list_subscription_charges: List the user's subscription charge history, newest first (cursor-paginated with plan tier, period, amount, currency, status, on-chain hash, dates, and invoice number).
- get_subscription_invoice: Generate (idempotently) the ZUGFeRD plan invoice PDF for a charge and return a 1-hour presigned download URL.
- list_agent_sessions: List your scoped autonomous agent sessions with status, spending policy, remaining period cap, and expiry. Requires read:agent_sessions scope (not in default set).
- get_agent_session: Get one agent session's full detail by id, including recent executions; poll after create_agent_session until ACTIVE. Requires read:agent_sessions scope.
- list_active_sessions: List your active login sessions (signed-in devices and clients) and connected agents, with location and last-active time. Requires read:sessions scope.
- list_api_keys: List the API keys on the account — name, prefix, permissions, last use and expiry. Never returns the secret.
- get_account_overview_data: Fetch a complete account overview in one call (balances, recent transactions, APY rates) instead of several separate read tools.
- get_balance_check_data: Fetch a balance check in one call (balances, exchange rates, APY rates) instead of several separate read tools.
- get_financial_summary_data: Fetch a comprehensive financial summary in one call (balances, recent transactions, APY rates, exchange rates).
- get_my_accounts_data: Fetch all account setup in one call (wallet address, Moneda balances, virtual bank accounts, saved external accounts).
- get_earnings_overview_data: Fetch an earnings overview in one call (earnings vault balances, APY rates, recent earnings transactions).
- get_spending_analysis_data: Fetch a spending analysis in one call (spending by type group, daily totals, category breakdown for a period).
- get_card_overview_data: Fetch a card overview in one call (all cards and recent card transactions).
- get_points_rewards_data: Fetch points and referral data in one call (points balance, recent activity, referral code, referees).
- get_payment_readiness_data: Fetch a payment-readiness check in one call (KYC status, virtual accounts, external accounts, contact count, balances).
- get_security_checkup_data: Fetch a security checkup in one call (passkeys, recovery contacts, security-related settings).

### Write Tools
- update_display_name: Change the account display name.
- set_passkey_label: Give a passkey a nickname (max 40 characters; empty clears it back to the provider name).
- update_transaction_category: Assign a spending category (Groceries, Restaurants, Transport, etc.) to a transaction.
- add_transaction_note: Add or update a personal note on a transaction (max 140 characters).
- batch_update_transaction_categories: Assign spending categories to up to 25 transactions at once.
- batch_add_transaction_notes: Add notes to up to 25 transactions at once.
- add_wallet: Save an external crypto wallet address (must support USDC/EURC/CHFAU/CADD/MXNB on Base network).
- add_bank: Save a bank account for withdrawals (EU IBAN/SEPA or US ACH routing and account number).
- add_contact_external: Register an external contact with their name, country, and wallet or bank details.
- add_contact_moneda: Add a Moneda user to the contacts list by username.
- initiate_payment: Create a payment request to a Moneda user, external wallet, or bank account (requires biometric approval in the mobile app).
- get_payment_status: Check the current status of a pending payment request.
- pay_x402: Pay an x402 (HTTP 402 Payment Required) invoice to a wallet address with USDC or EURC (requires biometric approval in the mobile app).
- request_receipt_upload: Step 1 of 2 — get a presigned S3 PUT URL and curl command to stage a local receipt file (bytes never enter the conversation context).
- finalize_receipt_upload: Step 2 of 2 — after PUTting the file, run OCR + LLM extraction and attempt to auto-match to a transaction.
- import_receipt_from_url: Import a receipt directly from an https:// URL (SSRF-guarded — rejects private IPs and non-https).
- reparse_receipt: Re-run OCR / LLM extraction on an existing receipt; refuses deleted rows and rows without a stored file.
- freeze_card: Freeze a card on-chain via PausableCardGuard. Reversible, idempotent at storage level (fresh tx submitted on every call), never touches Monavate-side state. Requires write:cards scope.
- unfreeze_card: Unfreeze a card on-chain via PausableCardGuard. Reversible, idempotent at storage level (fresh tx submitted on every call). Requires write:cards scope.
- create_agent_session: Create a scoped autonomous payment session bound to the agent (single pinned recipient, per-payment + per-period caps). Returns a wallet address and an activation link the user approves with a passkey in the app. Does NOT activate by itself. Requires write:agent_sessions scope (not in default set).
- agent_execute_payment: Send a payment to an active session's pinned recipient within its on-chain limits, no per-payment approval. Idempotent. Capped by the funded wallet balance and the per-execution / per-period limits. Requires write:agent_sessions scope.
- revoke_agent_session: Revoke an agent session, halting all further execution on the backend; the user completes the on-chain uninstall in the app. Requires write:agent_sessions scope.
- terminate_session: Terminate one login session by id — the device is signed out immediately and cannot renew. Requires write:sessions scope (not in default set).
- create_api_key: Create an API key for a script, the CLI, or an integration. The secret is returned once and cannot be retrieved again; capped to the caller's own permissions and never valid for payments.
- revoke_api_key: Revoke an API key by id — it stops working on its next request.
- terminate_all_other_sessions: Terminate all your login sessions on other devices, keeping the current one; does not disconnect agent connections. Requires write:sessions scope.
- disconnect_connected_service: Disconnect a connected agent by id, revoking its access immediately. Requires write:sessions scope.
- purchase_usage_credits: Redeem a completed top-up payment to Moneda (by transaction hash) for prepaid AI usage credits. The amount is read from the confirmed payment, converted to USD budget, and granted once (idempotent on the hash). Requires write:usage_credits scope (not in default set).
- set_ai_usage_limit: Set or clear the monthly spend limit on AI usage credits — a USD cap on how much of the prepaid balance is consumed per calendar month (resets the 1st, UTC), or null for unlimited. Requires write:usage_credits scope (not in default set).
- redeem_points: Redeem Moneda Points for prepaid AI usage credits — spends points and grants the matching AI budget atomically, enforcing the minimum and monthly cap. Pass a stable requestId (uuid) to make a retry idempotent. Requires write:usage_credits scope (not in default set).

## Examples

### Check balance
```
User: "What's my balance?"
AI calls: get_balance()
Response: Your USD account has $1,250.00 and your EUR account has €830.50.
```

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

### Categorize transactions
```
User: "Categorize my last 10 uncategorized transactions"
AI calls: get_transactions({ hasCategory: false, limit: 10 })
AI calls: batch_update_transaction_categories({ items: [{ transactionHash: "0x...", category: "RESTAURANTS" }, ...] })
Response: Categorized 10 transactions across Restaurants, Transport, and Shopping.
```

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

## About Moneda

- [What is Moneda](https://docs.moneda.com/moneda/index): Overview of the self-custodial stablecoin wallet for USDC, EURC, CHFAU, CADD, and MXNB on Base.
- [Why Moneda](https://docs.moneda.com/moneda/why-moneda): Value proposition — self-custody, multi-currency, earnings, and AI integration.
- [Security](https://docs.moneda.com/moneda/security): Self-custodial architecture, passkey authentication, biometric approvals, and social recovery.
- [Download](https://docs.moneda.com/moneda/download): Get the Moneda app for iOS and Android.

## Changelog

- [Changelog](https://docs.moneda.com/changelog): Version history of the Moneda MCP server including new tools, resources, and improvements. Latest: v0.3.0 (March 2026) — enriched tools, safety annotations, and security hardening.

## Optional

- [llms-full.txt](https://docs.moneda.com/llms-full.txt): Complete documentation content in a single markdown file for full-context AI consumption.