​
Overview

Lumx provides two ways to deal with currency conversions used in on-ramp and off-ramp transactions:
  • Floating rate — market-aligned pricing determined at execution time.
  • Locked rate — a guaranteed quote you reserve for a short time window and then execute with its exchangeRateId.
Both rate types return the base FX, a fee breakdown (Lumx + optional Partner Fee), and the effective (final) rate/amount you’ll settle at.

​
How exchange rates are used

You can request a rate, review it, and then create a transaction.

​
Floating Rate (typical flow)

1

Request a floating rate

Call the exchange rate endpoint with "type": "FLOATING" and the intended currencies/amount.
2

Review rate

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

Execute transaction

Create the on-/off-ramp with currencies/amounts; the effective rate is evaluated at execution.
See the guide: Use a floating exchange rate.

​
Locked Rate (typical flow)

1

Lock a rate

Call the rates endpoint with "type": "LOCKED" and a timeLock (e.g., 30s, 1m, 5m).
2

Receive ID and expiry

You get an exchangeRateId and expiresAt (UTC).
3

Execute before expiry

Create the on-/off-ramp passing the exchangeRateId. The transaction settles at the locked rate.
See the guide: Use a locked exchange rate.

​
When to use each

​
Floating — use when you want:

  • Immediate execution and market-aligned pricing
  • Simpler UX (no lock countdowns)
  • No lock premium

​
Locked — use when you need:

  • Price certainty before asking a user to pay/approve
  • Exact amounts displayed in UI/quotes/invoices
  • Multi-step or approval flows that can’t tolerate drift

​
Time lock options (locked rates)

  • 30s — fast confirmations / automated flows (default)
  • 1m — standard user interactions
  • 5m — multi-step approvals

​
Key characteristics

FeatureFloating rateLocked rate
Rate guaranteeNoYes (for lock window)
Lock durationN/A30s, 1m, 5m
Amount inputsSource or target amountSource and/or target amount (per your flow)
Quote ID (exchangeRateId)Not usedRequired
ExpirationNoYes (expiresAt)
FeesLumx + optional partnerLumx + optional partner (lock may include premium)
Best forImmediate exec, low frictionGuaranteed pricing, exact user quotes

​
What’s inside an exchange rate

A rate response (floating or locked) provides:
  • Base rate — the pre-fee rate between the pair.
  • Fees — broken down by Lumx and (optionally) partner (percentage in bps and/or flat).
  • Final amounts/rate — effective values after fees; these are the numbers that matter for the transaction.
  • For locked: id (your exchangeRateId) and expiresAt.
Exact field names and examples are shown in the step-by-step guides.

​
How pricing works (at a glance)

  • Floating: priced at execution based on current liquidity; fees are applied to derive the effective rate.
  • Locked: priced upfront, then reserved; may include a lock premium that scales with the lock duration and live market conditions.
Keep lock windows as short as your UX allows to minimize premium and expiry risk.

​
Common errors & handling

  • rate_expired — The locked quote expired before execution. Request a new locked rate or switch to a floating rate.
  • invalid_exchangeRateId — The ID is unknown or already used (locked quotes are single-use).
  • unsupported_pair — The currency pair combination isn’t valid; adjust inputs.
For transaction-level errors (e.g., payment/funding expiry, invalid payout details), see the specific guides:

​
Best practices

  • Choose the simplest path: prefer floating unless the user or workflow requires a guaranteed number.
  • Short locks win: use the smallest timeLock that fits your UX to reduce premium and timeout risk.
  • Show a countdown (locked): display time remaining to pay/approve; disable the action on expiry.
  • Don’t reuse IDs: every locked exchangeRateId is single-use; request a new one per transaction.
  • Keep amounts as strings: preserve decimal precision end-to-end.