Convert stablecoins (USDC or USDT) to Brazilian Real (BRL) via PIX transfer.

​
Prerequisites

Before initiating an off-ramp transaction:
  1. Verified Customer: Customer must be KYC-approved (see onboarding guides)
  2. Sufficient Balance: Customer must have enough stablecoins in their wallet
  3. PIX Key: Valid PIX key for receiving funds
  4. Exchange Rate (Optional): Get a quote or lock a rate (see exchange rate guides)

​
Transaction Flow

1

Initiate Off-Ramp

Submit transaction with amount and destination
2

Stablecoin Deduction

System deducts stablecoins from wallet
3

Processing

Convert stablecoins to fiat
4

PIX Transfer

Send BRL via PIX to specified key
5

Confirmation

Funds arrive in recipient’s bank account

​
Creating an Off-Ramp Transaction

​
Option 1: With Floating Rate

Use current market rates for conversion: 
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"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
sourceCurrencystringYes"USDC" or "USDT"
sourceAmountstringYesAmount of stablecoins to convert
targetCurrencystringYesMust be "BRL"
payment.railstringYesMust be "pix"
payment.keyTypestringYesType of PIX key (see below)
payment.keyValuestringYesThe PIX key value
partnerFeeIdstringNoUUID of partner fee configuration

​
Option 2: With Locked Rate

Use a pre-locked exchange rate for guaranteed conversion: 
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": "email",
      "keyValue": "user@example.com"
    }
  }'

​
Request Parameters

ParameterTypeRequiredDescription
customerIdstringYesUUID of the verified customer
exchangeRateIdstringYesUUID of locked exchange rate
payment.railstringYesMust be "pix"
payment.keyTypestringYesType of PIX key
payment.keyValuestringYesThe PIX key value

​
PIX Key Types

The system supports all standard PIX key types:
Key TypeFormatExample
cpfBrazilian individual tax ID123.456.789-00
cnpjBrazilian business tax ID12.345.678/0001-00
emailEmail addressuser@example.com
phonePhone number with country code+5511999999999
randomRandom key (EVP)123e4567-e89b-12d3-a456-426614174000
Ensure the PIX key belongs to the intended recipient. Transfers to PIX keys are irreversible once processed.

​
Transaction Response

​
Initial Response (Awaiting Funds)

{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "off_ramp",
  "request": {
    "sourceCurrency": "USDC",
    "sourceAmount": "1000.00",
    "targetCurrency": "BRL",
    "payment": {
      "rail": "pix",
      "keyType": "cpf",
      "keyValue": "123.456.789-00"
    }
  },
  "state": {
    "status": "awaiting_funds",
    "payment": {
      "rail": "pix"
    }
  },
  "createdAt": "2024-03-20T15:30:00Z",
  "updatedAt": "2024-03-20T15:30:05Z"
}

​
Transaction Status Monitoring

Monitor transaction progress: 
curl -X GET https://api.lumx.io/transactions/{transactionId} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Transaction Statuses

awaiting_funds

Verifying stablecoin balance

processing

Converting and sending funds

success

Funds delivered via PIX

failed

Transaction failed

​
Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "off_ramp",
  "request": {
    "sourceCurrency": "USDC",
    "sourceAmount": "1000.00",
    "targetCurrency": "BRL",
    "payment": {
      "rail": "pix",
      "keyType": "cpf",
      "keyValue": "123.456.789-00"
    }
  },
  "state": {
    "status": "success",
    "payment": {
      "rail": "pix"
    },
    "receipt": {
      "rate": "6.0066",
      "sourceAmount": "1000.00",
      "targetAmount": "5925.55",
      "sourceCurrency": "USDC",
      "targetCurrency": "BRL",
      "fees": {
        "currency": "USDC",
        "lumx": {
          "percentage": "10.000000",
          "flat": "1"
        },
        "developer": {
          "percentage": "0.000000",
          "flat": "0"
        }
      }
    },
    "blockchain": {
      "transactionHash": "0x1234567890123456789012345678901234567890",
      "blockExplorerUrl": "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
    }
  },
  "createdAt": "2024-03-20T15:30:00Z",
  "updatedAt": "2024-03-20T15:32:00Z"
}

​
Next Steps

On-Ramp Guide

Convert fiat to stablecoins

Transfer Guide

Send funds between customers

Balance Management

Check customer balances