Use a floating exchange rate when you want market-aligned pricing without locking a rate. The effective rate is determined when the on-ramp or off-ramp executes. This keeps integrations simple for flows that can tolerate minor price drift and focus on getting the best possible price—if you need guaranteed pricing, use a locked exchange rate instead.
Process overview
Request a rate
Get the current FX between two currencies.
Review the rate
Inspect base rate, fees, and the effective (final) rate.
Execute the transaction
Create an on-ramp or off-ramp using currencies/amounts directly.
Request a floating rate
Use the /exchange-rates
endpoint with "type": "FLOATING"
.
curl --request POST \
--url https://api.lumx.io/transactions/exchange-rates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"type": "FLOATING",
"sourceCurrency": "BRL",
"sourceAmount": "60000.00",
"targetCurrency": "USDC",
"partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
}'
See all 11 lines
Each request returns the current best FX and fee breakdown, and the
effective rate is evaluated at the time the transaction executes .
Parameters
Parameter Type Required Description type
string
Yes Must be "FLOATING"
. sourceCurrency
string
Yes Currency code to convert from (e.g., BRL
, USDC
). sourceAmount
string
Yes Amount in sourceCurrency
(string for decimal precision). targetCurrency
string
Yes Currency code to convert to (e.g., USDC
, BRL
). partnerFeeId
string
No Partner fee to apply. If omitted and a default exists, it will be used.
{
"type" : "FLOATING" ,
"sourceCurrency" : "BRL" ,
"sourceAmount" : "5925.55" ,
"targetCurrency" : "USDC" ,
"baseTargetAmount" : "1000.000000" ,
"baseExchangeRate" : "5.9255" ,
"fees" : {
"lumx" : {
"rate" : "10" ,
"flatAmount" : "1" ,
"totalAmount" : "11" ,
"currency" : "USDC"
},
"partner" : {
"rate" : "10" ,
"flatAmount" : "1" ,
"totalAmount" : "11" ,
"currency" : "USDC"
}
},
"finalTargetAmount" : "978.000000" ,
"finalExchangeRate" : "6.0567"
}
See all 24 lines
Fields
Field Description type
Exchange rate type (FLOATING
). sourceCurrency
Currency being converted from. sourceAmount
Amount in source currency. targetCurrency
Currency being converted to. baseTargetAmount
Target amount before fees. baseExchangeRate
Base FX before fees. fees.lumx
Lumx fees (rate in bps , flatAmount
and totalAmount
in fees.lumx.currency
). fees.partner
Partner fees (if partnerFeeId
provided or a default fee is configured). finalTargetAmount
Target amount after all fees. finalExchangeRate
Effective FX including fees (derived from finalTargetAmount / sourceAmount
).
Use floating rates in transactions
You do not pass an exchangeRateId
. The API computes the effective rate when the transaction executes.
On-ramp (floating)
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"
}'
See all 13 lines
{
"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" : "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
}
},
"createdAt" : "2024-03-20T15:30:00Z",
"updatedAt" : "2024-03-20T15:30:05Z"
}
See all 22 lines
Off-ramp (floating)
curl -X POST https://api.lumx.io/transactions/off-ramp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "123e4567-e89b-12d3-a456-426614174000",
"sourceCurrency": "USDC",
"sourceAmount": "1000.00",
"targetCurrency": "BRL",
"payment": {
"rail": "PIX",
"keyType": "CPF",
"keyValue": "123.456.789-00"
},
"partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
}'
See all 15 lines
{
"id" : "123e4567-e89b-12d3-a456-426614174000",
"customerId" : "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type" : "OFF_RAMP",
"request" : {
"sourceCurrency" : "USDC",
"targetCurrency" : "BRL",
"amount" : "10000.00",
"payment" : {
"rail" : "PIX",
"keyType" : "CPF",
"keyValue" : "123.456.789-00"
}
},
"state" : {
"status" : "TRANSFERRING_STABLECOIN"
"payment" : {
"rail" : "PIX",
"keyType" : "CPF",
"keyValue" : "123.456.789-00"
}
},
"createdAt" : "2023-11-07T05:31:56Z",
"updatedAt" : "2023-11-07T05:31:56Z"
}
See all 25 lines
The partnerFeeId
is optional. If not provided, default fees apply.
Next steps