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

# Build a multi-currency neobank app

> A copy-paste prompt that builds the skeleton of a neobank app on Lumx — onboarding, named accounts in BRL, MXN, USD, EUR and GBP, balances, money in and out.

Paste this prompt into your coding agent to build the whole neobank skeleton at once: verified users, named accounts, a stablecoin balance, and money in and out. The agent builds the backend and screens for onboarding, accounts, balance, adding and sending money, and an activity feed, with one Lumx customer per app user.

## Before you start

* A Sandbox API key. See [Authentication](https://docs.lumx.io/get-started/authentication.md).
* The currencies your users need, and how your product is authorized to hold customer balances where you operate. See [Nested payments](https://docs.lumx.io/compliance/nested-payments.md).
* A webhook endpoint registered under **Developers > Webhooks** in the [Dashboard](https://dashboard.lumx.io). See [Webhooks](https://docs.lumx.io/developer/webhooks.md).

## Prompt

```text Prompt theme={null}
You are a senior full-stack engineer building the skeleton of a multi-currency neobank app on Lumx: verified users, named accounts in several currencies, a stablecoin balance, and money in and out over local rails.

Ground truth. Read both before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index. Every page has a .md twin at its own path.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. Take field names, required flags and enum values from here; the prose carries the lifecycle and the rules the spec does not.

Work against sandbox at https://api-sandbox.lumx.io with a server-side key sent as "Authorization: Bearer <key>". The key never reaches the app client: build a thin backend the app calls.

1. Lay out five screens over one user: Onboarding, Accounts, Balance, Add money and Send money, plus an Activity feed. One app user is one Lumx customer, always. Never pool several users in one customer — read /compliance/nested-payments first.
2. Onboard with POST /customers: type INDIVIDUAL or BUSINESS and an "accounts" array drawn from BRL, MXN, USD, EUR and GBP. Request only the currencies the user picked, and make GBP an optional toggle, not a default. Individuals are supported in the countries listed at https://lumx.io/legal/legal-and-privacy/supported-countries, not only Brazil. The spec's INDIVIDUAL country enum currently lists fewer values than that. Send the user's real country, and if the API rejects it for an individual, surface the error instead of working around it. Then call POST /customers/{id}/tos with a JSON body, open the returned url as a redirect, and once terms are accepted read verification.link from GET /customers/{id} and send the user there for KYC or KYB. Do not rebuild document upload.
3. Drive the status screen from webhooks and confirm by reading the API. Customer events run customer.under_verification, customer.rfi, customer.approved and customer.final_rejection. Account events run account.awaiting_onboarding through account.active. Read account status from GET /accounts?customerId={id} and handle RFI and REJECTED. Show a pending account, never a missing one.
4. Accounts screen: once an account is ACTIVE, create one POST /autoconversion-rules per account with targetCurrency USDC or USDT, a purpose and a name, and render sourceDepositInfo per rail: brCode for PIX, clabe plus reference for SPEI, accountNumber with routingNumber for ACH and FEDWIRE, iban plus bic for SEPA, sortCode plus accountNumber for FPS. Respect the one-active-rule limit on USD, EUR and GBP accounts.
5. Balance screen: a deposit converts to stablecoin and lands in the customer's wallet, so the balance is one stablecoin balance, not one per currency. GET /accounts carries no balance. Read wallets[].balances with GET /customers/{id}?includeBalances=true after approval, since wallets are absent before it.
6. Send money: register the payee with POST /destinations on the rail the currency implies — PIX, SPEI, ACH, FEDWIRE, SEPA or FPS — with a true holder.relationship, SELF for the user's own account. Quote with POST /exchange-rates, then pay with POST /transactions/off-ramp and an Idempotency-Key you stored first.
7. Activity feed: persist the onramp.* and offramp.* webhook events per customer, dedupe on webhook-id, and confirm each with GET /transactions/{id} before showing it as settled.

Constraints:
- Call the product a balance with account details, never a bank account or a deposit, and promise no deposit insurance. Lumx wallets are custodial and Lumx is not a bank.
- Read limits from GET /customers/{id}?includeTransactionLimits=true. Do not hardcode a limit or a settlement time; take timings from the cut-off page in the docs.
- Amounts are decimal strings. Do not state a rate limit; none is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.

Deliverables:
- A backend with onboarding, account, balance, send and webhook modules behind the app.
- Screens for the five flows and the feed, with pending, RFI and rejected states.
- A sandbox script that onboards a user with BRL and USD and prints each status change.
- A list of every field you could not confirm in either source.
```

## How to use

1. Decide which currencies your users need before you run this; every currency you request becomes an account your users and your compliance reviewer will ask about.
2. Settle with your compliance advisers how your product is authorized to hold customer balances where you operate. The agent builds screens, not your regulatory structure.
3. Create the sandbox key and register your webhook endpoint yourself, then run the sandbox script before you show a screen to anyone.

## What the prompt builds

| **Endpoint** | **What the agent uses it for** |
| :- | :- |
| `POST /customers` | Creates the user as a customer and requests the currencies they picked |
| `POST /customers/{id}/tos` | Returns the terms of service link to open as a redirect |
| `GET /customers/{id}` | Reads the verification link, wallets, balances, and limits |
| `GET /accounts` | Reads each account's status for the Accounts screen |
| `POST /autoconversion-rules` | Returns the deposit details to show for each account |
| `POST /destinations` | Registers the bank account a user sends money to |
| `POST /exchange-rates` | Quotes a send before the user confirms |
| `POST /transactions/off-ramp` | Sends the money with an idempotency key |
| `GET /transactions/{id}` | Confirms each transaction before the feed shows it as settled |

Wallets are custodial and the balance is stablecoin in the user's wallet, not a bank deposit. Accounts carry deposit details, not balances. See [Wallets](https://docs.lumx.io/concepts/wallets.md).

## Errors to expect

These codes come from the [errors catalog](https://docs.lumx.io/developer/errors.md), for the resources this prompt uses. Match on `code`, not on `message`.

| **Code** | **Status** | **When it happens** |
| :- | :- | :- |
| `KYC_NOT_APPROVED` | 403 | Customer identity verification (KYC/KYB) is not approved. |
| `ACCOUNT_NOT_ACTIVE` | 409 | Account is not in a usable state. |
| `RAIL_NOT_ENABLED` | 403 | Rail is not enabled for this project. |
| `INSUFFICIENT_BALANCE` | 422 | Balance is too low for the operation. |
| `TRANSACTION_LIMIT_EXCEEDED` | 422 | Exceeds the customer's single, daily, or monthly limit for that transaction type. |
| `AUTOCONVERSION_RULE_ALREADY_EXISTS` | 409 | Customer already has an active USD, EUR, or GBP autoconversion rule. |

## Related resources

> [card] [Accounts](https://docs.lumx.io/concepts/accounts.md)
>
> Virtual accounts, provisioning, and status.

> [card] [Wallets](https://docs.lumx.io/concepts/wallets.md)
>
> Custodial wallets and balances.

> [card] [Integrate customer onboarding and verification](https://docs.lumx.io/prompts/integrate-customer-onboarding.md)
>
> Take a business or individual from signup to an approved customer.

> [card] [Integrate local-currency virtual accounts](https://docs.lumx.io/prompts/integrate-virtual-accounts.md)
>
> Collect in local currency through accounts in your customer's name.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.