​
Overview

A transfer moves a stablecoin from one customer to another, or from a customer to an external wallet. Use any supported stablecoin and supported blockchain configured for your account.

​
Prerequisites

Before initiating a transfer:
  1. Verified Sender (Customer) — Customer must be KYC-approved (see onboarding).
  2. Sufficient Balance — The sender must hold enough of the selected stablecoin.
  3. Valid Recipient — Provide either a Lumx customerId or a validexternal wallet address (per the selected stablecoin/blockchain).
Refer to supported stablecoins and blockchains.

​
Transaction Overview

1

Initiate Transfer

Create the transfer with currency, amount, and recipient (customerId or wallet address).
2

Balance and Recipient Verification

We verify if the sender has enough balance and perform compliance checks on the recipient’s wallet.
3

Stablecoin Transfer

The target stablecoin is sent to the recipient’s wallet.
4

Balance Updates

Sender is debited and recipient is credited; history is updated.

​
Creating a Transfer

​
Transfer to another customer

Request
curl --request POST \
  --url https://api.lumx.io/transactions/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "currency": "USDC",
  "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "980dc26b-42fd-4044-8a42-2271d20a2eb9",
  "amount": "10000.000000"
}'

​
Transfer to an external wallet

Request
curl --request POST \
  --url https://api.lumx.io/transactions/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "currency": "USDC",
  "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "amount": "10000.000000"
}'
Parameters
ParameterTypeRequiredDescription
currencystringYesAsset code (e.g., USDC, USDT, or another supported token)
fromstringYesSender’s customerId
tostringYesRecipient customerId or external wallet address
amountstringYesTransfer amount (supports up to 6 decimals, e.g., "1000.123456")
Response
{
	"value": {
		"id": "123e4567-e89b-12d3-a456-426614174004",
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"type": "TRANSFER",
		"request": {
			"currency": "USDC",
			"from": "123e4567-e89b-12d3-a456-426614174001",
			"to": "123e4567-e89b-12d3-a456-426614174002",
			"amount": "1000.000000"
		},
		"state": {
			"status": "PROCESSING"
		}
	}
}
Other Transfer Statuses 
{
	"id": "123e4567-e89b-12d3-a456-426614174004",
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"type": "TRANSFER",
	"request": {
		"currency": "USDC",
		"from": "123e4567-e89b-12d3-a456-426614174001",
		"to": "123e4567-e89b-12d3-a456-426614174002",
		"amount": "1000.000000"
	},
	"state": {
		"status": "SUCCESS",
		"receipt": {
			"transactionHash": "0x1234567890123456789012345678901234567890",
			"blockExplorerUrl": "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
		}
	}
}
Key Response Fields
FieldDescriptionPresent when
idUnique transaction identifierall statuses
customerIdOriginating (sender) customer identifierall statuses
state.statusprocessing | success | failedall statuses
state.blockchain.transactionHashOn-chain transaction hashsuccess
state.blockchain.blockExplorerUrlLink to view the on-chain transactionsuccess
state.errorError details (if any)failed

​
Transfer states

FieldDescription
processingThe transfer is being processed on-chain
successTransfer confirmed on-chain; balances updated.
failedTransfer failed (e.g., insufficient funds or invalid address)

​
Transaction Monitoring

Once we receive the deposit for your transaction, we will move the funds to the destination. You can use the API to check the state of the transaction or listen to webhooks.

​
Next steps