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 status

Create 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
201 Created
{ "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" }'
201 Created
{ "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 — send subAccountId and the wallet address to 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..."
  }'
202 Accepted
{
  "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

StatusWhen
400Insufficient balance or invalid PIN. Three invalid PIN attempts lock the wallet for 24 hours.
403KYC 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).