> ## 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. # Integrate on-ramps from fiat to stablecoin > Give your coding agent the exact steps, endpoints and enums to build a Lumx on-ramp — quote, create, render payment details, settle on webhooks. Paste this prompt into your coding agent to build a complete fiat-to-stablecoin on-ramp against the Lumx sandbox. The agent creates the customer, quotes the conversion, creates the on-ramp, shows the payer where to send funds, and follows the transaction to settlement. ## Before you start * A Sandbox API key. See [Authentication](/get-started/authentication). * A webhook endpoint registered under **Developers > Webhooks** in the [Dashboard](https://dashboard.lumx.io). See [Webhooks](/developer/webhooks). ## Prompt ```text Prompt theme={null} You are a senior backend engineer adding Lumx on-ramps — fiat in, stablecoin out — to an existing server-side application. 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 explains what the spec leaves untyped. Work against sandbox at https://api-sandbox.lumx.io with a server-side key sent as "Authorization: Bearer ". The key never reaches a client bundle. 1. Create the customer with POST /customers. Request the fiat currencies you need in "accounts" (BRL, USD, EUR, MXN, GBP) — each virtual account is created with the customer and provisions after verification. 2. Wait for verification to reach APPROVED, then read GET /customers/{id} for the "wallets" and "accounts" arrays. In sandbox the last digit of taxId drives the outcome: 1 NOT_STARTED, 2 RFI, 3 FINAL_REJECTION, any other digit APPROVED. 3. Quote with POST /exchange-rates. type LOCKED returns an id and expiresAt under a timelock of 30s, 1m or 5m; type FLOATING prices at execution. Choose one and record why in the code. 4. Create the transaction with POST /transactions/on-ramp in one of the two shapes the spec defines: rail + sourceCurrency + sourceAmount + targetCurrency + purpose, or exchangeRateId + purpose. Send an Idempotency-Key header with a UUID v4 you persist before sending, so a retry reuses it. 5. Render state.payment from the response for the payer. Its shape follows the rail — brCode for PIX; an identifier plus holder for bank rails, such as iban and bic for SEPA or sortCode and accountNumber for FPS. The spec types it as a free-form object, so take field names from the examples on /api-reference/transactions/on-ramp and flag any field you cannot find there instead of inventing one. 6. Drive the lifecycle from webhooks: onramp.awaiting_funds, onramp.transferring_fiat, onramp.trading, onramp.transferring_stablecoin, onramp.success, onramp.failed, onramp.expired. Confirm with GET /transactions/{id} before you credit anything in your own product. Constraints: - Read the purpose enum from the request schema. The response schema in the spec lists different values; use the request enum and flag the mismatch. - PERSONAL_ACCOUNT is only valid with SELF-relationship destinations. - Do not cache a wallet address. The docs do not state that it is permanent — read it when you use it and flag the question. - Amounts are decimal strings, never numbers. - Do not state a rate limit. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff. Deliverables: - A typed client for the five endpoints above. - A webhook handler covering the seven onramp.* events, idempotent on webhook-id. - A sandbox script that runs one on-ramp end to end and prints every status change. - A list of every field you could not confirm in either source. ``` ## How to use 1. Create a sandbox key in the Dashboard under Developers → API Keys and export it in your shell. The agent never creates the key. 2. Register a webhook endpoint under Developers → Webhooks, pointing at a tunnel to your machine, before you run the script. 3. Read the agent's list of unconfirmed fields and decide each one yourself — that list is where a wrong integration would start. ## What the prompt builds | **Endpoint** | **What the agent uses it for** | | :- | :- | | `POST /customers` | Creates the customer and requests its virtual accounts | | `GET /customers/{id}` | Reads verification status, wallets, and accounts | | `POST /exchange-rates` | Quotes the conversion, locked or floating | | `POST /transactions/on-ramp` | Creates the on-ramp and returns the payment details | | `GET /transactions/{id}` | Confirms the final status before crediting your product | ## Errors to expect These codes come from the [errors catalog](/developer/errors), 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. | | `EXCHANGE_RATE_EXPIRED` | 422 | Locked rate has expired. | | `MINIMUM_AMOUNT_NOT_MET` | 422 | Amount is below the supported minimum for the currency. | | `TRANSACTION_LIMIT_EXCEEDED` | 422 | Exceeds the customer's single, daily, or monthly limit. | | `IDEMPOTENCY_KEY_CONFLICT` | 409 | Same `Idempotency-Key` reused with a different body. | ## Related resources Transaction types and status progressions. Locked and floating quotes. Pay out from a stablecoin balance to a local bank account. Receive signed events that survive retries and secret rotation. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.