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…"| Field | Type | Required | Description |
|---|---|---|---|
network | string | yes | "stellar" |
walletPin | string | yes | The account's 6-digit wallet PIN. |
subAccountId | string | no | Create the wallet for a customer sub-account. |
default | boolean | no | Request 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" }'| Field | Type | Required | Description |
|---|---|---|---|
value | integer | yes | BRL the recipient receives, in cents (minimum 500). |
pixKey | string | one of | The recipient's Pix key. |
qrCode | string | one of | A Pix QR code (copia e cola). Send pixKey or qrCode, never both. |
walletPin | string | yes | The account's 6-digit wallet PIN. |
subAccountId | string | no | Pay from a customer sub-account's Stellar wallet. |
externalId | string | no | Idempotency key, 1–128 characters. Repeating it returns the same payout (200, alreadyProcessed: true). |
taxId | string | no | The 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
| Status | When |
|---|---|
400 | Invalid fields, both or neither of pixKey / qrCode, or payout below R$5.00. |
401 | Missing or invalid API key. |
403 | Stellar or payouts not enabled, wrong PIN, or KYC, third-party rules or limits refused. |
409 | Another payout from the same wallet is in progress. |
429 | Rate limited, wallet creation in progress, or Stellar wallet limit reached. |
503 | Wallet creation: activation or setup incomplete; retry the same body to resume. Payout: temporarily unavailable; retry with the same externalId. |