Skip to main content

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.

Moneda exposes actions to AI agents through four distinct patterns, picked based on what the action requires the user to do. Knowing the pattern up-front lets your agent handle each tool response correctly and set the right user expectations. This is the technical reference. For a consumer-facing version, see Working with your AI assistant.
Every pattern preserves Moneda’s self-custody guarantee: the user’s passkey is the only thing that can authorise value movement. The patterns differ only in when and how the user is involved.

​
At a glance

PatternWhen to useWhat the tool returnsWhat your agent does
InstantPure server state, no signature neededFinal resultShow result. Done.
HITL approvalEach invocation needs explicit user consent{ paymentRequestId, status: "PENDING_APPROVAL" }Tell user to approve in app, poll status until terminal.
Claim-linkOne-time device-bound setup (passkey, on-chain install){ activationUrl, expiresAt }Render the URL or QR for the user to open. Poll status if applicable.
Smart SessionRecurring, agent-initiated, bounded by static policy(Setup returns a claim-link; subsequent executions are transparent)Set up once via claim-link; thereafter call execution tools directly.
Does the action need a signature/biometric?
├─ No → Instant
└─ Yes
   ├─ Per-invocation user consent? → HITL approval
   ├─ One-time setup, then no further user action? → Claim-link
   └─ Recurring, bounded by static policy? → Smart Session

​
Pattern 1: Instant write

Direct server-side mutation. No signature, no biometric, no on-chain transaction. The tool runs the change and returns the final result in the same response. Examples: update_display_name, update_transaction_category, add_transaction_note, add_contact_moneda, add_contact_external, add_wallet, add_bank, batch variants of the above. Tool response shape: 
{
  "success": true,
  "id": "..."
}
Agent behaviour: Show the result and continue. Don’t ask for further confirmation — the tool would have returned an error if anything was wrong, and these are reversible-by-the-user changes (categories can be re-categorised, contacts can be deleted, etc.). When NOT to use: If the action moves money, even a tiny amount, it’s not Pattern 1 — it’s HITL approval. Self-custody applies even to “small” payments.

​
Pattern 2: HITL approval (push notification + polling)

The user must explicitly approve each invocation. Used today for payments. Each call creates a server-side pending request, sends a push notification to the user’s phone, and returns immediately. The user approves (or rejects) in the Moneda app; your agent polls a status endpoint until it reaches a terminal state. Examples: initiate_payment, get_payment_status. Initiation response shape: 
{
  "paymentRequestId": "...",
  "status": "PENDING_APPROVAL",
  "expiresAt": "2026-05-14T10:05:00.000Z",
  "amount": "50.00",
  "currency": "EUR"
}
Status polling response shape: 
{
  "paymentRequestId": "...",
  "status": "COMPLETED",
  "transactionHash": "0x..."
}
Terminal states: COMPLETED, FAILED, EXPIRED, REJECTED. Agent behaviour:
  1. Call the initiation tool (e.g. initiate_payment).
  2. Tell the user a notification has been sent and what to do (e.g. “I’ve sent the payment request to your phone — approve it in the Moneda app”).
  3. Poll get_payment_status({ paymentRequestId }) periodically (every few seconds). Stop polling when the status is terminal or expiresAt passes.
  4. Tell the user the outcome.
Polling cadence. Moneda’s payment requests have a 5-minute TTL. Reasonable polling: every 3-5 seconds for the first minute, every 10-15 seconds after. Don’t poll faster than once per second; you’ll just hit rate limits. Why this pattern: value transfer is irreversible. The push-on-phone approval ensures the user is physically present, biometrically authenticated, and consciously authorising that specific payment.
For actions requiring a one-time device-bound ceremony — registering a new passkey, installing an on-chain Smart Session, accepting a recovery email — but where the user doesn’t need per-invocation approval afterwards. The tool creates a server-side pending claim and returns a short-lived signed URL. The user opens the URL in any browser; their synced passkey (iCloud Keychain, Google Password Manager, 1Password, etc.) signs the ceremony locally; the action completes atomically. Examples (designed): agent-mediated signup, scheduled-transaction activation, sub-account create. Status: signup is shipping; the others land alongside their respective backend features. Tool response shape: 
{
  "claimId": "...",
  "activationUrl": "https://onboard.moneda.com/?token=eyJhbG...",
  "expiresAt": "2026-05-15T10:00:00.000Z"
}
Agent behaviour:
  1. Call the initiation tool.
  2. Render the activationUrl to the user. On a desktop, render as a clickable link. On a phone, the URL itself works in any browser. If the user’s passkey lives on a different device than the one they’re chatting from, the browser-side WebAuthn ceremony will use cross-device assertion (QR + Bluetooth proximity to the phone) automatically — no extra implementation needed.
  3. Tell the user what they’re signing for, briefly. (“This will set up email-based account recovery using ada@example.com — open the link and confirm with your passkey.”)
  4. If the action has follow-on state (e.g. “schedule activated” → continue scheduling), poll a corresponding status tool. For one-shot actions (passkey enrolled, recovery email accepted), no polling is needed; the user will tell you when they’re done.
Why this pattern: browser + synced passkey covers most device-bound ceremonies without requiring the Moneda mobile app, dramatically lowering friction for users who connect to Moneda via an AI assistant before installing the mobile app. The one-time nature makes it suitable for setup but not for recurring authorisation (use Pattern 2 for that). Claim link in chat history. Treat the activationUrl as a single-use token — which it is. The 24-hour expiresAt and one-shot consumption bound the blast radius if the URL leaks. Don’t echo it back later in conversation; refresh by calling the initiation tool again if the user needs a new one.

​
Pattern 4: Smart Sessions (delegated autonomous execution)

For repeating actions that should run without user interaction, bounded by a static 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. Status: rolling out alongside scheduled transactions. The first user is the recurring transfer engine; future users include auto-rebalance, threshold-triggered conversion, and recurring vault contributions. Setup response shape (one-time): see Pattern 3 — Smart Session installation is itself a claim-link. Execution response shape (subsequent): 
{
  "scheduleId": "...",
  "status": "ACTIVE",
  "nextExecutionAt": "2026-06-01T08:00:00.000Z"
}
Agent behaviour:
  1. First time only: propose the standing instruction. Make the bounds explicit (“send €100 to your savings vault on the 1st of every month, capped at €1,200/year, expires 2027-05-14”). Initiate via the appropriate tool, render the resulting claim-link, wait for the user to install the session.
  2. From then on: 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 matters. Most fintechs cannot offer scoped agent delegation because they lack on-chain policy enforcement; the best they can do is server-side OAuth scopes with the custodian as trust root, which throws away self-custody. Moneda’s smart-account architecture means the bounds are enforced cryptographically: the worst a compromised agent can do is what the bounds allowed.

​
Detecting the pattern from a tool response

Your agent doesn’t need to know the pattern up-front for every tool — the response shape tells you what to do next.
Field presentPatternNext step
success: true (or terminal data)InstantShow result.
paymentRequestId + status: "PENDING_APPROVAL"HITLPoll get_payment_status.
claimId + activationUrlClaim-linkRender URL/QR.
scheduleId + status: "PENDING_INSTALL"Smart Session setup (claim-link sub-case)Render the included activationUrl.
scheduleId + status: "ACTIVE"Smart Session activeStanding instruction is live.
If a future tool response contains both paymentRequestId and activationUrl, treat it as claim-link first (the link is the user’s next action) and poll status afterwards. The patterns compose; they don’t conflict.

​
Forward-looking notes

The patterns above describe both what’s live today (Patterns 1 and 2) and what’s coming (Patterns 3 and 4 are designed and partially implemented; tools that use them will appear in Read Tools and Write Tools as they ship). Agents built today should be ready to handle all four — the response-shape detection above is forward-compatible. Internal documents that describe the implementation roadmap:
  • docs/agent-signup-spec.md — the canonical claim-link pattern, applied to signup.
  • docs/scheduled-transactions-spec.md — Smart Sessions architecture (PR #1818).
  • docs/agent-headless-parity.md — full pattern guide and parity gap inventory.
These live in the Moneda monorepo, not on this docs site.

​
Learn more

Working with your AI

The consumer-facing version of this page — what users will experience for each pattern.

Read tools

All Pattern 1 read operations available today.

Write tools

Pattern 1 instant writes plus Pattern 2 HITL payment initiation.

Scopes

OAuth permission scopes that gate access to tools.