Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumx.io/llms.txt

Use this file to discover all available pages before exploring further.

Build a P2P remittance product where individuals send money to family and friends abroad. Each sender is onboarded as an individual customer who funds their wallet in local currency. To send, you register the recipient’s destination under the sender and trigger a payout. Lumx converts stablecoin to the recipient’s local fiat and delivers it on local rails.

​
Step 1: Generate your API key

Head over to dashboard.lumx.io. Once logged in, generate a new API key and store it securely. See Authentication for details.

​
Step 2: Onboard the sender

For each sender using your product, create an individual customer. Provision an account in their home currency so they can fund the wallet via a local rail. Senders must accept Lumx’s terms of service (POST /customers/{id}/tos) and complete KYC before they can move funds.
Request
curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "INDIVIDUAL",
    "name": "Lucia Pereira",
    "taxId": "123-45-6789",
    "birthDate": "1985-09-12",
    "country": "USA",
    "email": "lucia.pereira@example.com",
    "accounts": ["USD"]
  }'
See Individual verification for the full onboarding flow.

​
Step 3: Fund the sender’s wallet

Once the sender’s account is ACTIVE, create an on-ramp transaction for the exact amount the sender plans to deposit. The response includes the rail-specific payment details: ACH/wire for USD, PIX brCode for BRL, SPEI CLABE for MXN, IBAN for EUR. Show them in your app for the sender to pay; when the deposit matches, Lumx converts the fiat to stablecoin and credits the sender’s wallet.
Request
curl -X POST https://api-sandbox.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rail": "ACH",
    "sourceCurrency": "USD",
    "sourceAmount": "500.00",
    "targetCurrency": "USDC",
    "purpose": "PERSONAL_ACCOUNT"
  }'
Each deposit must be matched to an on-ramp transaction created in advance with the exact amount.
Subscribe to the onramp.success webhook to know the moment the wallet is funded and the sender can confirm the remittance. For the full deposit flow by rail, see Global accounts. If the sender pays after the on-ramp expires, Lumx refunds them on the same rail. See Late deposits.

​
Step 4: Register the recipient’s destination

Register a destination for the recipient under the sender. Use holder.relationship of RELATIVE for family or FRIEND for friends. This is how the recipient is categorized for compliance. See Coverage for the full list of supported rails and currencies.
Request
curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Mother - Brazil",
    "rail": "PIX",
    "currency": "BRL",
    "identifier": {
      "keyType": "CPF",
      "keyValue": "123.456.789-00"
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "RELATIVE",
      "name": "Ana Pereira",
      "taxId": "123.456.789-00",
      "birthDate": "1960-04-22",
      "email": "ana.pereira@example.com",
      "address": {
        "line1": "Rua das Flores 250",
        "city": "Belo Horizonte",
        "state": "MG",
        "postalCode": "30130-110",
        "country": "BRA"
      }
    }
  }'
Destinations go through verification before they can be used. Subscribe to the destinations.approved webhook to know when a recipient is ready to receive funds. See Destinations for the full reference.

​
Step 5: Lock an exchange rate

Senders want to know exactly how much the recipient will receive before confirming the transfer. Fetch a locked exchange rate first and reference its id in the off-ramp request to guarantee the conversion price.
Request
curl -X POST https://api-sandbox.lumx.io/exchange-rates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "LOCKED",
    "rail": "PIX",
    "sourceCurrency": "USDC",
    "targetCurrency": "BRL",
    "sourceAmount": "500.00",
    "timelock": "1m"
  }'
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "LOCKED",
  "rail": "PIX",
  "sourceCurrency": "USDC",
  "sourceAmount": "500.00",
  "targetCurrency": "BRL",
  "baseTargetAmount": "2587.50",
  "baseExchangeRate": "5.1750",
  "finalTargetAmount": "2581.81",
  "finalExchangeRate": "5.1636",
  "expiresAt": "2026-05-16T15:45:00Z"
}
Show the resulting finalTargetAmount to the sender. If they confirm before expiresAt, the off-ramp will settle at finalExchangeRate. See Exchange Rates.

​
Step 6: Send the remittance

Create an off-ramp transaction debiting the sender’s wallet. Reference the locked exchangeRateId and use purpose: "BILLS" (the closest available code for P2P remittances; see Purpose codes).
Request
curl -X POST https://api-sandbox.lumx.io/transactions/off-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "exchangeRateId": "123e4567-e89b-12d3-a456-426614174000",
    "purpose": "BILLS"
  }'
Response
{
  "id": "9b1c5b8a-3d1f-4a8f-b6e0-2c1b6a7e9f33",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "OFF_RAMP",
  "request": {
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "exchangeRateId": "123e4567-e89b-12d3-a456-426614174000",
    "purpose": "BILLS"
  },
  "state": {
    "status": "TRANSFERRING_STABLECOIN"
  }
}

​
Step 7: Notify the sender on completion

Each off-ramp follows this lifecycle: TRANSFERRING_STABLECOIN → TRADING → TRANSFERRING_FIAT → SUCCESS Subscribe to offramp.success and offramp.failed webhooks to push a confirmation back to the sender in your app the moment the recipient receives the funds. See Webhooks.

Global accounts

Provision the sender’s funding account.

Exchange Rates

Lock FX rates for predictable payouts.

Destinations

Holder relationships and rail-specific identifiers.

Transactions

Off-ramp lifecycle and purpose codes.