Stable ↔ PIX
End-to-end flow — go from API key to a settled PIX payout funded by USDT, USDC, or BRLA.
What this flow does
Pay BRL via PIX from a wallet holding USDT or BRLA on Polygon, or USDC or BRLA on Base. Hodle sponsors network fees. BRLA converts to BRL at 1:1.
Sequence
1. POST /api/subaccount → subAccountId
2. POST /api/wallet/create → wallet provisioned (Polygon/Base)
3. POST /api/kyc → submit KYC, wait for APPROVED
4. (off-chain) fund the wallet → on-ramp via /api/deposit/asset OR external transfer
5. POST /api/wallet/keys → read the selected wallet’s protectedSymmetricKey
6. POST /api/wallet/payout → get transactionId
7. GET /api/wallet/payout/{id} → poll until a final statusCreate and verify the subaccount once. Reuse its wallet and cached key for payouts.
Step 1 — Create a subaccount
Create one subaccount per end-user. See the Full integration guide.
curl -X POST https://api.hodle.com.br/api/subaccount \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "João da Silva" }'const { data } = await fetch('https://api.hodle.com.br/api/subaccount', {
method: 'POST',
headers: {
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'João da Silva' }),
}).then((r) => r.json())
const subAccountId = data.subAccountId{ "success": true, "data": { "subAccountId": "5b9f1a83b6b7c2b001f3c9e21" } }Step 2 — Provision a wallet
Use the PIN established on the platform. See Wallet Keys.
curl -X POST https://api.hodle.com.br/api/wallet/create \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "subAccountId": "5b9f...e21a", "network": "polygon", "walletPin": "424242" }'{ "success": true, "data": { "id": "6a4d263d4cc67674bf72a3c9", "address": "0x4b1f...c9a2", "network": "polygon", "balance": 0, "protectedSymmetricKey": "Aoofi..." } }Save data.id as walletId and cache protectedSymmetricKey for that wallet. Calling create again creates another wallet.
Step 3 — KYC
Submit POST /api/kyc with the user's data and document photos. See the dedicated KYC guide for the full schema. Wait for status: APPROVED (webhook or poll).
Step 4 — Fund the wallet
Two options:
- On-ramp via Hodle:
POST /api/deposit/asset— sendsubAccountIdand the walletaddressto buy USDT/USDC via PIX. - External transfer: Send USDT/USDC from any wallet to the address from step 2. Use the network selected in step 2.
Verify the balance with POST /api/wallet/get, passing subAccountId and walletId.
Step 5 — Cache the symmetric key
If you need to retrieve the key again, select the same wallet and subaccount:
curl -X POST https://api.hodle.com.br/api/wallet/keys \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "subAccountId": "5b9f...e21a", "walletId": "6a4d263d4cc67674bf72a3c9" }'{ "success": true, "data": { "protectedSymmetricKey": "Aoofi...", "email": "user@example.com" } }Cache the key per wallet and refresh it after a PIN reset.
Step 6 — Trigger the payout
curl -X POST https://api.hodle.com.br/api/wallet/payout \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subAccountId": "5b9f...e21a",
"walletId": "6a4d263d4cc67674bf72a3c9",
"externalId": "payout-001",
"value": 5000,
"network": "polygon",
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL",
"walletPin": "424242",
"protectedSymmetricKey": "Aoofi..."
}'{
"success": true,
"transactionId": "65f1a8...",
"status": "PROCESSING",
"stableAmount": "9.31",
"valueInBrl": "50.00",
"fee": "1.55",
"network": "polygon"
}value is in BRL cents. Keep the same externalId when retrying to avoid a duplicate payout. Full reference: Wallet Payout.
Step 7 — Poll until settled
curl https://api.hodle.com.br/api/wallet/payout/65f1a8... \
-H "Authorization: Bearer $API_KEY"Poll every 5 seconds, or listen for webhooks. COMPLETED means
PIX settled; endToEndId is the bank's reference. FAILED and REFUNDED are also
final. Read failureReason before retrying a failed payout.
Subscribe to PAYOUT_SUCCESSFUL, PAYOUT_FAILED and PAYOUT_REFUNDED. A failed
payout does not guarantee the wallet balance has been restored. Retry only when
the failure webhook has retryable: true, or after confirming the refund.
Errors
| Status | When |
|---|---|
400 | Insufficient balance or invalid PIN. Three invalid PIN attempts lock the wallet for 24 hours. |
403 | KYC is not approved or payouts are not enabled. Wait for approval or contact support. |
Reconciliation
Use POST /api/account/statement to reconcile payouts by
txHash (on-chain) and endToEndId (PIX).