> ## 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 with Lovable

> Add cross-border payments to your Lovable app: customer onboarding, on-ramp deposits, and transaction tracking via the Lumx API and a copy-paste prompt.

Lovable generates full-stack apps from natural language. Paste the prompt below to scaffold a Lumx-powered backend that creates customers, opens on-ramp transactions, and tracks settlement — without leaking your API key to the browser.

## Prerequisites

* A [Lumx](https://dashboard.lumx.io) account with a Sandbox API key
* A [Lovable](https://lovable.dev) project
* A Supabase project connected to that Lovable app (used to store your Lumx key as a secret)

## Step 1 — Get your Lumx credentials

From the [Lumx Dashboard](https://dashboard.lumx.io), go to **Developers → API Keys** and copy a Sandbox key. See [Authentication](/get-started/authentication) for details. Keys are only shown once — store them somewhere safe before closing the modal.

## Step 2 — Store the key in Lovable

Open your Lovable project's secrets pane (or the Supabase dashboard for the connected project) and add:

| Name           | Value                                                   |
| -------------- | ------------------------------------------------------- |
| `LUMX_API_KEY` | Your Sandbox key from Step 1                            |
| `LUMX_ENV`     | `sandbox` while building, `production` when you go live |

<Warning>
  Never paste your API key into the chat or into client-side code. Lovable will read it from secrets at runtime.
</Warning>

## Step 3 — Paste the prompt

In the Lovable chat, paste the prompt below and let it scaffold the integration.

<Info>
  Lovable doesn't support MCP servers directly, but if you open the same project in Cursor or Claude Code later, connect them to Lumx's [docs MCP](/developer/mcp-server) so the agent can pull endpoint shapes and field definitions without re-reading these guides.
</Info>

```text Lumx integration prompt theme={null}
Build a stablecoin payments backend using the Lumx API. Lumx connects
local banking rails to stablecoins so you can collect, hold, convert,
and pay out money in either form.

Rules
- Read LUMX_API_KEY from environment secrets. Never expose it in
  client-side code. Always call Lumx from server routes.
- Pick the base URL from LUMX_ENV. Default to
  https://api-sandbox.lumx.io. Use https://api.lumx.io when
  LUMX_ENV === "production".
- Send every request with the headers:
    Authorization: Bearer ${LUMX_API_KEY}
    Content-Type: application/json
- On non-2xx responses, surface the Lumx error body and HTTP status.
  Do not retry 4xx.

Server routes to build
1. POST /api/customers — calls Lumx POST /customers. Body: type
   ("INDIVIDUAL" or "BUSINESS"), name, taxId, country (ISO-3), email.
   Returns the Lumx customer record including verification.link.
2. POST /api/on-ramp — calls Lumx POST /transactions/on-ramp. Body:
   customerId, currency (ISO-3), amount (string). Returns the
   rail-specific deposit instructions.
3. GET /api/transactions/:id — calls Lumx GET /transactions/:id and
   returns the transaction's current status and timeline.

UI to build
- Customer onboarding screen: form that calls POST /api/customers,
  then renders verification.link as a button the customer can open
  to complete identity verification.
- On-ramp deposit screen: form that picks a customer, sets a
  currency and amount, calls POST /api/on-ramp, then renders the
  returned deposit instructions.

Reference: https://docs.lumx.io
```

## Step 4 — Test the flow

Lovable will generate routes and a UI. Open the preview, create a sandbox customer, open the verification link, and try an on-ramp deposit. Every transaction you create in Sandbox is fully simulated — no real money moves.

## Example: a server-side Lumx helper

If Lovable's generated code drifts, drop this helper in (or ask Lovable to align to it) so calls stay consistent.

```ts server/lumx.ts theme={null}
const LUMX_BASE =
  process.env.LUMX_ENV === "production"
    ? "https://api.lumx.io"
    : "https://api-sandbox.lumx.io";

async function lumx(path: string, init?: RequestInit) {
  const res = await fetch(`${LUMX_BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.LUMX_API_KEY}`,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });
  if (!res.ok) {
    throw new Error(`Lumx ${res.status}: ${await res.text()}`);
  }
  return res.json();
}

export const createCustomer = (input: {
  type: "INDIVIDUAL" | "BUSINESS";
  name: string;
  taxId: string;
  country: string;
  email: string;
}) => lumx("/customers", { method: "POST", body: JSON.stringify(input) });

export const createOnRamp = (input: {
  customerId: string;
  currency: string;
  amount: string;
}) =>
  lumx("/transactions/on-ramp", {
    method: "POST",
    body: JSON.stringify(input),
  });

export const getTransaction = (id: string) => lumx(`/transactions/${id}`);
```

## FAQ

<AccordionGroup>
  <Accordion title="Why does the prompt force a server route for every call?">
    Lumx API keys carry full account access. A key in client-side code is a key on every visitor's machine. Lovable's server routes (or a Supabase Edge Function) keep it where it belongs.
  </Accordion>

  <Accordion title="Can I use Lovable's Supabase integration to store the key?">
    Yes. Add `LUMX_API_KEY` as a Supabase secret and reference it from a Supabase Edge Function. The prompt's server routes work the same way.
  </Accordion>

  <Accordion title="How do I switch from Sandbox to Production?">
    Replace `LUMX_API_KEY` with a Production key and set `LUMX_ENV=production`. Production access requires a call with the Lumx team — see [Environments](/get-started/environments).
  </Accordion>

  <Accordion title="Which rails does the on-ramp support?">
    The available rails depend on the currency. A BRL on-ramp returns PIX details; USD returns ACH and Fedwire. See [Coverage](/get-started/coverage) for the full list.
  </Accordion>
</AccordionGroup>

## Next steps

* [Create a customer](/guides/create-a-customer) — full reference for the customer payload
* [Webhooks](/developer/webhooks) — subscribe to status changes instead of polling
* [Use cases](/guides/use-cases/global-accounts) — patterns for global accounts, payroll, treasury, and more