> ## 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 v0

> Generate a Lumx-powered Next.js app from v0: customer onboarding, on-ramp deposits, and transactions with server actions, Vercel env vars, and a copy-paste prompt.

v0 by Vercel generates Next.js apps from chat. Paste the prompt below and v0 will scaffold a Lumx integration with server actions for customer onboarding, on-ramp deposits, and transaction status — ready to deploy to Vercel without leaking your API key to the browser.

## Prerequisites

* A [Lumx](https://dashboard.lumx.io) account with a Sandbox API key
* A [v0](https://v0.dev) chat
* A [Vercel](https://vercel.com) project for the generated app (created automatically when you click **Deploy** from v0)

## Step 1 — Get your Lumx credentials

From the [Lumx Dashboard](https://dashboard.lumx.io), open **Developers → API Keys** and copy a Sandbox key. See [Authentication](/get-started/authentication). Keys are only shown once.

## Step 2 — Store the key as Vercel env vars

In your Vercel project, go to **Settings → Environment Variables** and add:

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

Mark them **Server-side only**. v0's generated server actions and route handlers will pick them up automatically on the next deploy.

<Warning>
  Don't paste your API key into the v0 chat — v0 messages are not a secret store. Add the key in the Vercel dashboard instead.
</Warning>

## Step 3 — Paste the prompt

In the v0 chat, paste:

<Info>
  v0 doesn't support MCP servers directly. Once you pull the generated repo into Cursor or Claude Code for follow-up work, connect them to Lumx's [docs MCP](/developer/mcp-server) so the agent can pull endpoint shapes and field definitions on demand.
</Info>

```text Lumx integration prompt theme={null}
Build a Next.js (App Router) stablecoin payments app that uses the
Lumx API. Lumx connects local banking rails to stablecoins so I can
collect, hold, convert, and pay out money in either form.

Rules
- Read LUMX_API_KEY from process.env. It must stay server-side — use
  it from server actions and route handlers only, never in a "use
  client" file.
- 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 actions / route handlers 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 (App Router pages)
- /onboarding: form that submits to the customer server action, then
  renders verification.link as a button the customer can open.
- /on-ramp: form that picks a customer, sets a currency and amount,
  calls the on-ramp action, then renders the returned deposit
  instructions in a clean card layout.

Style: shadcn/ui components, Tailwind, light mode default.

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

## Step 4 — Deploy and test

Click **Deploy** in v0 (or push from the connected GitHub repo). Once the build picks up the env vars, walk the flow in the deployed preview: create a sandbox customer, open the verification link, and start an on-ramp.

## Example: a server-side Lumx helper

The prompt aims for this shape. If v0's generated code diverges, ask it to align to the helper below.

```ts lib/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="Where do server actions read the env vars from?">
    Locally, from `.env.local`. On Vercel, from the env vars you set in the project. Both reach `process.env` at runtime — the key never leaves the server.
  </Accordion>

  <Accordion title="v0 put my key in a 'use client' file. What now?">
    Move the call into a server action (`"use server"`) or a route handler. Client components should call those, not Lumx directly. Ask v0 to "convert the Lumx call into a server action" and it will reshuffle the boundary.
  </Accordion>

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

  <Accordion title="Can I preview locally before deploying?">
    Yes. Run `vercel env pull` to copy the project env into `.env.local`, then `pnpm dev` (or `npm run dev`). The server actions will read the same key.
  </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