API Endpoints - Moneda Docs

The Moneda REST API endpoints are organized by domain. All endpoints use JSON request/response bodies and require an OAuth 2.0 Bearer token unless noted otherwise.

Write endpoints that involve money — like initiating payments — always require your confirmation in the Moneda app before anything happens.

Base URL

https://api.moneda.com/v1

All endpoints are prefixed with /v1. Include your Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.moneda.com/v1/balances

Response shape: `?view=full` vs `?view=lite`

Every GET /v1/* endpoint accepts an optional view query parameter that selects the response shape. This lets LLM agents and terminals consume a compact version of each response without dropping existing integrations.

`view`	Default	Use case
`full`	✅	Back-compat — every field the service exposes. Existing integrations keep working unchanged.
`lite`	—	Smaller response with optional metadata, coaching fields, derived counts, and empty/null optionals dropped. Designed for LLM agents and CLI rendering.

On a typical support-chatbot turn mix, ?view=lite reduces response payloads by ~20–80% per endpoint (see the per-endpoint notes below). The difference is most dramatic on /v1/wallet, /v1/virtual-accounts, and the balance snapshot-fallback path, where the full shape carries UI coaching text that an LLM reasoning about “how much do I have” doesn’t need.

lite is a strict subset of fields with two renames:

balances[].accountName → balances[].type (on /v1/balances, for semantic clarity)
points_activity[].createdAt → points_activity[].date

Empty arrays, empty objects, null, and "" are also dropped from the response body on every lite call — 0, false, and "0" are preserved (balance of zero is a real answer). This is a minor shape change on lite only; the full shape is unchanged. Example:

# Full (default)
curl https://api.moneda.com/v1/wallet -H "Authorization: Bearer $TOKEN"
# → {"smartAccountAddress":"0x...","network":"Base","supportedTokens":[...],
#    "username":"@alice","warning":"...","tip":"..."}

# Lite
curl 'https://api.moneda.com/v1/wallet?view=lite' -H "Authorization: Bearer $TOKEN"
# → {"smartAccountAddress":"0x...","username":"@alice"}

Routes whose response is already minimal (/v1/health, /v1/exchange-rates, /v1/points/balance, /v1/settings, knowledge search) ignore view because there’s nothing to trim.

Health

GET /v1/health

Server health check. No authentication required. Response

{
  "status": "ok",
  "uptime": 12345,
  "version": "1.0.0"
}

Balances & Finances

GET /v1/balances

Returns your account balances. Scope: read:balances Query parameters

Parameter	Type	Required	Description
`currency`	`USD` \| `EUR` \| `CHF`	No	Filter by currency
`view`	`full` \| `lite`	No	Response shape selector. Default `full`. See above.

Response (full)

{
  "source": "snapshot",
  "balances": [
    {
      "accountName": "USD Account",
      "currency": "USD",
      "type": "LOCAL",
      "balance": "1250.50"
    },
    {
      "accountName": "EUR Account",
      "currency": "EUR",
      "type": "LOCAL",
      "balance": "890.25"
    }
  ],
  "snapshotTimestamp": "2026-03-07T10:30:00.000Z",
  "snapshotAge": "2 minutes ago"
}

Response (?view=lite) Drops source, snapshotTimestamp, and notice. On the snapshot-fallback path only, collapses all 4 metadata fields to one optional stale field. Renames accountName → type per row.

{
  "balances": [
    { "currency": "USD", "type": "USD Account", "balance": "1250.50" },
    { "currency": "EUR", "type": "EUR Account", "balance": "890.25" }
  ],
  "stale": "2 minutes ago"
}

GET /v1/lifetime-savings

Returns your lifetime accumulated 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. Scope: read:balances Response

{
  "savings": 1234.56,
  "currencySymbol": "$"
}

GET /v1/transactions

Returns your transaction history with powerful filtering. Scope: read:transactions Query parameters

Parameter	Type	Required	Description
`currency`	`USD` \| `EUR` \| `CHF`	No	Filter by currency
`type`	string	No	Filter by exact transaction type (e.g. `TRANSFER`, `SWAP`)
`typeGroup`	string	No	Filter by group: `transfer`, `exchange`, `deposit`, `withdrawal`, `earnings`, `topup`, `offramp`
`category`	string	No	Filter by spending category (e.g. `GROCERIES`, `TRAVEL`)
`status`	`COMPLETED` \| `PENDING` \| `FAILED` \| `all`	No	Default: `COMPLETED` + `COMPLETED_DELAYED`. `all` to include every status.
`direction`	`incoming` \| `outgoing` \| `exchange`	No	Filter by transaction direction relative to the user
`counterparty`	string	No	Search by counterparty username, wallet name, address, or external provider
`transactionHash`	string	No	Exact hash lookup (with or without `0x` prefix, case-insensitive). Returns at most one row.
`search`	string	No	Free-text substring search over note + reference fields
`startDate`	ISO 8601	No	Filter from date
`endDate`	ISO 8601	No	Filter until date
`year`	number	No	Filter by year (overrides startDate/endDate)
`minAmount`	number	No	Minimum amount filter
`maxAmount`	number	No	Maximum amount filter
`hasNote`	`true` \| `false`	No	Filter by whether transactions have a note
`hasCategory`	`true` \| `false`	No	Filter by whether transactions have a category
`sort`	`newest` \| `oldest` \| `amount_desc` \| `amount_asc`	No	Default: `newest`
`limit`	number	No	Max 50, default 5
`offset`	number	No	Pagination offset
`view`	`full` \| `lite`	No	Response shape selector. Default `full`. See above.

Response (full)

{
  "data": [
    {
      "transactionHash": "0xabc...123",
      "typeGroup": "Transfers",
      "type": "TRANSFER",
      "category": "Friends & Family",
      "note": "Dinner split",
      "direction": "outgoing",
      "amount": "25.00",
      "currency": "USD",
      "status": "COMPLETED",
      "counterparty": {
        "type": "user",
        "username": "@alice"
      },
      "date": "2026-03-06T18:30:00.000Z",
      "signer": {
        "label": "YubiKey",
        "kind": "backup"
      }
    }
  ],
  "count": 1,
  "limit": 5,
  "offset": 0
}

signer names the passkey that approved the payment: label is the nickname (falling back to the provider name) and kind is primary or backup. It is absent on rows that no user signed — anything created before signer provenance was recorded, and every server-initiated movement such as an incoming deposit, a scheduled transfer, an on-ramp, or a card settlement. Absent means “no user signature on file”, not “an unrecognised key”.

Exchange transactions include additional fields:

{
  "direction": "exchange",
  "amount": "0",
  "exchanged": "100.00",
  "exchangedCurrency": "USD",
  "received": "92.15",
  "receivedCurrency": "EUR"
}

Counterparty types

Type	Fields	Description
`self`	—	Self-transfer (swap, deposit, withdrawal)
`user`	`username`	Moneda user
`provider`	`name`	Service provider (Coinbase, etc.)
`bank`	`name`, `iban`, `account`, `routing`	Bank transfer
`wallet`	`name`, `address`	External wallet
`unknown`	`address`	Unknown source

Response (?view=lite) Drops typeGroup, type, category, note, reference, exchanged*, received*, and counterparty raw address/iban/account/routing (already masked, still unused by LLM agents). Keeps hash, direction, amount, currency, status, date, and the trimmed counterparty. Per row ≈40–50 % smaller.

{
  "data": [
    {
      "hash": "0xabc...123",
      "direction": "outgoing",
      "amount": "25.00",
      "currency": "USD",
      "status": "COMPLETED",
      "date": "2026-03-06T18:30:00.000Z",
      "counterparty": { "type": "user", "username": "@alice" }
    }
  ],
  "count": 1,
  "limit": 5,
  "offset": 0
}

GET /v1/transactions/{hash}

Single-resource lookup by transaction hash. Scope: read:transactions Path parameters

Parameter	Type	Description
`hash`	string	Transaction hash (with or without `0x` prefix, case-insensitive)

Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`. Pass `lite` for the compact shape when you don’t need typeGroup/category/note/reference/raw routing.

Returns a single transaction (same shape as the list items above). 404 if not found or not owned by this user.

GET /v1/spending/by-type-group

Spending grouped by transaction type group (formerly /v1/spending/summary). Scope: read:spending Query parameters

Parameter	Type	Required	Description
`period`	`7d` \| `30d` \| `90d`	No	Default: `30d`
`currency`	`USD` \| `EUR`	No	Filter by currency

Response

{
  "period": "30d",
  "since": "2026-02-05T00:00:00.000Z",
  "typeGroups": [
    {
      "typeGroup": "transfer",
      "name": "Transfers",
      "count": 12,
      "total": "450.00"
    }
  ],
  "totalSpent": "1250.00",
  "transactionCount": 28
}

GET /v1/spending/by-category

Spending grouped by user-assigned category (Groceries, Restaurants, Transport, etc.). Transactions without a category land in an UNCATEGORIZED bucket. Scope: read:spending Query parameters

Parameter	Type	Required	Description
`period`	`7d` \| `30d` \| `90d`	No	Default: `30d`
`currency`	`USD` \| `EUR`	No	Filter by currency

GET /v1/spending/by-contact

Total amount sent to a single recipient (Moneda user, external bank, or external wallet) over a window. Scope: read:spending Query parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Recipient account id (from `/v1/contacts` or `/v1/accounts`)
`period`	`7d` \| `30d` \| `90d`	No	Default: `30d`
`currency`	`USD` \| `EUR`	No	Filter by currency

GET /v1/spending/by-merchant

Spending grouped by recipient. Each Moneda user gets their own bucket; off-ramps share one bucket per type (bank-withdrawal, external-wallet, coinbase, wallet-connect). Scope: read:spending Query parameters

Parameter	Type	Required	Description
`period`	`7d` \| `30d` \| `90d`	No	Default: `30d`
`currency`	`USD` \| `EUR`	No	Filter by currency

GET /v1/spending/comparison

Compare spending totals across two arbitrary windows (e.g. this month vs. last month) with absolute and percentage delta. Scope: read:spending Query parameters

Parameter	Type	Required	Description
`currentFrom`	ISO date	Yes	Start of the current period (UTC)
`currentTo`	ISO date	Yes	End of the current period (UTC)
`previousFrom`	ISO date	Yes	Start of the comparison period (UTC)
`previousTo`	ISO date	Yes	End of the comparison period (UTC)
`currency`	`USD` \| `EUR`	No	Filter by currency

GET /v1/spending/daily

Daily spending totals for a stablecoin over a rolling window or absolute UTC range. Scope: read:spending Query parameters

Parameter	Type	Required	Description
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD`	Yes	Token to chart
`window`	`1d` \| `1w` \| `1m` \| `1y`	No	Rolling window from now (mutually exclusive with `from`/`to`)
`from`	ISO date	No	Absolute window start (UTC)
`to`	ISO date	No	Absolute window end (UTC)

GET /v1/spending/transactions

List the underlying transactions for a spending window (or a category/merchant bucket). Used to drill into a spending breakdown. Scope: read:spending Query parameters

Parameter	Type	Required	Description
`period`	`7d` \| `30d` \| `90d`	No	Default: `30d`
`currency`	`USD` \| `EUR`	No	Filter by currency
`category`	string	No	Drill into one category bucket
`accountId`	string	No	Drill into one merchant/recipient bucket

GET /v1/exchange-rates

Current USD/EUR exchange rate. Scope: read:rates Query parameters

Parameter	Type	Required	Description
`from`	`USD` \| `EUR`	No	Default: `USD`
`to`	`USD` \| `EUR`	No	Default: `EUR`

Response

{
  "from": "USD",
  "to": "EUR",
  "rate": "0.9215",
  "updatedAt": "2026-03-07T10:00:00.000Z"
}

GET /v1/apy-rates

Current earnings APY rates. Scope: read:earnings Query parameters

Parameter	Type	Required	Description
`currency`	`USD` \| `EUR`	No	Filter by currency

Response

[
  {
    "product": "Morpho USDC Vault",
    "currency": "USD",
    "apyPercent": "4.25",
    "updatedAt": "2026-03-07T00:00:00.000Z"
  }
]

GET /v1/dinari/capabilities

What the user may currently do with tokenized equities (dShares). Scope: read:account Response

{
  "jurisdiction": "US",
  "canTrade": false,
  "canTradeRestrictedAssets": false,
  "canWrap": false,
  "canUseDefi": false,
  "requiresNbboQuote": true,
  "quoteMaxAgeSeconds": 15,
  "requiresDedicatedWallet": true,
  "settlementStablecoins": ["USDC"],
  "maxOrderNotionalUsd": null,
  "blockedReasons": ["dinari_us_onboarding_incomplete", "dinari_kyc_not_approved"]
}

blockedReasons is ordered — render the first entry as the next thing the user should fix. It is empty if and only if canTrade is true.

GET /v1/dinari/us/requirements

What a US-jurisdiction user still owes before their brokerage KYC can be submitted. Scope: read:account Returns field names and counts only — never the user’s answers. A non-US user gets isUsCustomer: false and an empty, already-complete requirement set. Response

{
  "jurisdiction": "US",
  "isUsCustomer": true,
  "canTrade": false,
  "blockedReasons": ["dinari_us_onboarding_incomplete"],
  "consentVersion": "2026-07-28",
  "agentCollectableFields": ["countryOfBirth", "investibleAssets"],
  "handoffRequiredSteps": [
    "Accept the remaining brokerage disclosures in the app",
    "Enter the taxpayer id (SSN or ITIN) in the app"
  ],
  "onboardingPath": "/(protected)/(app)/kyc/(dinari-us)",
  "isComplete": false,
  "requirements": {
    "missingProfileFields": ["countryOfBirth", "investibleAssets"],
    "missingConsentKeys": ["BROKERAGE_AGREEMENT"],
    "missingRiskFormFields": [],
    "missingTaxId": true,
    "isComplete": false
  }
}

There is no write counterpart to this endpoint, by design. The US profile answers and the ten regulatory disclosures are completed by the user in the Moneda app: a consent recorded without the user having personally seen the verbatim document is not a consent, and the row carries an IP and timestamp that a broker-dealer treats as a signature. Use this endpoint to explain what is outstanding and send the user to onboardingPath.

GET /v1/dinari/market-hours

The US equity session clock. No scope required: this is the public exchange calendar and carries no account data. Response

{
  "session": "open",
  "open": true,
  "etDate": "2026-07-14",
  "tradingDay": true,
  "holiday": null,
  "cycleEtDate": "2026-07-14",
  "earlyClose": false,
  "windows": [
    { "session": "pre_market", "start": "2026-07-14T08:00:00.000Z", "end": "2026-07-14T13:30:00.000Z" },
    { "session": "open", "start": "2026-07-14T13:30:00.000Z", "end": "2026-07-14T20:00:00.000Z" },
    { "session": "after_hours", "start": "2026-07-14T20:00:00.000Z", "end": "2026-07-15T00:00:00.000Z" },
    { "session": "closed", "start": "2026-07-15T00:00:00.000Z", "end": "2026-07-15T08:00:00.000Z" }
  ],
  "nextTransition": { "session": "after_hours", "at": "2026-07-14T20:00:00.000Z" }
}

windows are ISO instants for the trading day named by cycleEtDate. On a weekend or holiday that is the next trading day, so there is always a concrete cycle to show. Render the instants in the reader’s own timezone.

GET /v1/dinari/orders/free-trade-allowance

Commission-free stock trades left in the current window, without quoting an order. Scope: read:account Response

{
  "limit": 1,
  "used": 1,
  "remaining": 0,
  "resetsAt": "2026-08-28T09:14:00.000Z",
  "degraded": false,
  "upgrade": { "planType": "PREMIUM", "freeTradesPerMonth": 5 }
}

The window steps from the customer’s own subscription anniversary, clamped on short months. It does not reset on the 1st, so quote resetsAt rather than a day of the month. degraded: true means the count could not be read and the values are a fail-open default. Say so; do not present them as fact. upgrade is populated only once the allowance is spent, and names the cheapest higher plan whose allowance would still have covered this window.

GET /v1/earnings/time-series

Daily time series of earnings and balance for a Morpho or YO vault account, used for charting yield over time. Scope: read:earnings Query parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Vault account id
`window`	`1w` \| `1m` \| `3m` \| `1y`	No	Default: `1m`

Response

{
  "accountId": "acc_…",
  "window": "1m",
  "points": [
    { "date": "2026-04-14", "balance": "1000.00", "earned": "0.12" }
  ]
}

Account Info

GET /v1/wallet

Your smart wallet address on Base. Scope: read:account Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`. `lite` drops `network`, `supportedTokens`, `warning`, `tip`.

Response (full)

{
  "smartAccountAddress": "0x1234...abcd",
  "network": "Base",
  "supportedTokens": ["USDC", "EURC", "CHFAU", "CADD"],
  "username": "@john",
  "warning": "Never send tokens on other networks to this address.",
  "tip": "This is your Base smart account address. Only send USDC, EURC, CHFAU, CADD or MXNB on the Base network."
}

Response (?view=lite) — ~76% smaller

{ "smartAccountAddress": "0x1234...abcd", "username": "@john" }

GET /v1/virtual-accounts

IBAN and ACH virtual account details for receiving transfers. Scope: read:virtual_accounts Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`. `lite` drops `capabilityInfo`, `minimumTransfer`, `firstPartyPayments`, `thirdPartyPayments`, and the per-account `type` discriminator.

Response (full)

{
  "status": "active",
  "accounts": {
    "eur": {
      "type": "IBAN",
      "iban": "DE89370400440532013000",
      "minimumTransfer": "1.00"
    },
    "usd": {
      "type": "ACH",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "minimumTransfer": "1.00"
    }
  }
}

Status can be active, pending, or not_registered. Response (?view=lite) — ~78% smaller

{
  "status": "active",
  "accounts": {
    "eur": { "iban": "DE89370400440532013000" },
    "usd": { "accountNumber": "1234567890", "routingNumber": "021000021" }
  }
}

GET /v1/virtual-accounts/limits

Remaining spending limit per direction on a rolling 52-week window, plus enhanced-due-diligence (EDD) status. Scope: read:virtual_accounts Crossing a limit does not reject a transfer — the banking partner pauses it and gives the user 24 hours to supply a Source-of-Wealth document before it is returned. Check this before proposing a large deposit or withdrawal. Response

{
  "limits": [
    {
      "direction": "deposit",
      "currency": "EUR",
      "used": 10000,
      "threshold": 27000,
      "remaining": 17000,
      "periodStart": "2026-01-01T00:00:00Z",
      "periodEnd": "2026-08-07T00:00:00Z"
    },
    {
      "direction": "withdrawal",
      "currency": "EUR",
      "used": 2500,
      "threshold": 27000,
      "remaining": 24500,
      "periodStart": "2026-01-01T00:00:00Z",
      "periodEnd": "2026-08-07T00:00:00Z"
    }
  ],
  "eddRequired": false,
  "eddSubmitted": false,
  "isReVerification": true,
  "ironStatus": "Active"
}

threshold: null means the customer has no enforced cap — not that the value is unknown. Limits are per direction and are not a combined budget: a customer may use their full limit on deposits and on withdrawals in the same window. Thresholds are personalised per customer (derived from declared income), so never hard-code one — always read it here.

GET /v1/virtual-accounts/settlement-estimate

The date a US bank (ACH) transfer settles. Scope: read:virtual_accounts Accounts for the 3:00 PM ET same-day cutoff, weekends, and US federal bank holidays — a transfer sent the afternoon before Thanksgiving does not arrive the next day. USD/ACH only; no equivalent published cutoff exists for EUR/SEPA. Query parameters

Parameter	Type	Required	Description
`submittedAt`	ISO timestamp	No	When the transfer was submitted. Omit to estimate for a transfer sent right now.

Response

{
  "sameBusinessDay": false,
  "settlesOn": "2026-11-27",
  "delayedByHoliday": true
}

settlesOn is a calendar date in the bank’s timezone (ET). delayedByHoliday is true when a bank holiday, not merely a weekend, pushed the date out.

GET /v1/accounts

Your saved external wallets and bank accounts. Scope: read:external_accounts Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`. `lite` drops `walletCount`, `bankCount`, wallet `address`, wallet `provider`.

Response (full)

{
  "wallets": [
    {
      "accountId": "acc_123",
      "name": "MetaMask",
      "address": "0xabcd...1234",
      "provider": "EXTERNAL"
    }
  ],
  "bankAccounts": [
    {
      "id": "bank_456",
      "holderName": "John Doe",
      "bankName": "Deutsche Bank",
      "iban": "DE89****3000",
      "country": "DE"
    }
  ],
  "walletCount": 1,
  "bankCount": 1
}

GET /v1/contacts

Your saved contacts (Moneda users, external wallets, and bank accounts). Scope: read:contacts Query parameters

Parameter	Type	Required	Description
`search`	string	No	Search by name, username, or address
`limit`	number	No	Max results
`offset`	number	No	Pagination offset

Response

{
  "monedaContacts": [
    {
      "type": "user",
      "username": "@alice",
      "displayName": "Alice Smith",
      "isExternal": false,
      "lastInteraction": "2026-03-06T12:00:00.000Z"
    }
  ],
  "walletContacts": [
    {
      "type": "wallet",
      "contactAccountId": "acc_789",
      "name": "Alice's MetaMask",
      "address": "0xdef...5678"
    }
  ],
  "bankContacts": [
    {
      "type": "bank",
      "contactAccountId": "acc_012",
      "name": "Alice's Bank",
      "bankName": "N26",
      "iban": "DE89****3000",
      "country": "DE"
    }
  ],
  "monedaUsers": 1,
  "wallets": 1,
  "bankAccounts": 1
}

GET /v1/settings

Your app preferences. Scope: read:settings Response

{
  "language": "en",
  "currency": "USD",
  "country": "US",
  "phone": "+1****7890",
  "phoneCountryCode": "+1",
  "theme": "LIGHT",
  "notifications": {
    "email": true,
    "inApp": true
  },
  "biometrics": true,
  "animations": true,
  "decimalSeparator": "DOT",
  "hideBalances": false
}

GET /v1/passkeys

Your authentication passkeys. Scope: read:passkeys Query

Param	Description
`target`	`WALLET` (default) lists your smart-account signing keys. `LOGIN` lists your email-login credentials. Pass the returned `target` straight back to `PATCH /v1/passkeys/{id}/label`.
`view`	`lite` drops the count envelope and the fields an agent can’t act on.

Response (target=WALLET) kind tells a backup apart from the key you signed up with, and onchainStatus says whether it can actually sign yet: a pending backup is registered but its add-owner transaction has not confirmed.

{
  "passkeys": [
    {
      "id": "b1e4c2f0-1111-2222-3333-444455556666",
      "target": "WALLET",
      "label": "Work laptop",
      "provider": "iCloud Keychain",
      "status": "active",
      "address": "0x12...ab",
      "kind": "primary",
      "onchainStatus": "active",
      "createdAt": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "c2f5d3a1-2222-3333-4444-555566667777",
      "target": "WALLET",
      "label": "YubiKey",
      "provider": "Hardware Key (YubiKey, etc.)",
      "status": "active",
      "address": "0x12...ab",
      "kind": "backup",
      "onchainStatus": "pending",
      "createdAt": "2026-03-02T10:00:00.000Z"
    }
  ],
  "count": 2
}

Response (target=LOGIN) The credential id is masked and the public key is never returned.

{
  "passkeys": [
    {
      "id": "d3a6e4b2-3333-4444-5555-666677778888",
      "target": "LOGIN",
      "label": null,
      "status": "active",
      "credentialId": "AAAABB...FFGGGG",
      "device": "Mozilla/5.0 (Macintosh)",
      "lastUsedAt": "2026-07-01T08:30:00.000Z",
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "count": 1
}

This endpoint reports which keys exist, not which one signs next. The preferred signing key is chosen on the user’s own device and is never stored server-side, so no API can report it. Don’t infer it from kind or ordering.

PATCH /v1/passkeys/{id}/label

Rename one of your passkeys. Scope: write:profile Cosmetic only — it cannot add, remove, or weaken a credential. Use the id from GET /v1/passkeys. target is WALLET for a smart-account passkey or LOGIN for an email login passkey. A null or empty label clears the nickname so the derived provider name is shown again. Labels are capped at 40 characters and are not required to be unique. Body

{
  "target": "WALLET",
  "label": "Work laptop"
}

Response

{
  "id": "b1e4c2f0-1111-2222-3333-444455556666",
  "label": "Work laptop"
}

Returns 404 when the id does not belong to you.

GET /v1/recovery-contacts

Your recovery guardians. Scope: read:recovery Response

{
  "myContacts": [
    {
      "username": "@alice",
      "displayName": "Alice Smith",
      "imageUrl": null,
      "status": "accepted",
      "addedAt": "2026-02-01T10:00:00.000Z"
    }
  ],
  "myContactsCount": 1,
  "recoveryContactOf": [
    {
      "username": "@bob",
      "displayName": "Bob Jones",
      "imageUrl": null,
      "status": "accepted",
      "addedAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "recoveryContactOfCount": 1
}

Recovery emails (ZK email recovery)

The recovery-emails endpoints surface the email addresses set up for ZK email-based account recovery. Mutations (invite, accept, recover) require a passkey-signed UserOp from the mobile app and are not exposed over REST. All four endpoints share the read:recovery scope and accept an optional accountId query parameter — when omitted, the call defaults to the authenticated user’s main LOCAL account.

GET /v1/recovery-emails

List recovery emails set up for the account. Query parameters

Parameter	Type	Required	Description
`accountId`	UUID	No	Defaults to the user’s main LOCAL account.
`view`	`full` \| `lite`	No	Default `full`. `lite` drops `notes` and irrelevant timestamps.

Response

{
  "recoveryEmails": [
    {
      "id": "g-abc123",
      "email": "alice@example.com",
      "weight": 100,
      "status": "accepted",
      "invitedAt": "2026-01-01T00:00:00.000Z",
      "acceptedAt": "2026-01-02T00:00:00.000Z",
      "declinedAt": null,
      "removedAt": null,
      "notes": null
    }
  ],
  "count": 1
}

When no recovery emails are configured, the response includes a friendly message field instead of an empty array.

GET /v1/recovery-emails/{id}

Single recovery email lookup by id. 404 if not found or not owned by this user (unified to prevent existence leakage). Path parameters

Parameter	Type	Description
`id`	UUID	Recovery email id (`zkRecoveryGuardian.id`)

Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`.

Returns the same shape as the list rows, plus the on-chain accountAddress the email protects.

GET /v1/recovery-config

Recovery configuration for an account: accepted recovery emails, total weight, and the threshold required to approve a recovery. Query parameters

Parameter	Type	Required	Description
`accountId`	UUID	No	Defaults to the user’s main LOCAL account.
`view`	`full` \| `lite`	No	Default `full`. `lite` adds `fullySet: boolean` and drops `accountAddress` + per-row `id` / `acceptedAt`.

Response

{
  "accountAddress": "0x1234...abcd",
  "recoveryEmails": [
    {
      "id": "g-abc123",
      "email": "alice@example.com",
      "weight": 100,
      "acceptedAt": "2026-01-02T00:00:00.000Z"
    }
  ],
  "totalWeight": 100,
  "threshold": 100
}

The threshold is a fixed value (currently 100) that must match the on-chain Universal Email Recovery Module configuration. Recovery is approvable when totalWeight >= threshold.

GET /v1/recovery-status

Most recent recovery request snapshot for the account. Reads from the database only — agents tolerate the slight lag while the cron job syncs on-chain state. The mobile app additionally polls on-chain. Query parameters

Parameter	Type	Required	Description
`accountId`	UUID	No	Defaults to the user’s main LOCAL account.
`view`	`full` \| `lite`	No	Default `full`.

Response (no recovery in flight)

{ "hasActiveRecovery": false }

Response (recovery in flight)

{
  "hasActiveRecovery": true,
  "recovery": {
    "id": "r-xyz789",
    "status": "threshold_met",
    "createdAt": "2026-04-01T00:00:00.000Z",
    "executeAfter": "2026-04-02T00:00:00.000Z",
    "executeBefore": "2026-04-09T00:00:00.000Z",
    "threshold": 100,
    "totalRecoveryEmails": 1,
    "approvedCount": 1,
    "approvedWeight": 100,
    "approvedBy": [
      { "email": "a***@example.com", "weight": 100, "approvedAt": "2026-04-01T01:00:00.000Z" }
    ],
    "pending": [],
    "isExecutable": true,
    "timeUntilExecutable": 0,
    "cancelledAt": null,
    "completedAt": null,
    "expiredAt": null
  }
}

hasActiveRecovery is true only for the active states (initiated, threshold_met, executing); terminal states (cancelled, completed, expired, failed) flip it back to false while the latest recovery details are still returned for context. Recovery email addresses are anonymized to first-letter***@domain in the active payload.

Notifications

GET /v1/notifications

Paginated in-app notifications inbox, newest first. Scope: read:notifications Query parameters

Parameter	Type	Required	Description
`cursor`	UUID	No	Id of the last notification from the previous page.
`limit`	number	No	Page size, max 50, default 20.
`filter`	`all` \| `unread`	No	Default `all`. Pass `unread` to scope to unread items.

Response

{
  "notifications": [
    {
      "id": "n-abc123",
      "type": "TRANSFER_RECEIVED",
      "deepLink": "moneda://tx/0xabc",
      "metadata": { "amount": "100", "currency": "USD" },
      "isRead": false,
      "createdAt": "2026-04-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "n-abc123"
}

nextCursor is omitted on the last page. metadata shape varies by type — agents should treat it as opaque unless they recognise the type. Mark-as-read / dismiss / clear-all are tied to the active mobile push session and stay in tRPC; the REST surface is read-only.

GET /v1/notifications/unread-count

Unread notification count. Scope: read:notifications Response

{ "count": 7 }

Sub-accounts (vaults)

Sub-accounts (a.k.a. vaults) are nested Safe smart accounts owned by your main account. The endpoints below are read-only — vault create / top-up / withdraw / freeze / close all require a passkey-signed UserOp from the mobile app. All endpoints require the read:sub_accounts scope.

GET /v1/sub-accounts

List the user’s sub-accounts. Query parameters

Parameter	Type	Required	Description
`includeClosed`	boolean	No	Default `false`. Pass `true` to include archived vaults.
`view`	`full` \| `lite`	No	Default `full`.

Response

{
  "subAccounts": [
    {
      "id": "sa-abc123",
      "name": "Travel fund",
      "status": "ACTIVE",
      "type": "VAULT",
      "address": "0xchild...safe",
      "createdAt": "2026-02-01T10:00:00.000Z"
    }
  ]
}

GET /v1/sub-accounts/{id}

Single sub-account detail by id. Path parameters

Parameter	Type	Description
`id`	UUID	Sub-account id

Returns the full sub-account shape including parent + child Safe addresses, members, deployment index, and close timestamp.

GET /v1/sub-accounts/{id}/balance

On-chain balances for a sub-account’s child Safe. Path parameters

Parameter	Type	Description
`id`	UUID	Sub-account id

Query parameters

Parameter	Type	Required	Description
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD`	No	Filter to a single token. Omit for every enabled currency.
`view`	`full` \| `lite`	No	Default `full`.

Balances are returned as raw bigint strings (6 decimals).

GET /v1/wealth

Aggregate wealth across the main account + every live vault. Scope: read:balances + read:sub_accounts. Query parameters

Parameter	Type	Required	Description
`view`	`full` \| `lite`	No	Default `full`.

Returns per-leg breakdown (wallet + Morpho + YO for the main account; wallet-only for vaults) plus per-currency totals. USDC and EURC are cross-converted using the on-chain Aerodrome rate.

Sessions

API key authentication produces sessions tracked in the database for audit trails. Bearer-token (OAuth) requests don’t create sessions.

POST /v1/sessions

Create a session record (typically called by clients that hold long-lived API keys). Scope: depends on the calling channel. Request body

{
  "deviceName": "moneda-cli",
  "platform": "darwin"
}

Response

{
  "sessionId": "ses_abc123",
  "createdAt": "2026-04-01T00:00:00.000Z"
}

DELETE /v1/sessions/{sessionId}

End a session. Path parameters

Parameter	Type	Description
`sessionId`	UUID	Session id from the create response

Returns 204 No Content on success.

GET /v1/sessions/active

List active login sessions and connected agents (third-party services). Scope: read:sessions Response

{
  "loginSessions": [
    {
      "id": "ses_abc123",
      "type": "MOBILE",
      "device": "iPhone 15",
      "appVersion": "1.3.26",
      "city": "Berlin",
      "countryCode": "DE",
      "lastActive": "2026-04-01T00:00:00.000Z"
    }
  ],
  "connectedAgents": [
    {
      "id": "svc_abc123",
      "name": "Claude",
      "enabled": true,
      "connectedAt": "2026-04-01T00:00:00.000Z",
      "lastActive": "2026-04-01T00:00:00.000Z"
    }
  ]
}

DELETE /v1/sessions/active/{sessionId}

Terminate a specific active session. Scope: write:sessions Path parameters

Parameter	Type	Description
`sessionId`	UUID	Session id from `GET /v1/sessions/active`

Response

{
  "success": true
}

POST /v1/sessions/revoke-all

Terminate all other active sessions, keeping the caller’s current session. Scope: write:sessions Response

{
  "revoked": 3
}

Points & Referrals

GET /v1/points/balance

Your points balance. Scope: read:points Response

{
  "totalPoints": 1500
}

GET /v1/points/activity

Points earning history. Scope: read:points Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Max results
`offset`	number	No	Pagination offset

Response

{
  "data": [
    {
      "actionType": "REFERRAL_BONUS",
      "points": 500,
      "description": "Referred a friend",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}

GET /v1/points/redemption-config

Config for redeeming points into AI credits: the points-per-$1 rate, the minimum redemption, the monthly cap, your current balance, and how much monthly allowance is left. Scope: read:points Response

{
  "pointsPerCreditUsd": 500,
  "minPoints": 100,
  "monthlyCapUsd": "20.00",
  "estMessageUsd": 0.05,
  "totalPoints": 1500,
  "monthlyRedeemedUsd": "0.00",
  "monthlyRemainingUsd": "20.00",
  "monthlyResetsAt": "2026-08-01T00:00:00.000Z"
}

POST /v1/points/redeem

Redeem Moneda Points for prepaid AI usage credits. Spends points and grants the matching AI budget atomically, enforcing the minimum, sufficient-balance, and monthly-cap checks. Scope: write:usage_credits Body

Field	Type	Required	Description
`points`	number	Yes	How many points to redeem
`requestId`	string (uuid)	No	Idempotency key — reuse to make a retry a no-op; omit to mint one

Response

{
  "granted": true,
  "pointsRedeemed": 500,
  "budgetUsd": "1.00",
  "paidBalanceEur": "1.80",
  "totalPoints": 1000,
  "creditBalanceUsd": "1.00"
}

GET /v1/referrals/code

Your referral link and stats. Scope: read:referrals

The referral code is derived from your account (<username>-<id-prefix>). Set a username first — the code is unavailable until you do.

Response

{
  "code": "alice-fc17d96c",
  "link": "https://moneda.com/?grsf=alice-fc17d96c",
  "referralCount": 5
}

GET /v1/referrals/referees

Friends you’ve referred. Scope: read:referrals Response

{
  "referees": [
    {
      "name": "Alice",
      "email": "",
      "status": "referred",
      "referredAt": "2026-02-20T10:00:00.000Z"
    }
  ],
  "count": 1
}

Knowledge Base

These endpoints are public — no authentication required.

GET /v1/knowledge/search

Search the FAQ knowledge base. Query parameters

Parameter	Type	Required	Description
`query`	string	No	Search query
`category`	string	No	Filter by category slug
`limit`	number	No	Max results

Response

{
  "query": "transfer fees",
  "totalMatches": 3,
  "returned": 3,
  "results": [
    {
      "id": "faq_001",
      "question": "Are there fees for transfers?",
      "answer": "Moneda does not charge fees for transfers between Moneda users...",
      "category": "Transfers"
    }
  ]
}

GET /v1/knowledge/categories/

Browse a FAQ category by slug. Path parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Category slug (e.g. `transfers`, `security`)

Response

{
  "category": "Transfers",
  "slug": "transfers",
  "itemCount": 8,
  "items": [
    {
      "id": "faq_001",
      "question": "Are there fees for transfers?",
      "answer": "...",
      "category": "Transfers"
    }
  ]
}

GET /v1/knowledge/items/

Get a specific FAQ item. Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	FAQ item ID

Response

{
  "id": "faq_001",
  "question": "Are there fees for transfers?",
  "answer": "Moneda does not charge fees for transfers between Moneda users...",
  "category": "Transfers",
  "categorySlug": "transfers",
  "relatedItems": [
    {
      "id": "faq_002",
      "question": "How long do transfers take?",
      "category": "Transfers"
    }
  ]
}

Users

GET /v1/users/search

Search Moneda users by username or display name. Scope: read:users Query parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query

Response

{
  "users": [
    {
      "username": "@alice",
      "displayName": "Alice Smith"
    }
  ],
  "count": 1
}

Write Endpoints

PATCH /v1/profile

Update your display name. Scope: write:profile Request body

{
  "displayName": "John Doe"
}

Response

{
  "success": true
}

PATCH /v1/transactions/{hash}/category

Assign a spending category to a transaction. Scope: write:transactions Path parameters

Parameter	Type	Required	Description
`hash`	string	Yes	Transaction hash

Request body

{
  "category": "GROCERIES"
}

Valid categories: 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 Response

{
  "success": true
}

PATCH /v1/transactions/{hash}/note

Add or update a note on a transaction. Scope: write:transactions Path parameters

Parameter	Type	Required	Description
`hash`	string	Yes	Transaction hash

Request body

{
  "note": "Dinner at Luigi's"
}

Response

{
  "success": true
}

POST /v1/transactions/batch/categories

Categorize up to 25 transactions at once. Scope: write:transactions Request body

{
  "updates": [
    { "transactionHash": "0xabc...123", "category": "GROCERIES" },
    { "transactionHash": "0xdef...456", "category": "TRAVEL" }
  ]
}

Response

{
  "succeeded": 2,
  "failed": 0
}

POST /v1/transactions/batch/notes

Add notes to up to 25 transactions at once. Scope: write:transactions Request body

{
  "updates": [
    { "transactionHash": "0xabc...123", "note": "Weekly groceries" },
    { "transactionHash": "0xdef...456", "note": "Flight to Paris" }
  ]
}

Response

{
  "succeeded": 2,
  "failed": 0
}

POST /v1/accounts/wallets

Save an external crypto wallet. Scope: write:external_accounts Request body

{
  "walletName": "MetaMask",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "confirmed": true
}

Set confirmed: false first to check for warnings (e.g. if the address belongs to another Moneda user). Then resend with confirmed: true to proceed. Response

{
  "success": true,
  "wallet": {
    "id": "acc_123",
    "name": "MetaMask",
    "address": "0x1234...5678",
    "network": "Base",
    "supportedTokens": ["USDC", "EURC"]
  }
}

Or if confirmation is needed:

{
  "success": false,
  "requiresConfirmation": true,
  "message": "This address belongs to a Moneda user. Are you sure you want to add it as an external wallet?"
}

POST /v1/accounts/banks

Save a bank account (EU IBAN or US ACH). Scope: write:external_accounts Request body (EU)

{
  "firstName": "John",
  "lastName": "Doe",
  "country": "DE",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "confirmed": true
}

Request body (US)

{
  "firstName": "John",
  "lastName": "Doe",
  "country": "US",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "confirmed": true
}

Response

{
  "success": true,
  "bankAccount": {
    "id": "bank_456",
    "holderName": "John Doe",
    "country": "DE",
    "iban": "DE89****3000"
  }
}

POST /v1/payments

Initiate a payment. Requires approval in the Moneda app. Scope: write:payments

Payments are not executed immediately. After calling this endpoint, the user must approve the payment in the Moneda mobile app within 5 minutes.

Request body

{
  "paymentType": "transfer_moneda",
  "amount": "50.00",
  "currency": "USD",
  "recipientUsername": "@alice",
  "reference": "Dinner split"
}

Payment types

Type	Required fields	Description
`transfer_moneda`	`recipientUsername`	Send to a Moneda user
`transfer_account`	`accountId`	Send to a saved external account
`transfer_contact_bank`	`contactUsername`, `contactAccountId`	Send to a contact’s bank account
`transfer_contact_wallet`	`contactUsername`, `contactAccountId`	Send to a contact’s wallet

Response

{
  "paymentRequestId": "pr_abc123",
  "status": "PENDING_APPROVAL",
  "amount": "50.00",
  "currency": "USD",
  "recipient": "@alice",
  "paymentType": "transfer_moneda",
  "expiresAt": "2026-03-07T10:35:00.000Z",
  "message": "Payment request created. Please approve in your Moneda app within 5 minutes.",
  "nextStep": "Open the Moneda app to approve this payment.",
  "pollAfterMs": 3000
}

GET /v1/payments//status

Check the status of a payment request. Scope: write:payments Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Payment request ID (UUID)

Response

{
  "paymentRequestId": "pr_abc123",
  "status": "COMPLETED",
  "amount": "50.00",
  "currency": "USD",
  "recipient": "@alice",
  "paymentType": "transfer_moneda",
  "expiresAt": "2026-03-07T10:35:00.000Z",
  "message": "Payment completed successfully.",
  "transactionHash": "0xabc...123"
}

Payment statuses: PENDING_APPROVAL, APPROVED, COMPLETED, FAILED, EXPIRED, REJECTED

POST /v1/x402-payments

Pay an x402 (HTTP 402 Payment Required) invoice to a wallet address. Requires approval in the Moneda app, then settles on-chain to the resource’s payTo address. Scope: write:payments

Like other payments, x402 invoices are not executed immediately — the user must approve in the Moneda mobile app within 5 minutes. Poll GET /v1/payments/{id}/status for the result, then retry the original HTTP request once it is COMPLETED.

Request body

{
  "amount": "0.01",
  "currency": "USD",
  "payTo": "0x1234567890123456789012345678901234567890",
  "resource": "https://api.example.com/data",
  "network": "base",
  "reference": "API call"
}

Field	Required	Description
`amount`	Yes	Amount to pay (e.g. `"0.01"`)
`currency`	Yes	`USD` (→ USDC) or `EUR` (→ EURC)
`payTo`	Yes	Recipient wallet address from the 402 `paymentRequirements.payTo`
`resource`	Yes	The URL that returned HTTP 402
`network`	Yes	x402 network — must match the Moneda deployment (`base`)
`maxAmountRequired`	No	Maximum amount from the 402 response
`reference`	No	Optional memo (max 140 chars)

Response

{
  "paymentRequestId": "pr_abc123",
  "status": "PENDING_APPROVAL",
  "amount": "0.01",
  "currency": "USD",
  "recipient": "x402 · 0x1234...7890 · api.example.com",
  "paymentType": "x402",
  "expiresAt": "2026-03-07T10:35:00.000Z",
  "message": "x402 payment request created. Approve it in your Moneda app.",
  "pollAfterMs": 10000
}

Payment Routing

These endpoints help an agent or client choose a payment corridor and quote the cost before calling POST /v1/payments. They are provider-agnostic — don’t branch on which underlying processor handles each rail.

GET /v1/payment-destinations

List the country, currency, and rail combinations Moneda can pay out to. Each entry includes the required fields you’ll need to collect from the user before calling POST /v1/payments. Scope: read:external_accounts Query parameters

Parameter	Type	Required	Description
`countrySymbol`	string	No	Filter by ISO country code (e.g. `BR`, `MX`, `CO`)

GET /v1/payment-quote

Preview the cost, FX rate, and final amount for moving money between two currencies. Provide exactly one of amountIn (what the user sends) or amountOut (what they want to receive). Scope: read:rates Query parameters

Parameter	Type	Required	Description
`fromCurrency`	string	Yes	Source currency (e.g. `USDC`, `EUR`)
`toCurrency`	string	Yes	Target currency
`amountIn`	string	One of	Amount the sender pays (mutually exclusive with `amountOut`)
`amountOut`	string	One of	Amount the recipient receives (mutually exclusive with `amountIn`)

Receipts

Receipts are user-uploaded files (PDFs, images, structured invoices) the platform OCRs, extracts to structured fields, and optionally auto-matches to a transaction. Bills are the invoice-shaped sibling (AP queue) covered separately below.

GET /v1/receipts

List the user’s transaction receipts, newest first, with extracted summary fields and lifecycle status. Scope: read:receipts Query parameters: transactionHash (optional), needsReview (true/false, optional), status (optional), limit (default 20, max 100), cursor (optional).

GET /v1/receipts/{receiptId}

Get one receipt with full extracted fields and a presigned S3 download URL valid for ~15 minutes. Scope: read:receipts

GET /v1/receipts/{receiptId}/line-items

List parsed line items on a receipt — description, quantity, unit price, total, tax rate, category. Scope: read:receipts

POST /v1/receipts/{receiptId}/line-items

Add a line item to a receipt. Used after manual extraction review. Scope: write:receipts

PATCH /v1/receipts/line-items/{lineItemId}

Update one line item on a receipt (description, quantity, price, tax rate, category). Scope: write:receipts

DELETE /v1/receipts/line-items/{lineItemId}

Remove one line item from a receipt. Scope: write:receipts

GET /v1/receipts/line-items/search

Search across every line item the user has uploaded (case-insensitive substring on description). Returns matching items + aggregate spend grouped by currency. Optional category and date-range filters. Scope: read:receipts

POST /v1/receipts

Create a receipt row (metadata only; for direct upload use the upload-url + finalize flow). Scope: write:receipts

DELETE /v1/receipts/{receiptId}

Delete a receipt and its line items. Scope: write:receipts

POST /v1/receipts/upload-url

Step 1 of 2 — get a presigned S3 PUT URL to stage a local file. Returns uploadUrl, uploadKey, and constraints (size cap, content-type whitelist). The file bytes go directly to S3. Scope: write:receipts

POST /v1/receipts/finalize

Step 2 of 2 — after PUTting the file to S3, finalize the receipt to run OCR + LLM extraction, attempt auto-match to a transaction, and persist line items. Pass the uploadKey from /v1/receipts/upload-url. Scope: write:receipts

POST /v1/receipts/import-url

Import a receipt directly from an https:// URL (S3, Drive shared link, public file host). The server fetches behind an SSRF guard — rejects private IPs and non-https. Single call. Scope: write:receipts

POST /v1/receipts/{receiptId}/attach

Link a receipt to a transaction (used after manual review when auto-match didn’t run or was wrong). Scope: write:receipts

POST /v1/receipts/{receiptId}/detach

Unlink a receipt from its transaction. Scope: write:receipts

POST /v1/receipts/{receiptId}/confirm-suggestion

Accept the auto-match suggestion the OCR pipeline proposed. Scope: write:receipts

POST /v1/receipts/{receiptId}/reject-suggestion

Reject the auto-match suggestion (the receipt stays unlinked). Scope: write:receipts

Bills (AP queue)

Bills are the invoice-shaped sibling of receipts. They surface as an accounts-payable queue ordered due-soon-first, and carry merchant + payment routing detail extracted by OCR.

GET /v1/bills

List the user’s bills (AP queue), ordered dueDate ASC NULLS LAST, id DESC. Cursor-paginated; defaults to status=PENDING. Scope: read:receipts

GET /v1/bills/{billId}

Get one bill with full extracted detail — merchant (name, tax id, address), total, currency, due date, invoice number, vendor IBAN/BIC/routing/account, payment status, presigned download URL. Scope: read:receipts

Bewirtungsbelege (German hospitality receipts)

Bewirtungsbelege are an overlay on existing transactions that capture German tax-deductible business-meal detail (occasion, attendees, deductible/non-deductible split). They reference a transaction; the receipt file itself stays in the Receipts table.

GET /v1/bewirtungsbelege

List the user’s Bewirtungsbelege. Each row carries the underlying transaction, date, location, occasion, total/tip/subtotal split, deductible/non-deductible amounts, and signing state. Scope: read:receipts

GET /v1/bewirtungsbelege/{bewirtungsbelegId}

Get one Bewirtungsbeleg with full detail including attendees. Scope: read:receipts

POST /v1/bewirtungsbelege

Create a Bewirtungsbeleg overlay for an existing transaction. Scope: write:receipts

DELETE /v1/bewirtungsbelege/{bewirtungsbelegId}

Delete a Bewirtungsbeleg overlay. The underlying transaction and receipt file are untouched. Scope: write:receipts

Eigenbelege (German self-issued substitute receipts)

Eigenbelege are used when the original receipt for a transaction was lost or never issued. They capture the recipient, amount, and reason for the substitute receipt.

GET /v1/eigenbelege

List the user’s Eigenbelege. Each row carries the linked transaction, recipient name, amount, reason, and signing state. Scope: read:receipts

GET /v1/eigenbelege/{eigenbelegId}

Get one Eigenbeleg with full detail. Scope: read:receipts

POST /v1/eigenbelege

Create an Eigenbeleg overlay for an existing transaction. Scope: write:receipts

DELETE /v1/eigenbelege/{eigenbelegId}

Delete an Eigenbeleg overlay. The underlying transaction is untouched. Scope: write:receipts

Cards

Card endpoints return PCI-redacted metadata only — last four digits, expiry, design, status. Full PAN / CVV / PIN are never available via the API. Freeze and unfreeze run on-chain via the PausableCardGuard and are fully reversible.

GET /v1/cards

List the user’s cards (active, suspended, expired, terminated) with PCI-redacted metadata. Scope: read:cards

GET /v1/cards/{cardId}

Get detailed metadata for one card (status, type, program, currency, expiry, design). Returns NOT_FOUND if the card does not exist or does not belong to the caller. Scope: read:cards

POST /v1/cards/{cardId}/freeze

Freeze a card on-chain via the PausableCardGuard. Settlement is blocked at the Roles Module level. Idempotent at the storage level (re-freezing succeeds, but a fresh on-chain tx is submitted on every call). Returns CONFLICT if the card’s on-chain proxy hasn’t been deployed yet. Scope: write:cards

POST /v1/cards/{cardId}/unfreeze

Unfreeze a card on-chain via the PausableCardGuard. Restores settlement. Idempotent at the storage level. Scope: write:cards

Scheduled (Recurring) Transactions

Read + lifecycle (pause/resume) endpoints for scheduled transactions. Create / activate / cancel / edit / renew are NOT exposed via REST — they need a passkey signature on a Smart Sessions install UserOp, which is mobile-app only.

GET /v1/scheduled-transactions

List the user’s scheduled (recurring) transactions. Filter by status. Scope: read:transactions

GET /v1/scheduled-transactions/{id}

Get one scheduled transaction by id. Scope: read:transactions

GET /v1/scheduled-transactions/upcoming

List the next scheduled executions across all the user’s schedules. Scope: read:transactions

GET /v1/scheduled-transactions/{id}/history

List past executions for one schedule. Scope: read:transactions

POST /v1/scheduled-transactions/{id}/pause

Pause execution of a schedule (backend-only state flip; no on-chain change). Scope: write:transactions

POST /v1/scheduled-transactions/{id}/resume

Resume execution of a paused schedule. Returns the new nextExecutionAt, which is always in the future — an execution window that elapsed while the schedule was paused is skipped, never run retroactively. Fails with 422 if the schedule’s end date has already passed. Scope: write:transactions

Agent Sessions

Read + lifecycle (pause/resume/revoke) endpoints for scoped autonomous agent sessions — a bounded mandate an agent can spend against without per-payment approval. Create / execute and the passkey-bound install are served separately. Both scopes are opt-in (not granted by default).

POST /v1/agent-sessions

Create a scoped autonomous payment session. Does NOT activate — returns a counterfactual child Safe address and an activation link the user opens in the Moneda app to install the on-chain policy with a passkey. Body: recipient, currency (USD/EUR), maxAmountPerExecution, maxAmountPerPeriod (user-facing units), periodSeconds, optional expiresAt, fundingAmount. Scope: write:agent_sessions

GET /v1/agent-sessions

List the user’s agent sessions, newest first, with status, spending policy, and remaining period cap. Optional status query filter. Scope: read:agent_sessions

POST /v1/agent-sessions/{id}/payments

Execute a payment within an ACTIVE session’s on-chain policy — no per-payment approval. Body: recipient, amount (user-facing units), currency, optional idempotencyKey for safe retries. Scope: write:agent_sessions

GET /v1/agent-sessions/{id}

Get one agent session by id, including its 5 most recent executions. Scope: read:agent_sessions

POST /v1/agent-sessions/{id}/pause

Pause an active session (backend-only flip; halts execution, reversible via /resume). Scope: write:agent_sessions

POST /v1/agent-sessions/{id}/resume

Resume a manually-paused session. Auto-paused sessions need their underlying condition cleared first. Scope: write:agent_sessions

POST /v1/agent-sessions/{id}/revoke

Revoke a session — immediately and permanently halts all execution. The on-chain uninstall is completed separately in the Moneda app. Scope: write:agent_sessions

Usage Credits

POST /v1/usage-credits/purchase

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 (idempotent). The payment is already finished, so there is nothing more to approve. Body: transactionHash. Scope: write:usage_credits Response

{
  "granted": true,
  "txHash": "0x4a3f…",
  "paidAmount": 50.0,
  "paidCurrency": "USDC",
  "budgetUsd": "47.50",
  "creditBalanceUsd": "47.50"
}

PATCH /v1/usage-credits/monthly-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). Body: monthlyLimitUsd (number 0–100000, or null for unlimited). Scope: write:usage_credits Response

{
  "monthlySpendLimitUsd": "50.00",
  "unlimited": false
}

Subscriptions

Read + invoice-generation surface for subscription billing. The write surface (subscribe / cancel / change plan) stays in tRPC for now — it needs on-chain Smart Session ceremonies that don’t fit a synchronous REST request. Gated by the ENABLE_BALANCE_PAY_SUBSCRIPTIONS feature flag in the services layer (a disabled flag surfaces as 403).

GET /v1/subscriptions/charges

Cursor-paginated list of the authenticated user’s subscription charges (SUBSCRIPTION_CHARGE rows), newest first. Scope: read:subscriptions

POST /v1/subscriptions/charges/{chargeId}/invoice

Idempotently generate (and upload) the ZUGFeRD plan-invoice PDF for a charge and return a 1-hour presigned downloadUrl. Re-calling for the same charge reuses the existing invoice. Returns 404 if the charge doesn’t exist or isn’t owned by the caller. Scope: read:subscriptions

Platform (Management API)

The Platform Management API (/v1/platform/*) lets developers manage their organization, workspaces, members, invites, and platform API keys. These endpoints are authorized by the calling user’s organization role (owner / admin / developer / billing / compliance / member), not by MCP scopes. See the Moneda Platform for the full model.

POST /v1/platform/organizations

Create an organization. The caller is seated as its OWNER. Body: name, slug.

GET /v1/platform/organizations

List the organizations the caller is an active member of, with their role in each.

POST /v1/platform/organizations/{orgId}/workspaces

Create a workspace under an organization. Requires a key-manager role (owner / admin / developer). Body: name, slug.

GET /v1/platform/organizations/{orgId}/workspaces

List the workspaces in an organization.

POST /v1/platform/organizations/{orgId}/members

Add (or re-activate) a member by user id. Requires a member-manager role (owner / admin); only an owner may grant or modify the OWNER role. Body: userId, role.

GET /v1/platform/organizations/{orgId}/members

List the members of an organization with their roles.

POST /v1/platform/organizations/{orgId}/invites

Invite a member by email. Requires a member-manager role. Returns the raw invite token once. Body: email, role.

GET /v1/platform/organizations/{orgId}/invites

List an organization’s invites with their status (pending / accepted / expired). Never exposes the token hash.

POST /v1/platform/invites/accept

Accept an invite. Body: the raw invite token. Seats the caller as an organization member.

POST /v1/platform/workspaces/{workspaceId}/keys

Issue a workspace-scoped platform API key. Requires a key-manager role. The raw secret is returned exactly once. Body: name, scopes (money-movement scopes are not available on platform keys), optional mode. mode: "live" (default) mints an mnd_live_… key billed against org credits; mode: "test" mints an mnd_test_… sandbox key — it never decrements credits, never calls paid upstreams, and uses separate rate buckets. (Sandbox tool calls are served as deterministic fixtures; tool execution over platform keys — live and sandbox — ships with the tool API and is not yet available.) Live and sandbox keys have independent per-workspace caps. The response sandbox flag reflects the key’s mode.

GET /v1/platform/workspaces/{workspaceId}/keys

List a workspace’s platform API keys (metadata only — never the secret).

POST /v1/platform/keys/{keyId}/rotate

Rotate a platform key: mints a replacement and puts the old key on a grace window so it can be swapped with zero downtime. Requires a key-manager role.

DELETE /v1/platform/keys/{keyId}

Revoke a platform key immediately. Requires a key-manager or compliance role.

POST /v1/platform/organizations/{orgId}/limits

Create or reconfigure a spend/rate limit. Requires a member-manager role (owner / admin). Body: scope (ORG/WORKSPACE/KEY), targetId, limitType (SPEND_HARD/SPEND_SOFT/RATE_RPM/RATE_TPM/RATE_RPD), value, optional windowSeconds (rolling window; defaults to the calendar month for spend), and optional notifyThresholdPct (1–99). Upserts on (scope, targetId, limitType).

GET /v1/platform/organizations/{orgId}/limits

List every limit configured for the org (its own, plus workspace- and key-scoped limits). Any member may read.

DELETE /v1/platform/organizations/{orgId}/limits/{limitId}

Remove a limit. Requires a member-manager role.

POST /v1/platform/workspaces/{workspaceId}/webhooks

Register a webhook endpoint for a workspace. Requires a member-manager role. Body: url (https only, and must resolve to a public address — loopback/private/link-local targets are rejected at registration and re-checked at every delivery), optional description, and enabledEvents (one or more of the event catalog below). The signingSecret is returned exactly once — store it to verify signatures.

GET /v1/platform/workspaces/{workspaceId}/webhooks

List a workspace’s webhook endpoints (metadata only — never the signing secret).

PATCH /v1/platform/webhooks/{webhookId}

Update an endpoint’s url, description, enabledEvents, or status (ENABLED/DISABLED). Requires a member-manager role.

DELETE /v1/platform/webhooks/{webhookId}

Delete a webhook endpoint (cascades its pending deliveries). Requires a member-manager role. Event catalog: usage.threshold_reached, usage.limit_exceeded, usage.rate_limited, credit.low, credit.exhausted, key.created, key.revoked. Signature verification. Each delivery is a POST with headers X-Moneda-Event, X-Moneda-Delivery, X-Moneda-Timestamp, and X-Moneda-Signature. Verify by computing HMAC-SHA256(signingSecret, "v0:" + timestamp + ":" + rawBody) (hex) and comparing against X-Moneda-Signature; reject timestamps outside a few minutes to prevent replay. Delivery is at-least-once. A retry (or an overlapping dispatch of a still-in-flight delivery) can send the same event more than once. Deduplicate on X-Moneda-Delivery (unique per delivery attempt) or the event’s id, and make your handler idempotent. Return a 2xx promptly; any other status is retried with exponential backoff up to 6 attempts.

GET /v1/platform/organizations/{orgId}/audit-log

Read the organization audit log (policy-changing actions: key/limit/webhook/member changes), newest first. Restricted to owner / admin / compliance roles. Query: optional action filter, before (opaque cursor — pass a prior response’s nextBefore), limit (default 50, max 200). Response includes nextBefore for keyset pagination.

GET /v1/platform/organizations/{orgId}/usage

Read the organization’s metered request log (one row per billed call), newest first. Any member may read. Query: optional workspaceId, apiKeyId, tool filters, before (opaque cursor — pass a prior response’s nextBefore), limit (default 50, max 200). Money fields (costUsd, upstreamCostUsd) are strings; response includes nextBefore.

GET /v1/platform/pricing

The machine-readable rate card: one row per tool with unitPriceUsd, markupMultiplier, and the effective pricePerUnitUsd (unit × markup), plus unit (PER_CALL/PER_1K_TOKENS/PER_GB_DAY), category, and scope. Money fields are decimal strings. This is the global default table.

GET /v1/platform/organizations/{orgId}/contract

Read the org’s enterprise contract (committed spend, term, SLA tier, dedicated-capacity flag, legal-doc references) plus its billingMode and dataResidency. Returns null if the org has no contract. Any member may read.

PUT /v1/platform/organizations/{orgId}/contract

Create or update the enterprise contract terms. Requires a member-manager role. Body (all optional): status (DRAFT/ACTIVE/EXPIRED/TERMINATED), committedAmountUsd, termStart, termEnd, autoRenew, slaTier, dedicatedUpstreamCapacity, legalDocRefs ([{ kind, url, version?, signedAt? }] — pointers to MSA/DPA/SLA, never the documents), dataResidency. Provisioning is sales-led; in production this is a Moneda-admin action.

POST /v1/platform/organizations/{orgId}/billing-mode

Set the org’s billing mode. Requires a member-manager role. Body: billingMode (PREPAID or INVOICED). INVOICED — where usage accrues to a monthly invoice against the contract instead of decrementing prepaid credits — requires an ACTIVE contract.

Error Responses

All errors follow a consistent format:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing Bearer token",
  "retryable": false
}

Error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing Bearer token
`INSUFFICIENT_SCOPE`	403	Token lacks the required scope
`NOT_FOUND`	404	Resource not found
`RESOURCE_NOT_OWNED`	403	Resource belongs to another user
`VALIDATION_ERROR`	422	Invalid request parameters
`RATE_LIMIT_EXCEEDED`	429	Too many requests (60/min per IP)
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	Downstream service temporarily unavailable

What’s next?

Authentication

Learn how to authenticate your API requests.

OpenAPI Spec

Explore the API interactively with Swagger UI.

Scopes

See which scopes each endpoint requires.

CLI Tool

Use these endpoints from the command line with the Moneda CLI.

​Base URL

​Response shape: ?view=full vs ?view=lite

​Health

​GET /v1/health

​Balances & Finances

​GET /v1/balances

​GET /v1/lifetime-savings

​GET /v1/transactions

​GET /v1/transactions/{hash}

​GET /v1/spending/by-type-group

​GET /v1/spending/by-category

​GET /v1/spending/by-contact

​GET /v1/spending/by-merchant

​GET /v1/spending/comparison

​GET /v1/spending/daily

​GET /v1/spending/transactions

​GET /v1/exchange-rates

​GET /v1/apy-rates

​GET /v1/dinari/capabilities

​GET /v1/dinari/us/requirements

​GET /v1/dinari/market-hours

​GET /v1/dinari/orders/free-trade-allowance

​GET /v1/earnings/time-series

​Account Info

​GET /v1/wallet

​GET /v1/virtual-accounts

​GET /v1/virtual-accounts/limits

​GET /v1/virtual-accounts/settlement-estimate

​GET /v1/accounts

​GET /v1/contacts

​GET /v1/settings

​GET /v1/passkeys

​PATCH /v1/passkeys/{id}/label

​GET /v1/recovery-contacts

​Recovery emails (ZK email recovery)

​GET /v1/recovery-emails

​GET /v1/recovery-emails/{id}

​GET /v1/recovery-config

​GET /v1/recovery-status

​Notifications

​GET /v1/notifications

​GET /v1/notifications/unread-count

​Sub-accounts (vaults)

​GET /v1/sub-accounts

​GET /v1/sub-accounts/{id}

​GET /v1/sub-accounts/{id}/balance

​GET /v1/wealth

​Sessions

​POST /v1/sessions

​DELETE /v1/sessions/{sessionId}

​GET /v1/sessions/active

​DELETE /v1/sessions/active/{sessionId}

​POST /v1/sessions/revoke-all

​Points & Referrals

​GET /v1/points/balance

​GET /v1/points/activity

​GET /v1/points/redemption-config

​POST /v1/points/redeem

​GET /v1/referrals/code

​GET /v1/referrals/referees

​Knowledge Base

​GET /v1/knowledge/search

​GET /v1/knowledge/categories/

​GET /v1/knowledge/items/

​Users

​GET /v1/users/search

​Write Endpoints

​PATCH /v1/profile

​PATCH /v1/transactions/{hash}/category

​PATCH /v1/transactions/{hash}/note

​POST /v1/transactions/batch/categories

​POST /v1/transactions/batch/notes

​POST /v1/accounts/wallets

​POST /v1/accounts/banks

​POST /v1/payments

​GET /v1/payments//status

​POST /v1/x402-payments

​Payment Routing

​GET /v1/payment-destinations

​GET /v1/payment-quote

Base URL

Response shape: `?view=full` vs `?view=lite`

Health

GET /v1/health

Balances & Finances

GET /v1/balances

GET /v1/lifetime-savings

GET /v1/transactions

GET /v1/transactions/{hash}

GET /v1/spending/by-type-group

GET /v1/spending/by-category

GET /v1/spending/by-contact

GET /v1/spending/by-merchant

GET /v1/spending/comparison

GET /v1/spending/daily

GET /v1/spending/transactions

GET /v1/exchange-rates

GET /v1/apy-rates

GET /v1/dinari/capabilities

GET /v1/dinari/us/requirements

GET /v1/dinari/market-hours

GET /v1/dinari/orders/free-trade-allowance

GET /v1/earnings/time-series

Account Info

GET /v1/wallet

GET /v1/virtual-accounts

GET /v1/virtual-accounts/limits

GET /v1/virtual-accounts/settlement-estimate

GET /v1/accounts

GET /v1/contacts

GET /v1/settings

GET /v1/passkeys

PATCH /v1/passkeys/{id}/label

GET /v1/recovery-contacts

Recovery emails (ZK email recovery)

GET /v1/recovery-emails

GET /v1/recovery-emails/{id}

GET /v1/recovery-config

GET /v1/recovery-status

Notifications

GET /v1/notifications

GET /v1/notifications/unread-count

Sub-accounts (vaults)

GET /v1/sub-accounts

GET /v1/sub-accounts/{id}

GET /v1/sub-accounts/{id}/balance

GET /v1/wealth

Sessions

POST /v1/sessions

DELETE /v1/sessions/{sessionId}

GET /v1/sessions/active

DELETE /v1/sessions/active/{sessionId}

POST /v1/sessions/revoke-all

Points & Referrals

GET /v1/points/balance

GET /v1/points/activity

GET /v1/points/redemption-config

POST /v1/points/redeem

GET /v1/referrals/code

GET /v1/referrals/referees

Knowledge Base

GET /v1/knowledge/search

GET /v1/knowledge/categories/

GET /v1/knowledge/items/

Users

GET /v1/users/search

Write Endpoints

PATCH /v1/profile

PATCH /v1/transactions/{hash}/category

PATCH /v1/transactions/{hash}/note

POST /v1/transactions/batch/categories

POST /v1/transactions/batch/notes

POST /v1/accounts/wallets

POST /v1/accounts/banks

POST /v1/payments

GET /v1/payments//status

POST /v1/x402-payments

Payment Routing

GET /v1/payment-destinations

GET /v1/payment-quote