​
Overview

An on-ramp converts fiat money paid by a customer into a stablecoin delivered to the customer’s wallet. You can use floating rates (market-aligned at execution) or locked rates (guaranteed for a short window).

​
Prerequisites

Before initiating an on-ramp transaction:
  1. Verified Customer — Customer must be KYC-approved (see onboarding).
  2. Exchange Rate (optional) — Choose a floating or locked quote.
  3. Partner Fee (optional) — Configure custom fees (see partner fees).
  4. Currencies & rails — Use any supported fiat currency as source and any supported stablecoin as target on any supported payment rail (examples below are illustrative only).
Refer to supported currencies, blockchains, and rails.

​
Transaction Overview

1

Initiate On-Ramp

Create the transaction with an amount and currencies (floating rate), or pass a locked exchangeRateId .
2

Receive Deposit Instructions

Get rail-specific payment details (e.g., a QR Code or bank account info) and the payment time window.
3

Fiat Deposit

The customer sends a deposit following the given instructions and time limit.
4

Deposit Confirmation

Lumx matches your customer’s deposit to the transaction you created.
5

Stablecoin Transfer

The target stablecoin is credited to the customer’s wallet.

​
Creating an On-Ramp Transaction

​
Option 1: Floating Rate

Use current market rates determined at execution time:
Request
curl -X POST https://api.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sourceCurrency": "BRL",
    "sourceAmount": "10000.00",
    "targetCurrency": "USDC",
    "payment": { "rail": "PIX" },
    "partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
  }'
Parameters
ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
sourceCurrencystringYesFiat ISO code (e.g., BRL)
sourceAmountstringYesAmount in sourceCurrency
targetCurrencystringYesAsset code (e.g., USDC, USDT, or other supported stablecoins)
payment.railstringYesPayment rail (e.g., PIX)
partnerFeeIdstringNoOptional partner fee configuration
Note: Currencies and rails above are examples only. Your integration can use other supported currencies/assets/rails without changing the schema.

​
Option 2: Locked Rate

Use a pre-locked exchange rate for guaranteed conversion:
Request
curl -X POST https://api.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "exchangeRateId": "123e4567-e89b-12d3-a456-426614174000",
    "payment": { "rail": "PIX" }
  }'
Parameters
ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
exchangeRateIdstringYesID of the locked exchange rate (use before expiresAt)
payment.railstringYesPayment rail (e.g., PIX)
When using exchangeRateId, you don’t need to input currencies/amounts; they’re derived from the locked rate you got earlier. Attempts after expiry will be rejected.
Response
{
	"id": "123e4567-e89b-12d3-a456-426614174000",
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"type": "ON_RAMP",
	"request": {
		"sourceCurrency": "BRL",
		"sourceAmount": "10000.00",
		"targetCurrency": "USDC",
		"payment": { "rail": "PIX" }
	},
	"state": {
		"status": "AWAITING_FUNDS",
		"payment": {
			"rail": "PIX",
			"brCode": "0002012658...6304ABCD"
		}
	},
	"createdAt": "2025-08-18T15:30:00Z",
	"updatedAt": "2025-08-18T15:30:05Z"
}
Other On-Ramp Statuses 
{
	"id": "123e4567-e89b-12d3-a456-426614174000",
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"type": "ON_RAMP",
	"request": {
		"sourceCurrency": "BRL",
		"sourceAmount": "10000.00",
		"targetCurrency": "USDC",
		"payment": { "rail": "PIX" }
	},
	"state": {
		"status": "TRANSFERRING_FIAT",
		"payment": {
			"rail": "PIX",
			"brCode": "0002012658...6304ABCD"
		}
	},
	"createdAt": "2025-08-18T15:30:00Z",
	"updatedAt": "2025-08-18T15:30:05Z"
}
Key Response Fields
FieldDescriptionPresent when
idUnique transaction identifierall statuses
customerIdCustomer identifierall statuses
state.statusCurrent status: AWAITING_FUNDS → TRANSFERRING_FIAT → TRADING → TRANSFERRING_STABLECOIN → SUCCESS/FAILEDall statuses
state.payment.railPayment rail used for funding (e.g., PIX)all statuses
state.payment.brCodeRail-specific payment data (e.g., Pix Copia e Cola / QR content)all statuses
state.receipt.*Conversion breakdown after settlement: rate, sourceAmount, targetAmount, currencies, feesSUCCESS
state.receipt.fees.lumx.*Lumx fee components (e.g., rate, flat, currency)SUCCESS
state.receipt.fees.partner.*Partner fee components (if configured)SUCCESS
state.transactionHashHash of the on-chain delivery transactionSUCCESS
state.blockExplorerUrlLink to view the on-chain transactionSUCCESS
Field availability is status-dependent. For locked quotes, ensure the transaction is created and funded before the rate’s expiresAt; otherwise, the transaction will be rejected or end up as failed.

​
On-ramp states

FieldDescription
AWAITING_FUNDSWaiting for the customer’s payment on the selected rail; see state.payment.* (e.g., brCode).
TRANSFERRING_FIATPayment confirmed; conversion and delivery in progress.
TRADINGTrading for stablecoin is happening.
TRANSFERRING_STABLECOINTransfering the funds to the customer’s wallet.
SUCCESSTransaction has been settled and the customer has received the funds.
FAILEDTransaction failed/expired; check state.error if present.
REFUNDINGtransaction has failed and funds will be sent back to the bank account of origin.
REFUNDEDfunds have been successfully sent back.

​
Transaction Monitoring

Once we receive the deposit for your transaction, we will move the funds to the destination. You can use the API to check the state of the transaction or listen to webhooks.

​
Next steps