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

1

Request a rate

Get the current FX between two currencies.
2

Review the rate

Inspect base rate, fees, and the effective (final) rate.
3

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".
Request
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"
}'
Each request returns the current best FX and fee breakdown, and the effective rate is evaluated at the time the transaction executes.
Parameters
ParameterTypeRequiredDescription
typestringYesMust be "floating".
sourceCurrencystringYesCurrency code to convert from (e.g., BRL, USDC).
sourceAmountstringYesAmount in sourceCurrency (string for decimal precision).
targetCurrencystringYesCurrency code to convert to (e.g., USDC, BRL).
partnerFeeIdstringNoPartner fee to apply. If omitted and a default exists, it will be used.
Response
{
  "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"
}
Fields
FieldDescription
typeExchange rate type (floating).
sourceCurrencyCurrency being converted from.
sourceAmountAmount in source currency.
targetCurrencyCurrency being converted to.
baseTargetAmountTarget amount before fees.
baseExchangeRateBase FX before fees.
fees.lumxLumx fees (rate in bps, flatAmount and totalAmount in fees.lumx.currency).
fees.partnerPartner fees (if partnerFeeId provided or a default fee is configured).
finalTargetAmountTarget amount after all fees.
finalExchangeRateEffective 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)

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"
  }'
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": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
    }
  },
  "createdAt": "2024-03-20T15:30:00Z",
  "updatedAt": "2024-03-20T15:30:05Z"
}

​
Off-ramp (floating)

Response
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"
  }'
Response
{
  "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": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}
The partnerFeeId is optional. If not provided, default fees apply.

​
Next steps