> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moneda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write Tools

> Write MCP tools for payments, transaction categorization, contact management, receipts, card freeze/unfreeze, and account updates on Moneda

Write tools let your AI assistant make changes on your behalf. All write tools require the appropriate permissions, and **payments always require your explicit approval** in the Moneda mobile app.

## Profile

<AccordionGroup>
  <Accordion title="update_display_name">
    Change your display name shown to other Moneda users.

    **Try asking:** "Change my display name to Federico"
  </Accordion>
</AccordionGroup>

## Transaction annotations

<AccordionGroup>
  <Accordion title="update_transaction_category">
    Assign a spending category to a transaction (e.g. Groceries, Restaurants, Travel).

    **Try asking:** "Categorize my last coffee purchase as Restaurants"
  </Accordion>

  <Accordion title="add_transaction_note">
    Add or update a personal note on a transaction. Maximum 140 characters.

    **Try asking:** "Add a note to my last transaction: Birthday dinner with friends"
  </Accordion>

  <Accordion title="batch_update_transaction_categories">
    Assign spending categories to up to 25 transactions at once.

    **Try asking:** "Categorize all my uncategorized transactions from last week"
  </Accordion>

  <Accordion title="batch_add_transaction_notes">
    Add or update notes on up to 25 transactions at once.

    **Try asking:** "Add notes to my recent transactions"
  </Accordion>
</AccordionGroup>

## External accounts

<AccordionGroup>
  <Accordion title="add_wallet">
    Save an external crypto wallet to your account. The wallet must support USDC or EURC on the Base network. You'll be asked to confirm this before the wallet is saved.

    **Try asking:** "Save this wallet address: 0x..."
  </Accordion>

  <Accordion title="add_bank">
    Save a bank account for withdrawals. Supports EU bank accounts (IBAN) and US bank accounts (ACH routing + account number).

    **Try asking:** "Add my bank account"
  </Accordion>
</AccordionGroup>

## Contacts

<AccordionGroup>
  <Accordion title="add_contact_external">
    Register an external (non-Moneda) contact with their wallet address or bank account details. EU Travel Rule requires first name, last name, and country of residence.

    **Try asking:** "Add John as an external contact with his wallet address"
  </Accordion>

  <Accordion title="add_contact_moneda">
    Add a Moneda user to your contacts by their username.

    **Try asking:** "Add @alice to my contacts"
  </Accordion>
</AccordionGroup>

## Payments

<Warning>
  Payment requests created through MCP are sent to your Moneda mobile app, where you must approve them with biometric authentication. No money moves without your explicit confirmation.
</Warning>

<AccordionGroup>
  <Accordion title="initiate_payment">
    Create a payment request that requires your approval in the Moneda app. Supports transfers to Moneda users, your own external accounts, or contact bank accounts and wallets.

    **Try asking:** "Send \$50 to @alice" or "Transfer EUR 100 to my bank account"
  </Accordion>

  <Accordion title="get_payment_status">
    Check the current status of a pending payment request. Terminal statuses are: completed, failed, expired, or rejected.

    **Try asking:** "What's the status of my last payment?"
  </Accordion>

  <Accordion title="pay_x402">
    Pay an x402 (HTTP 402 Payment Required) invoice to a wallet address. When an API or service replies with HTTP 402, your AI assistant can pay it with USDC or EURC — requiring your approval in the Moneda app before it settles. Then it polls `get_payment_status` and retries the original request once paid.

    **Try asking:** "This API returned a 402 — pay the x402 invoice for me."
  </Accordion>
</AccordionGroup>

## Receipts

<AccordionGroup>
  <Accordion title="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. The file bytes go straight to S3 — never through the conversation context. Follow up with `finalize_receipt_upload`.

    **Try asking:** "I want to upload a receipt — what do I do?"
  </Accordion>

  <Accordion title="finalize_receipt_upload">
    Step 2 of 2 for uploading a local receipt file. Pass the upload key from `request_receipt_upload` after you've PUT the file to S3. Runs OCR + LLM extraction, attempts to auto-match to an existing transaction, and persists line items. Returns the receipt id, optional bill id (for invoices), and any matched/suggested transaction.

    **Try asking:** (used as a follow-up to `request_receipt_upload`)
  </Accordion>

  <Accordion title="import_receipt_from_url">
    Import a receipt directly from an `https://` URL (S3, Drive shared link, public file host). The server fetches the file behind an SSRF guard, validates it, then runs OCR + matching. Single tool call, no sandbox needed.

    **Try asking:** "Import this receipt from this URL"
  </Accordion>

  <Accordion title="reparse_receipt">
    Re-run the OCR / LLM extraction pipeline on an existing receipt and return the refreshed fields. Use when extraction looks wrong or after a model upgrade.

    **Try asking:** "Re-scan this receipt — the merchant looks wrong"
  </Accordion>
</AccordionGroup>

## Cards

<Warning>
  These tools require the `write:cards` scope, which is **not** in the default scope set. Your AI client has to ask for it explicitly when connecting.
</Warning>

<Info>
  Freeze/unfreeze are the **only** card-lifecycle operations available through MCP. They run on-chain via the Server-Safe-controlled `PausableCardGuard`, are fully reversible, idempotent, and never touch issuer-side card state. Destructive operations — suspend, terminate, replace, change PIN, reveal PIN, approve 3DS — stay mobile-app-only behind a fresh passkey assertion.
</Info>

<AccordionGroup>
  <Accordion title="freeze_card">
    Freeze a card on-chain. Settlement is blocked at the on-chain Roles Module level so no further spending lands until you unfreeze. Idempotent — re-freezing an already-frozen card succeeds without changing on-chain state (no spend, no double-block), though a fresh transaction is still submitted on every call. Returns a `CONFLICT` error if the card's on-chain proxy hasn't been deployed yet (you'll need to finish card setup in the mobile app first).

    **Try asking:** "Freeze my virtual card" or "Block spending on card ending 1234"
  </Accordion>

  <Accordion title="unfreeze_card">
    Unfreeze a card on-chain. Restores settlement. Idempotent — unfreezing an already-active card succeeds without changing on-chain state, though a fresh transaction is still submitted on every call.

    **Try asking:** "Unfreeze my virtual card" or "Re-enable spending on card ending 1234"
  </Accordion>
</AccordionGroup>

## Agent sessions

<Info>
  Agent sessions let you hand your AI a **bounded, autonomous spending mandate**: a single pinned recipient, a per-payment cap, and a per-period cap, enforced **on-chain** by a pre-funded dedicated wallet. The funded balance is the hard ceiling on worst-case loss and the recipient is fixed on-chain — the agent can never exceed the limits or redirect funds. These tools need the **Manage Agent Sessions** permission, which is **not granted by default** — you opt in at connection time.
</Info>

<AccordionGroup>
  <Accordion title="create_agent_session">
    Create a scoped autonomous session bound to your AI agent. You provide the recipient, currency, per-payment and per-period limits, and an optional expiry and funding amount. The tool returns a wallet address and an activation link. The session is **not active yet** — you open the activation link in the Moneda app and approve with your passkey to install the on-chain spending policy and fund the wallet. Only then can the agent pay within those limits.

    **Try asking:** "Set up an agent that can pay my landlord up to \$500/month"
  </Accordion>

  <Accordion title="agent_execute_payment">
    Send a payment to an active session's pinned recipient, within its on-chain limits — no per-payment approval. Rejected automatically if it would exceed the per-payment cap, the remaining period cap, or the funded balance. For safe retries, pass a stable idempotency key — retrying with the same key returns the original transaction instead of sending twice.

    **Try asking:** "Pay this month's rent from my landlord agent session"
  </Accordion>

  <Accordion title="revoke_agent_session">
    Revoke an agent session. This immediately stops all further payments through it. You finish the on-chain teardown in the Moneda app.

    **Try asking:** "Stop the landlord agent session"
  </Accordion>
</AccordionGroup>

## Usage credits

<Info>
  AI usage credits are prepaid budget for your AI assistant. You top up by sending a stablecoin payment to Moneda and then redeeming that completed payment for credits. This tool needs the **Purchase AI Usage Credits** permission, which is **not granted by default** — you opt in at connection time.
</Info>

<AccordionGroup>
  <Accordion title="purchase_usage_credits">
    Redeem a payment you already sent to Moneda for prepaid AI usage credits. You give the transaction hash of the completed top-up, and the amount is read straight from that confirmed payment, converted to your USD credit balance. The payment is already finished, so there's nothing more to approve — this just turns it into credits. Safe to call again with the same hash: credits are only ever granted once.

    **Try asking:** "I sent the credit payment, here's the transaction hash — add my AI credits."
  </Accordion>

  <Accordion title="set_ai_usage_limit">
    Set a monthly cap on how much of your prepaid AI credit balance can be spent, or remove the cap entirely. Give a US dollar amount to set the limit, or ask for no limit to make it unlimited. The cap resets at the start of each month. Setting the same value again does nothing.

    **Try asking:** "Cap my AI spending at \$50 a month." or "Remove my monthly AI spending limit."
  </Accordion>
</AccordionGroup>

## Learn more

<CardGroup cols={2}>
  <Card title="Read tools" icon="book-open" href="/tools/read-tools">
    Tools for querying balances, transactions, account data, recovery setup, notifications, vaults, receipts, bills, and card metadata.
  </Card>

  <Card title="Scopes" icon="list-check" href="/scopes">
    Permission scopes that control which tools your AI can use.
  </Card>
</CardGroup>