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://rest.moneda.com/v1

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

curl -H "Authorization: Bearer YOUR_TOKEN" https://rest.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://rest.moneda.com/v1/wallet -H "Authorization: Bearer $TOKEN"
# → {"smartAccountAddress":"0x...","network":"Base","supportedTokens":[...],
#    "username":"@alice","warning":"...","tip":"..."}

# Lite
curl 'https://rest.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` \| `CAD` \| `MXN`	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": "$",
  "components": {
    "sponsoredGas": 210.4,
    "ironFees": 88.16,
    "tierDiscount": 936.0
  }
}

components itemises the same total, in the same display currency: network fees Moneda paid on your behalf, on/off-ramp fees Moneda absorbed, and your plan’s discount on Moneda’s own fees versus Standard. Each is rounded independently, so the parts can differ from savings by a cent.

GET /v1/transactions

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

Parameter	Type	Required	Description
`currency`	`USD` \| `EUR` \| `CHF` \| `CAD` \| `MXN`	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`, `card`, `trade` (crypto and stock buys/sells; each row adds a `trade` block with fills, fees and any failure)
`category`	string	No	Filter by spending category (e.g. `GROCERIES`, `TRAVEL`)
`status`	`COMPLETED` \| `COMPLETED_DELAYED` \| `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
`hasReceipt`	`true` \| `false`	No	Filter by whether transactions have a receipt attached
`sort`	`newest` \| `oldest` \| `amount_desc` \| `amount_asc`	No	Default: `newest`
`limit`	number	No	Max 50, default 5
`offset`	number	No	Pagination offset
`cursor`	string	No	Opaque cursor for keyset pagination (alternative to `offset`)
`cardId`	string	No	Filter to transactions made with one card
`card`	string	No	Filter by card, accepting a card id or its last four digits
`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"
      },
      "refundOf": null,
      "refunds": []
    }
  ],
  "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, or an on-ramp. Absent means “no user signature on file”, not “an unrecognised key”.

refundOf links a refund to the payment it reverses ({ id, transactionHash }, or null). refunds lists the completed refunds of a payment, oldest first, each with id, transactionHash, amount, currency and createdAt; it is empty when nothing was refunded.

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` \| `CHF` \| `CAD` \| `MXN`	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
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD` \| `MXNB`	Yes	Stablecoin to break down
`period`	`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/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
`recipientAccountId`	string	Yes	Recipient account id (from `/v1/contacts` or `/v1/accounts`)
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD` \| `MXNB`	Yes	Stablecoin to break down
`period`	`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/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
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD` \| `MXNB`	Yes	Stablecoin to break down
`period`	`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/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`	`USDC` \| `EURC` \| `CHFAU` \| `CADD` \| `MXNB`	Yes	Stablecoin to compare

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` \| `MXNB`	Yes	Token to chart
`period`	`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
`currency`	`USDC` \| `EURC` \| `CHFAU` \| `CADD` \| `MXNB`	No	Filter to a single stablecoin
`period`	`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)
`bucketKind`	`category` \| `merchant`	No	Which kind of bucket `bucketId` refers to
`bucketId`	string	No	Drill into one bucket of `bucketKind`
`bucketType`	`user` \| `bank-withdrawal` \| `external-wallet` \| `coinbase` \| `wallet-connect` \| `other`	No	Narrow a merchant bucket to one counterparty kind
`recipientAccountId`	string	No	Drill into one recipient account
`orderBy`	`createdAt` \| `amount`	No	Sort field. Default `createdAt`.
`direction`	`asc` \| `desc`	No	Sort direction. Default `desc`.
`take`	number	No	Page size
`skip`	number	No	Page offset

GET /v1/exchange-rates

Exchange rate between two supported currencies. Scope: read:rates Query parameters

Parameter	Type	Required	Description
`from`	`USD` \| `EUR` \| `CHF` \| `CAD` \| `MXN`	No	Default: `USD`
`to`	`USD` \| `EUR` \| `CHF` \| `CAD` \| `MXN`	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` \| `CHF` \| `CAD` \| `MXN`	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,
  "minOrderNotionalUsd": 2,
  "brokerOrderFeeUsd": 0.2,
  "blockedReasons": ["dinari_us_onboarding_incomplete", "dinari_kyc_not_approved"]
}

brokerOrderFeeUsd is the broker’s per-order fee, separate from Moneda’s own trade fee. It is taken out of the amount on a buy and off the proceeds on a sale: a

4 buy puts

3.80 into shares. It is 0 when the broker bills its network fees to Moneda instead. 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
`chainRef`	string	Yes	Chain reference for the vault account
`vaultProvider`	`MORPHO` \| `YO`	Yes	Which vault provider the account belongs to

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", "MXNB"],
  "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",
  "rfis": [],
  "rfiRequired": false,
  "missingRequirements": []
}

rfis has the same shape as the items of GET /v1/virtual-accounts/information-requests. rfiRequired is true when one is waiting on the user’s answers. missingRequirements lists what Iron still needs while eddRequired is true (codes such as kyc_questionnaire, kyc_proof_of_residence, kyc_identity, kyc_selfie); the user finishes these in the app.

GET /v1/virtual-accounts/information-requests

Compliance information requests (RFIs) the banking partner (Iron/MoonPay) has sent the user. Scope: read:virtual_accounts Read-only by design: MoonPay requires the customer to answer personally, so there is no endpoint to submit answers or documents. Direct the user to Settings > Features and limits in the Moneda app. Response

{
  "items": [
    {
      "id": "rfi_123",
      "rfiType": "source_of_funds",
      "status": "waiting_on_response",
      "transactionId": null,
      "sentAt": "2026-09-17T10:00:00Z",
      "openRound": {
        "id": "round_1",
        "round_number": 1,
        "questions": [
          { "id": "q1", "prompt": "What is the source of these funds?", "answer_type": "text", "required": true }
        ],
        "answers": null,
        "analyst_instructions": null,
        "documents_requested": false,
        "document_instructions": null,
        "document_upload_url": null,
        "document_link_opened_at": null,
        "sent_at": "2026-09-17T10:00:00Z",
        "response_received_at": null
      }
    }
  ]
}

status is waiting_on_response, needs_review or closed. openRound is null when nothing is waiting on the user. 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
}

API Keys

An API key is a long-lived credential for scripts, the CLI (--api-key), and integrations that can’t run an OAuth flow. Send it as X-API-Key. Two rules apply wherever a key is minted: it can never carry a scope the calling credential doesn’t already hold, and payment scopes are never available on an API key at all — moving money always goes through approval in the app.

GET /v1/api-keys

Your API keys. Scope: read:api_keys Returns { keys: [...] }. Each key carries id, name, prefix (the first 12 characters, enough to recognise it), scopes, lastUsedAt, expiresAt, revokedAt, createdAt, and isActive. The secret is stored hashed and is never returned here.

POST /v1/api-keys

Create an API key. Scope: write:api_keys Body

Field	Description
`name`	What the key is for, 1–100 characters
`scopes`	Permissions the key carries — a subset of the scopes your own credential holds
`expiresInDays`	Optional expiry. Omit for a key that doesn’t expire

Response The key field is the secret, and this response is the only place it ever appears — it can’t be retrieved again. A maximum of 10 active keys is allowed; revoke one to make room.

{
  "id": "dbf500d0-f6a0-486e-bfd8-38ace2701b69",
  "name": "monthly export script",
  "key": "mnd_example000000000000000000000000000000000",
  "prefix": "mnd_example0",
  "scopes": ["read:balances", "read:transactions"],
  "expiresAt": null,
  "createdAt": "2026-08-19T19:43:31.261Z"
}

DELETE /v1/api-keys/{keyId}

Revoke an API key. Scope: write:api_keys The key is refused on its very next request. This can’t be undone — create a new key to restore access.

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` \| `MXNB`	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/sub-accounts/{id}/proposals

Approval requests on a joint account (M-of-N). Read-only: voting and executing require a passkey signature from the user’s device. Path parameters

Parameter	Type	Description
`id`	UUID	Sub-account id

Query parameters

Parameter	Type	Required	Description
`includeResolved`	`true` \| `false`	No	Default `false` (open requests only). `true` also returns completed / rejected / expired / failed.

A request past its deadline that no writer has swept yet reports isExpired: true while its status is still PENDING.

GET /v1/sub-accounts/proposals/{proposalId}

One approval request with its per-member approval list. Path parameters

Parameter	Type	Description
`proposalId`	UUID	Proposal id

POST /v1/sub-accounts/{id}/top-up

Propose moving money from your main account into this sub-account. Requires approval in the Moneda app. Scope: write:sub_accounts Request body

{ "amount": "200.00", "currency": "USD" }

currency is one of USD, EUR, CHF, CAD, MXN. Response Same shape as POST /v1/payments, with paymentType set to sub_account_top_up. Poll GET /v1/payments/{id}/status for the result.

POST /v1/sub-accounts/{id}/withdraw

Propose moving money from this sub-account back to your main account (single-signature sub-accounts). Requires approval in the Moneda app. Scope: write:sub_accounts Same request body as top-up. paymentType is sub_account_withdraw.

POST /v1/sub-accounts/{id}/swap

Propose a swap inside this sub-account. One side must be a currency (USD, EUR, CHF, CAD, MXN); the other can be a crypto asset symbol such as cbBTC. The funds stay in the sub-account. Requires approval in the Moneda app. Scope: write:sub_accounts Request body

{ "fromAsset": "USD", "toAsset": "cbBTC", "amount": "100", "slippageBps": 50 }

amount is in units of fromAsset. slippageBps is optional (0 to 200, default 50). paymentType is sub_account_swap.

POST /v1/sub-accounts/{id}/freeze

Propose freezing a sub-account you created. No request body. Unfreezing is only possible in the app. Scope: write:sub_accounts paymentType is sub_account_freeze.

POST /v1/sub-accounts/{id}/proposals

Open a SPEND or WITHDRAW proposal on a joint account that needs more than one approval. This only creates the proposal; co-owners approve and execute it in the Moneda app. Scope: write:sub_accounts Request body

{
  "proposalType": "SPEND",
  "amount": "900.00",
  "currency": "USD",
  "recipientUsername": "landlord",
  "description": "September rent"
}

For SPEND, name exactly one recipient: recipientUsername, accountId, or contactUsername / contactAccountId. Bank and cross-chain recipients are not supported. description is optional, up to 280 characters. paymentType is sub_account_proposal.

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 the same value on a retry; a replay returns `granted: false`. If omitted the server derives the key from (user, points, 30s window) rather than minting a random one, so a retry still dedupes

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`	integer	No	Max results, 1-50 (default 5). Out-of-range or non-numeric values return `400`.

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

List the published FAQ categories with each item’s id and question (no answers). Pass an id to GET /v1/knowledge/items/{id} for the answer. Response

{
  "categories": [
    {
      "slug": "fees",
      "name": "Fees",
      "itemCount": 12,
      "items": [{ "id": "cm1abc", "question": "Are there fees for 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

Wallet payouts settle on Base. A payout to a contact wallet on another chain is refused with VALIDATION_ERROR; make it in the Moneda app. Payment source (optional)

`source`	Description
omitted or `{ "kind": "main" }`	Pay from the main balance
`{ "kind": "earnings" }`	Withdraw from the USD earnings vault, then send (USD and EUR only)
`{ "kind": "sub_account", "subAccountId": "<UUID>" }`	Pay from a single-signature sub-account. Wallet recipients on Base only. Also requires the `write:sub_accounts` scope

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
}

POST /v1/payments/exchange

Exchange money between two of your own currency accounts. Requires approval in the Moneda app. Scope: write:payments fromCurrency is what leaves your account and toCurrency is what arrives. The destination is always your own account in toCurrency. Supported currencies: USD, EUR, CHF, CAD, MXN. Request body

{
  "amount": "100.00",
  "fromCurrency": "USD",
  "toCurrency": "EUR"
}

Response Same shape as POST /v1/payments, with paymentType set to exchange. Poll GET /v1/payments/{id}/status for the result.

POST /v1/payments/crypto-trade

Buy or sell a crypto asset with your own balance. Requires approval in the Moneda app. Scope: write:trades Not for sending money (POST /v1/payments) or converting between currencies (POST /v1/payments/exchange). The server chooses the route. The user sees the live price, then approves and signs in the Moneda app. amount is what you spend: in stableCurrency on a BUY, in the asset on a SELL. Supported assets: cbBTC (Bitcoin), WETH (Ethereum). Supported currencies: USD, EUR, CAD, MXN. Request body

{
  "symbol": "cbBTC",
  "side": "BUY",
  "stableCurrency": "USD",
  "amount": "100"
}

Response Same shape as POST /v1/payments, with paymentType set to crypto_swap. Poll GET /v1/payments/{id}/status for the result.

POST /v1/payments/token-buy

Buy a Base token that is not in the crypto-trade catalogue, by contract address, with your own balance. Requires approval in the Moneda app. Scope: write:trades amount is what you spend, in stableCurrency (USD, EUR, CHF or MXN). The token must be tradeable on Base. How much of it you get is priced when the user approves; they see it, then approve and sign in the Moneda app. Request body

{
  "tokenAddress": "0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed",
  "stableCurrency": "USD",
  "amount": "25"
}

Response Same shape as POST /v1/payments, with paymentType set to buy_token. Poll GET /v1/payments/{id}/status for the result.

POST /v1/payments/earnings-move

Deposit into or withdraw from an earnings vault with your own money. Requires approval in the Moneda app. Scope: write:payments vaultProvider is MORPHO (Earnings: USD, EUR, MXN) or YO (Smart Earnings: USD, EUR). A DEPOSIT comes from the account in currency; a WITHDRAW goes back to it. Request body

{
  "direction": "DEPOSIT",
  "vaultProvider": "YO",
  "currency": "USD",
  "amount": "500.00",
  "reference": "Rainy day fund"
}

Response Same shape as POST /v1/payments, with paymentType set to earnings_move. Poll GET /v1/payments/{id}/status for the result.

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 (UPLOADING / PROCESSING / VALID / INVALID / DELETED, optional), limit (default 20, max 100), offset (optional). Paging is offset-based here, not cursor-based.

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. Scope: read:receipts Query parameters: query (required), category (optional), startDate / endDate (ISO dates, optional), limit and offset (optional).

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}/reparse

Re-run OCR + LLM extraction on a receipt already stored in S3 — no re-upload needed. Use after a failed parse, a wrong extraction, or an extraction-model upgrade. Synchronous: the response is the post-extraction snapshot (status, confidence, document type, line-item count). Refuses deleted receipts and receipts with no stored file. 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}/partial-payment

Mark a receipt as a partial payment (a deposit or instalment against a larger invoice), so a total that differs from the transaction amount stops being flagged. Replaces the amount_mismatch review reason with partial_payment; amounts are unchanged. Scope: write:receipts

PATCH /v1/receipts/{receiptId}/amounts

Correct a receipt’s top-line amounts: totalAmountValue, subtotalValue, taxAmountValue, taxRateValue (a percentage, 19 for 19%) and tipAmountValue. Omit a field to leave it unchanged, send null to clear it; at least one field is required and values must be non-negative. Returns the amounts after the update. A later reparse re-extracts and overwrites them. 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 Query parameters: status (optional), limit (optional), cursor (optional).

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 Query parameters: transactionHash (optional), limit and offset (optional).

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 Query parameters: transactionHash (optional), limit and offset (optional).

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

Scheduled (Recurring) Transactions

Read + lifecycle (pause/resume) endpoints for scheduled transactions, plus proposing one. 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. A proposal is a draft the user activates in the app.

GET /v1/scheduled-transactions

List the user’s scheduled (recurring) transactions. Scope: read:transactions Query parameters: status (optional).

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 Query parameters: limit (optional).

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

List past executions for one schedule. Scope: read:transactions Query parameters: limit (optional), cursor (optional).

POST /v1/scheduled-transactions/propose

Propose a recurring payment. Creates a draft (PENDING_ACTIVATION) and notifies the user, who reviews it and activates it by signing with their passkey in the Moneda app. Nothing is sent until then, and a draft that is not approved within 48 hours expires. Not for one-off payments (use POST /v1/payments). Scope: write:payments paymentType is transfer_moneda (pass recipientUsername) or transfer_contact_wallet (pass contactUsername or contactAccountId; Base wallets only). frequency is DAILY, WEEKLY, BIWEEKLY, MONTHLY or QUARTERLY. Dates are YYYY-MM-DD in the user’s timezone; endDate is optional. Supported currencies: USD, EUR, CHF, CAD. Request body

{
  "paymentType": "transfer_moneda",
  "amount": "50",
  "currency": "USD",
  "frequency": "MONTHLY",
  "startDate": "2026-10-01",
  "recipientUsername": "alice"
}

Response: scheduleId, status (PENDING_ACTIVATION), amount, currency, frequency, startDate, endDate, recipient, expiresAt, notificationSent. Track it with GET /v1/scheduled-transactions/{id}: the status becomes ACTIVE once the user signs.

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

Crypto Conditional Orders

Read and cancel crypto limit, stop-loss, take-profit and trailing-stop orders. Creating an order is NOT exposed via REST: it needs the user’s passkey to sign the Smart Sessions install and the CoW approval, which is mobile-app only.

GET /v1/conditional-orders

List the user’s crypto conditional orders, newest first. Scope: read:transactions Response: { "orders": [...] }. Each order has id, assetSymbol, side, type, status (PENDING_ACTIVATION, ARMED, PUBLISHED, FILLED, CANCELLED, EXPIRED), triggerPrice, trailPercent, sellAmount and minBuyAmount (raw token units), expiresAt, skipReason, createdAt, publishedAt, filledAt.

GET /v1/conditional-orders/{id}

Get one crypto conditional order by id. Scope: read:transactions

POST /v1/conditional-orders/{id}/cancel

Cancel an open order. A PUBLISHED order is live in the CoW order book, so it is withdrawn on-chain first and only then marked CANCELLED; if the withdrawal fails the order stays live and the call returns 500 (retry). Returns 409 for a filled, cancelled or expired order. Scope: write:trades

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 Query parameters: limit (optional), cursor (optional).

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/information-requests

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

​GET /v1/accounts

​GET /v1/contacts

​GET /v1/settings

​API Keys

​GET /v1/api-keys

​POST /v1/api-keys

​DELETE /v1/api-keys/{keyId}

​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/sub-accounts/{id}/proposals

​GET /v1/sub-accounts/proposals/{proposalId}

​POST /v1/sub-accounts/{id}/top-up

​POST /v1/sub-accounts/{id}/withdraw

​POST /v1/sub-accounts/{id}/swap

​POST /v1/sub-accounts/{id}/freeze

​POST /v1/sub-accounts/{id}/proposals

​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/categories/

​GET /v1/knowledge/items/

​Users

​GET /v1/users/search

​Write Endpoints

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/information-requests

GET /v1/virtual-accounts/settlement-estimate

GET /v1/accounts

GET /v1/contacts

GET /v1/settings

API Keys

GET /v1/api-keys

POST /v1/api-keys

DELETE /v1/api-keys/{keyId}

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/sub-accounts/{id}/proposals

GET /v1/sub-accounts/proposals/{proposalId}

POST /v1/sub-accounts/{id}/top-up

POST /v1/sub-accounts/{id}/withdraw

POST /v1/sub-accounts/{id}/swap

POST /v1/sub-accounts/{id}/freeze

POST /v1/sub-accounts/{id}/proposals

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/categories/

GET /v1/knowledge/items/

Users

GET /v1/users/search

Write Endpoints