# Moneda MCP

> Moneda is a self-custodial stablecoin wallet for USDC and EURC 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 and EURC
- 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).
- 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 and EUR accounts and earnings vaults. Includes sparkline trends and APY rates.
- 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) 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_wallet: Get the Moneda smart wallet address on Base (supports USDC and EURC only).
- get_virtual_accounts: View IBAN (EUR) and ACH (USD) virtual bank account details.
- 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 and authentication devices.
- 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_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.

### Write Tools
- update_display_name: Change the account display 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 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.
- 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.

## 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 and EURC 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.