Payout: USDC to BRL

A payout takes stablecoin from your customer’s wallet and delivers fiat to a bank account. In this quickstart, your customer sells 100 USDC and the BRL lands on a Pix key in Brazil. It runs in the sandbox, where the Pix transfer is simulated, so it takes about a minute and no real money moves.

Why USDC and BRL

This picks up where the pay-in quickstart ends: the customer holds USDC on Polygon. Paying out over Pix shows the return trip, with the customer turning dollars on-chain back into reais, for example to pay a supplier or move the money to their own bank. The same calls work in other corridors. Register a destination on another rail, such as a CLABE over SPEI for MXN, and point the off-ramp at it. See Coverage for every currency, rail, and network.

Build it with your AI agent

Copy a prompt into Cursor, Claude Code, Codex, or any coding agent. Both read this page and the API spec before writing code.

Build it for me
Step by step

The agent writes and runs the full script, then reports back.

Prompt

You are a backend engineer integrating Lumx. Goal: in the Lumx sandbox, pay out USDC from a customer's wallet to that customer's own Pix key in Brazil, end to end, in one script.

Ground truth. Read these before writing code and follow them over any prior knowledge:
1. https://docs.lumx.io/quickstarts/payout.md, the quickstart you are implementing.
2. https://docs.lumx.io/llms.txt, the documentation index. Every page has a .md twin at its own path.
3. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml, the OpenAPI spec. Take field names and enum values from here.

Use https://api-sandbox.lumx.io only. Read the API key from the LUMX_API_KEY environment variable and the customer id from LUMX_CUSTOMER_ID, and never hard-code either. Never call production. The customer must be APPROVED and hold USDC on Polygon. If it does not, run https://docs.lumx.io/quickstarts/pay-in.md first.

Steps:
1. GET /customers/{id}?includeBalances=true and confirm the Polygon wallet holds at least 100 USDC. Read the customer's name and taxId from the same response.
2. POST /destinations with rail PIX, currency BRL, identifier keyType CPF and keyValue equal to the customer's taxId, and holder type INDIVIDUAL, relationship SELF, the customer's name and taxId, and a Brazilian address. Send an Idempotency-Key header. Continue only if holder.verification.status is APPROVED.
3. POST /transactions/off-ramp with that destinationId, sourceCurrency USDC, sourceAmount "100.00", purpose PERSONAL_ACCOUNT, blockchain POLYGON, a memo, and an Idempotency-Key header.
4. Poll GET /transactions/{id} until the status is SUCCESS or FAILED. Print finalTargetAmount and blockExplorerUrl from the receipt.

Constraints:
- The minimum payout is the equivalent of USD 40.
- Retry 429 responses with exponential backoff. No rate limit is published, so do not assume one.
- Exit non-zero if any step fails, and log what each step returned.

When you finish, hand back the script and a short summary of each step's result.

The agent explains each call and waits for your go-ahead before running it.

Prompt

You are a backend engineer teaching me to integrate Lumx. Goal: in the Lumx sandbox, pay out USDC from a customer's wallet to that customer's own Pix key in Brazil. Walk me through it one step at a time.

Ground truth. Read these first and follow them over any prior knowledge:
1. https://docs.lumx.io/quickstarts/payout.md, the quickstart we are following.
2. https://docs.lumx.io/llms.txt, the documentation index. Every page has a .md twin at its own path.
3. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml, the OpenAPI spec.

Use https://api-sandbox.lumx.io only. Read the API key from the LUMX_API_KEY environment variable and never print it. Never call production. Ask me for the customer id. The customer must be APPROVED and hold USDC on Polygon. If it does not, we start with https://docs.lumx.io/quickstarts/pay-in.md.

For each step: explain what the call does and why it is needed, show the exact request, run it only after I confirm, then show the response and point out the fields we use next. If a call fails, stop and explain the error before trying anything else.

Steps:
1. GET /customers/{id}?includeBalances=true to check the USDC balance and read the customer's name and taxId.
2. POST /destinations for the customer's own CPF Pix key, with holder relationship SELF. Check that holder.verification.status is APPROVED.
3. POST /transactions/off-ramp for 100 USDC on Polygon to that destination, with purpose PERSONAL_ACCOUNT and an Idempotency-Key header.
4. GET /transactions/{id} until the status is SUCCESS, then walk me through the receipt.

How it works

Object	Role in the payout
Wallet	Holds the customer’s USDC. The off-ramp debits it.
Destination	The bank account that receives the BRL, here a Pix key, with the holder’s details.
Off-ramp	One conversion: how much USDC goes out, from which network, and to which destination.

Before you start

A sandbox API key. See Authentication.
An approved customer with USDC in their wallet. The pay-in quickstart gets you there, and this page uses the customer it creates.

1. Register the Pix destination

A destination is where the payout goes, and Lumx verifies its holder before any money is sent. Here it is the customer’s own Pix key, so holder.relationship is SELF and the holder’s name and taxId match the customer.

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": "9d1ed178-7c29-42bb-912f-255f0e10cdb9",
    "name": "Ana - own account",
    "rail": "PIX",
    "currency": "BRL",
    "identifier": {
      "keyType": "CPF",
      "keyValue": "529.982.247-25"
    },
    "holder": {
      "type": "INDIVIDUAL",
      "relationship": "SELF",
      "name": "Ana Souza",
      "taxId": "529.982.247-25",
      "address": {
        "line1": "Rua Voluntarios da Patria 89",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postalCode": "22270-000",
        "country": "BRA"
      }
    }
  }'

Response (excerpt)

{
  "id": "d588796f-1d5c-4c94-b8ae-7d4172a12732",
  "customerId": "9d1ed178-7c29-42bb-912f-255f0e10cdb9",
  "rail": "PIX",
  "currency": "BRL",
  "identifier": { "keyType": "CPF", "keyValue": "52998224725" },
  "holder": {
    "name": "Ana Souza",
    "type": "INDIVIDUAL",
    "relationship": "SELF",
    "verification": { "status": "APPROVED", "level": "BASIC" }
  }
}

A payout needs a destination in APPROVED, and this Pix destination comes back approved. Save its id. Later payouts to the same recipient can reuse it.

2. Create the off-ramp

The off-ramp sells 100 USDC from the customer’s Polygon wallet and sends the BRL to the destination. The minimum per payout is the equivalent of USD 40.

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": "d588796f-1d5c-4c94-b8ae-7d4172a12732",
    "sourceCurrency": "USDC",
    "sourceAmount": "100.00",
    "purpose": "PERSONAL_ACCOUNT",
    "blockchain": "POLYGON",
    "memo": "Quickstart payout"
  }'

Response (excerpt)

{
  "id": "9685c5e2-9dd9-4eb4-a82c-f2f26a8d1ad0",
  "customerId": "9d1ed178-7c29-42bb-912f-255f0e10cdb9",
  "type": "OFF_RAMP",
  "request": {
    "sourceCurrency": "USDC",
    "targetCurrency": "BRL",
    "sourceAmount": "100.000000",
    "rail": "PIX",
    "purpose": "PERSONAL_ACCOUNT",
    "blockchain": "POLYGON",
    "memo": "Quickstart payout"
  },
  "state": { "status": "TRANSFERRING_STABLECOIN" }
}

The destination already fixes the rail and the currency, so the request has no rail or targetCurrency. The response fills them in.
PERSONAL_ACCOUNT only works with SELF destinations. To pay a third party, register the destination with their details and pick the matching purpose code.
memo goes in the message field of the Pix.

3. Wait for the payout

The off-ramp moves through TRANSFERRING_STABLECOIN, TRADING, and TRANSFERRING_FIAT to SUCCESS. In the sandbox this takes about a minute.

Request

curl https://api-sandbox.lumx.io/transactions/9685c5e2-9dd9-4eb4-a82c-f2f26a8d1ad0 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (excerpt)

{
  "id": "9685c5e2-9dd9-4eb4-a82c-f2f26a8d1ad0",
  "type": "OFF_RAMP",
  "request": {
    "sourceAmount": "100.000000",
    "targetAmount": "538.08"
  },
  "state": {
    "status": "SUCCESS",
    "receipt": {
      "sourceCurrency": "USDC",
      "sourceAmount": "100.000000",
      "targetCurrency": "BRL",
      "baseExchangeRate": "5.437900",
      "baseTargetAmount": "543.79",
      "fees": {
        "lumx": { "rate": "5", "flatAmount": "1.000000", "totalAmount": "1.050000", "currency": "USDC" }
      },
      "finalTargetAmount": "538.08",
      "finalExchangeRate": "5.380802",
      "transactionHash": "0xf82ab0941b313022f25b5a9a7c0ffa39e9031d0c1fff779c5c930f49971de1bb",
      "blockExplorerUrl": "https://amoy.polygonscan.com/tx/0xf82ab0941b313022f25b5a9a7c0ffa39e9031d0c1fff779c5c930f49971de1bb"
    }
  }
}

finalTargetAmount is the BRL the recipient receives, after fees. blockExplorerUrl opens the on-chain transfer that left the customer’s wallet.

What changes in production

Recipients: most payouts go to third parties, such as suppliers or employees. Register their destination with their details and the right holder.relationship. Destinations on some rails stay in UNDER_VERIFICATION until Lumx approves them. Wait for the destinations.approved webhook.
The rate: without a quote, the off-ramp converts at a floating rate. To fix the BRL amount before you pay, lock a quote.
Status updates: subscribe to the offramp.* webhooks instead of polling.
Sender name: the recipient sees your customer as the sender. See Sender of record.

Pay out stablecoins via Pix

The full Pix payout guide, with third-party recipients and errors.

Lock an FX quote

Fix the BRL amount before you pay.

USDT to MXN over SPEI

The same flow in Mexico.

Pay-in: BRL to USDC

Fund the wallet first.

Get Started

Quickstarts

Core Concepts

Compliance

Developer

Additional Information

Payout: USDC to BRL

Why USDC and BRL

Build it with your AI agent

How it works

Before you start

1. Register the Pix destination

2. Create the off-ramp

3. Wait for the payout

What changes in production

Pay out stablecoins via Pix

Lock an FX quote

USDT to MXN over SPEI

Pay-in: BRL to USDC

​Why USDC and BRL

​Build it with your AI agent

​How it works

​Before you start

​1. Register the Pix destination

​2. Create the off-ramp

​3. Wait for the payout

​What changes in production

​Related resources

Pay out stablecoins via Pix

Lock an FX quote

USDT to MXN over SPEI

Pay-in: BRL to USDC

Why USDC and BRL

Build it with your AI agent

How it works

Before you start

1. Register the Pix destination

2. Create the off-ramp

3. Wait for the payout

What changes in production

Related resources