Stellar (USDC)

Hold USDC on Stellar, receive it, buy it with Pix and pay Pix from it — without ever holding XLM.

USDC wallets on Stellar require account enablement (ask support). Wallets receive USDC without holding XLM; network fees are sponsored.

1. Create the wallet

Creating again with the same scope returns the same PIN-protected wallet.

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/create \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "network": "stellar", "walletPin": "123456" }'
const res = await fetch('https://api.hodle.com.br/api/wallet/create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ network: 'stellar', walletPin: '123456' }),
})
const { data } = await res.json()
// data.address → "G…"
FieldTypeRequiredDescription
networkstringyes"stellar"
walletPinstringyesThe account's 6-digit wallet PIN.
subAccountIdstringnoCreate the wallet for a customer sub-account.
defaultbooleannoRequest it as the default wallet of its scope.

Response 201

{
  "success": true,
  "data": {
    "id": "6ad96f9124b1c5b037ec6fed",
    "address": "GCHZCGL3DQ4BBVK2UCDRTIBSAJPGBQJZMDVZHPXVNRA6X5IWT7Y33ZJD",
    "network": "stellar",
    "balance": 0
  }
}

2. Receive USDC

Send USDC on Stellar (the official USDC asset, issuer GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN) to the wallet's G… address. No memo is needed. Other Stellar assets are not credited.

3. Buy USDC with Pix

Use Deposit Asset with asset: "USDC" and network: "stellar". Create the receiving Hodle Stellar wallet first and send its address.

{ "asset": "USDC", "network": "stellar", "value": 10000, "address": "GCHZCGL3DQ4BBVK2UCDRTIBSAJPGBQJZMDVZHPXVNRA6X5IWT7Y33ZJD" }

To buy for a customer, add its subAccountId and send the address of that sub-account's Stellar wallet. The customer's identity must be approved through KYC under the same subAccountId first; the Pix is paid by the customer. A sub-account buy is refused if the address belongs to another wallet, or while the customer's KYC is not approved.

{ "asset": "USDC", "network": "stellar", "value": 10000, "subAccountId": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e", "address": "GBXQ…7KLM" }

4. Read the balance

Wallet Get includes the Stellar wallet:

{
  "addresses": { "stellar": "GCHZ…ZJD" },
  "balances": [
    { "network": "stellar", "asset": "USDC", "amount": "25.00" },
    { "network": "stellar", "asset": "XLM", "amount": "0.00" }
  ]
}

Balances are cached for 30 seconds; pass sync: true for a fresh read. POST /api/wallet/list lists the wallet with type: "STELLAR_CLIENT_GENERATED" and its address.

5. Pay a Pix

POST /api/wallet/payout/stellar pays a Pix key or a Pix QR code in BRL from the wallet's USDC. It applies Wallet Payout limits and third-party rules, and returns 202 while settling.

Payouts must be enabled separately on your account (ask support).

curl --request POST \
  --url https://api.hodle.com.br/api/wallet/payout/stellar \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "value": 1000, "pixKey": "maria@example.com", "walletPin": "123456", "externalId": "order-123" }'
FieldTypeRequiredDescription
valueintegeryesBRL the recipient receives, in cents (minimum 500).
pixKeystringone ofThe recipient's Pix key.
qrCodestringone ofA Pix QR code (copia e cola). Send pixKey or qrCode, never both.
walletPinstringyesThe account's 6-digit wallet PIN.
subAccountIdstringnoPay from a customer sub-account's Stellar wallet.
externalIdstringnoIdempotency key, 1–128 characters. Repeating it returns the same payout (200, alreadyProcessed: true).
taxIdstringnoThe recipient's CPF/CNPJ, for the third-party rules.

Response 202

{
  "success": true,
  "data": {
    "id": "6ad9…",
    "trackId": "1dbf…",
    "stage": "SENT",
    "amountInRaw": "19230000",
    "txHash": "aa…"
  }
}

amountInRaw is the USDC debited, with 7 decimals (19230000 = 1.923 USDC). Follow the payout with GET /api/wallet/payout/:transactionId and the PAYOUT_SUCCESSFUL / PAYOUT_FAILED webhooks. Do not resend while settlement is pending.

Errors

StatusWhen
400Invalid fields, both or neither of pixKey / qrCode, or payout below R$5.00.
401Missing or invalid API key.
403Stellar or payouts not enabled, wrong PIN, or KYC, third-party rules or limits refused.
409Another payout from the same wallet is in progress.
429Rate limited, wallet creation in progress, or Stellar wallet limit reached.
503Wallet creation: activation or setup incomplete; retry the same body to resume. Payout: temporarily unavailable; retry with the same externalId.