Skip to main content
A locked exchange rate returns a guaranteed FX quote for a limited time window.
The response includes an exchangeRateId and expiresAt. Use this ID to execute the on/off-ramp before it expires; attempts after expiry will be rejected.
Locked rates may include a premium or wider spread that depends on the selected lock duration and market conditions (longer locks typically cost more). If you don’t require guaranteed pricing, consider using a floating exchange rate instead.

​
Process overview

1

Request a locked rate

Request a guaranteed rate with a specified lock-in duration.
2

Receive the rate ID

Get exchangeRateId plus expiresAt (UTC).
3

Execute before expiry

Start the on-ramp or off-ramp using the exchangeRateId.
4

Complete the transaction

The transaction settles at the locked rate.

​
Create a locked rate

Call /exchange-rates with "type": "locked".
You can pass a partnerFeeId to bake partner fees into the rate.
Request
curl -X POST https://api.lumx.io/exchange-rates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "LOCKED",
    "sourceCurrency": "BRL",
    "sourceAmount": "5925.55",
    "targetCurrency": "USDC",
    "targetAmount": "1000.00",
    "timeLock": "5m"
  }'
Parameters
ParameterTypeRequiredDescription
typestringYesMust be "LOCKED".
sourceCurrencystringYesCurrency code to convert from (e.g., BRL, USDC, USDT).
sourceAmountstringYesAmount in sourceCurrency (string for decimal precision).
targetCurrencystringYesCurrency code to convert to (e.g., USDC, BRL, USDT).
targetAmountstringYesDesired amount in the targetCurrency.
timeLockstringNoQuote validity window: 30s (no additional fees), 1m, or 5m. Default: 30s.
partnerFeeIdstringNoUUID of the partner fee to apply. If omitted and a default exists, that fee will be used.
Response
{
	"id": "123e4567-e89b-12d3-a456-426614174001",
	"type": "LOCKED",
	"expiresAt": "2026-05-05T00:05:00Z",
	"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": "1000.000000",
	"finalExchangeRate": "5.9255"
}
Fields
FieldDescription
idThe exchangeRateId to use when executing the transaction.
typeExchange rate type (LOCKED).
expiresAtUTC timestamp when the locked quote expires.
sourceCurrencyCurrency being converted from.
sourceAmountAmount in source currency.
targetCurrencyCurrency being converted to.
baseTargetAmountTarget amount before fees.
baseExchangeRateBase FX before fees.
feesBreakdown of Lumx and partner fees (rate in bps).
finalTargetAmountTarget amount after fees (guaranteed for the lock window).
finalExchangeRateEffective rate including fees.

​
Time lock options

  • 30s — 30 seconds (default)
  • 1m — 1 minute
  • 5m — 5 minutes

​
Use a locked rate in transactions

Pass the exchangeRateId when creating the transaction. You do not need to include currencies/amounts again; they are derived from the locked quote.

​
On-ramp (locked)

Request
curl --request POST \
  --url https://api.lumx.io/transactions/on-ramp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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 (locked)

Request
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",
    "exchangeRateId": "123e4567-e89b-12d3-a456-426614174001",
    "payment": {
      "rail": "PIX",
      "keyType": "CPF",
      "keyValue": "123.456.789-00"
    }
  }'
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": {
    "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"
}
Locked quotes are single-use and must be executed before expiresAt.

​
Next steps