> ## 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 Bolt.new

> Scaffold a Lumx integration in Bolt.new: customer onboarding, on-ramp deposits, and transactions via the Lumx API and a copy-paste prompt — with your key kept server-side.

Bolt.new builds full-stack apps in your browser on StackBlitz. Paste the prompt below to scaffold a Lumx integration with a server runtime, server-side helpers, and a starter UI — so your API key stays out of the bundle that ships to users.

## Prerequisites

* A [Lumx](https://dashboard.lumx.io) account with a Sandbox API key
* A [Bolt.new](https://bolt.new) project
* Familiarity with how StackBlitz exposes env vars to your runtime (Node, Next.js, Astro, etc.)

## 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 in Bolt

Open the **`.env`** file in the Bolt file tree (create it if missing) and add:

```bash .env theme={null}
LUMX_API_KEY=lumx_sk_sandbox_xxxxxxxxxxxxxxxx
LUMX_ENV=sandbox
```

Bolt's runtime will pick these up on the next preview reload. If your stack needs a different prefix (for example `PRIVATE_LUMX_API_KEY` in some frameworks), use that — but never use a prefix that exposes the value to the client (no `VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, etc.).

<Warning>
  Don't paste your API key into the Bolt chat. Add it to `.env` directly and keep that file out of any export or share link.
</Warning>

## Step 3 — Paste the prompt

In the Bolt chat, paste:

<Info>
  Bolt doesn't support MCP servers directly. Once you pull the generated project into Cursor or Claude Code locally, 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 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 the runtime's server env. It must stay
  server-side — do not bake it into the client bundle. Never use a
  framework prefix that exposes env vars to the browser (no VITE_,
  NEXT_PUBLIC_, PUBLIC_, etc.).
- 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.
- 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 — Run the preview

Bolt will scaffold the project, install dependencies, and open the preview. Walk the flow once: create a customer, open the verification link, and start an on-ramp. Watch the network panel — `LUMX_API_KEY` should never appear in any client request.

## Example: a server-side Lumx helper

If Bolt's generated code drifts, ask it to align to this helper.

```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="How do I keep the key out of the bundle in Vite-based projects?">
    Skip the `VITE_` prefix. Vite only exposes prefixed vars to the client. Read `LUMX_API_KEY` from a server file (an API route, a server action, a backend route) that never imports into the client tree.
  </Accordion>

  <Accordion title="Can I share my Bolt project link with a teammate?">
    Yes — but the share link includes everything in the file tree. Remove `.env` (or replace its values with placeholders) before sharing, then re-add the real key locally. Rotate the key in the Dashboard if it ever leaks.
  </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="Bolt is asking for a database. Do I need one?">
    Not for this scaffold — every piece of state lives in Lumx. Skip the database prompt unless you want to persist your own customer IDs or transaction history alongside Lumx's.
  </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