Overview

A transaction is how value moves through Lumx. There are three types:
  • On-Ramp — convert fiat to a stablecoin and deliver it to a wallet.
  • Off-Ramp — convert a stablecoin to fiat and pay it out via a rail.
  • Transfer — move a stablecoin from one customer to another or to an external wallet.
Use any supported fiat, asset, network, and rail configured for your account. Refer to supported currencies, blockchains, and rails.

Transaction anatomy

Every transaction returns a consistent envelope with type-specific details.
{
	"id": "uuid",
	"customerId": "uuid",
	"type": "ON_RAMP | OFF_RAMP | TRANSFER",
	"request": {
		/* input params for this transaction */
	},
	"state": {
		"status": "AWAITING_FUNDS | PROCESSING | SUCCESS | FAILED..",
		"payment": {
			/* rail-specific fields, e.g., brCode for Pix */
		},
		"receipt": {
			/* rate, amounts, fees (after settlement), transactionHash */
		},
		"error": {
			/* optional error object */
		}
	},
	"createdAt": "ISO-8601",
	"updatedAt": "ISO-8601"
}
Field presence is status-dependent and varies by type. See the type guides for full examples.

Statuses by type

On-Ramp

  • AWAITING_FUNDS — waiting for the customer’s deposit on the selected payment rail (state.payment.*).
  • TRANSFERRING_FIAT — deposit identified; confirming fiat settlement.
  • TRADING — funding confirmed; converting source fiat currency to the target stablecoin.
  • TRANSFERRING_STABLECOIN — sending stablecoin to the destination wallet.
  • SUCCESS — stablecoin delivered; state.receipt.* and, when applicable, state.blockchain.*.
  • FAILED — transaction failed/expired; see state.error if present.

Off-Ramp

  • TRANSFERRING_STABLECOIN — pulling funds from the source stablecoin.
  • TRADING — funding confirmed; converting source stablecoin to the target fiat currency.
  • TRANSFERRING_FIAT — fiat payout in progress.
  • SUCCESS — fiat settled on the selected payment rail; state.receipt.*.
  • FAILED — transaction failed/expired; see state.error.

Transfer

  • PROCESSING — on-chain submission/confirmation in progress.
  • SUCCESS — transfer confirmed on-chain; state.blockchain.transactionHash and blockExplorerUrl.
  • FAILED — transfer failed (e.g., insufficient funds, invalid address, network error); see state.error.

Lifecycles (at a glance)

  • On-Ramp: create → deposit instructions → customer funds fiat → deliver stablecoin.
  • Off-Ramp: create → provide payout details → customer funds stablecoin → pay out fiat.
  • Transfer: create → on-chain transfer → confirm.

Exchange rates & amounts

Transactions may use floating or locked exchange rates:
  • Floating — priced at execution; simpler UX; no lock premium.
  • Lockedguaranteed for a short window; comes with an exchangeRateId and expiresAt; may include a lock premium that depends on lock duration and market conditions.
See: Floating Exchange RateLocked Exchange Rate.

Fees

Both transaction and rate responses show transparent fees:
  • Lumx fees — percentage (bps) and/or flat, in a defined currency.
  • Partner fees — optional via partnerFeeId.
Final delivered amounts are reflected in state.receipt.* on success.

Retries

Safe to poll by transaction ID and/or subscribe to webhooks for status changes. See Webhooks.

Common errors

  • Payments/Funding: payment_expired, insufficient balance/funding not received.
  • Delivery/Payout: invalid delivery address/payout fields, rail constraints.
  • Transfers: invalid address format, insufficient funds, network errors.
Handle errors by showing clear UI, offering retry (new quote or new payment), and preventing duplicate submissions (idempotency).

Best practices

  • Pick the simplest pricing: use floating unless your UI or workflow needs a guaranteed amount.
  • Short locks (if using locked): keep timeLock minimal to reduce premium and expiry risk.
  • Show timers where relevant (payment window, lock countdown).
  • Validate early: wallet addresses, payout fields, balances, and limits.
  • Observe limits & compliance: KYC/KYB, sanctions/KYT, AML alerts.