Full integration guide
The complete path — from API key to a settled PIX payout, covering subaccounts, KYC, wallets, on-ramp and off-ramp.
Create a subaccount, verify the user, provision and fund a wallet, then pay out to
PIX and reconcile. Use the same subAccountId across KYC, wallets, deposits and payouts.
Prerequisites
- An API key from the Hodle team. Keys start with
hodle_live_. - A server that can receive webhooks (recommended) — or you can poll.
Every request carries your key:
Authorization: Bearer YOUR_API_KEYStep 1 — Create a subaccount
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" }'{ "success": true, "data": { "subAccountId": "5b9f...e21a" } }Store subAccountId against your user. List or fetch them any time:
curl https://api.hodle.com.br/api/subaccount -H "Authorization: Bearer $API_KEY" # list
curl https://api.hodle.com.br/api/subaccount/5b9f...e21a -H "Authorization: Bearer $API_KEY" # oneStep 2 — Run KYC
Money can't move for a subaccount until it's APPROVED. Submit the person's data plus two
uploaded image ids (selfie + document).
curl -X POST https://api.hodle.com.br/api/kyc \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subAccountId": "5b9f...e21a",
"fullName": "João da Silva",
"dateOfBirth": "1990-05-21",
"taxIdNumber": "12345678901",
"countryOfTaxId": "BRA",
"email": "joao@example.com",
"country": "BRA",
"state": "SP",
"city": "São Paulo",
"zipCode": "01310-100",
"streetAddress": "Av. Paulista, 1000",
"uploadedSelfieId": "sel_...",
"uploadedDocumentId": "doc_..."
}'{ "success": true, "data": { "attemptId": "kyc_8a2f...", "status": "PENDING" } }Then wait for approval — by webhook (preferred) or by polling:
curl https://api.hodle.com.br/api/kyc/kyc_8a2f... -H "Authorization: Bearer $API_KEY"{ "success": true, "data": { "status": "APPROVED" } }States: PENDING → APPROVED | REJECTED | EXPIRED. Wait for approval before depositing
or paying out. Full reference: KYC.
Step 3 — Provision a wallet
Create a wallet protected by the PIN the account holder established on the platform. See Wallet Keys for PIN setup and wallet selection.
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": "123456" }'{ "success": true, "data": { "id": "6a4d263d4cc67674bf72a3c9", "address": "0x4b1f...c9a2", "network": "polygon", "chainId": 137, "balance": 0, "protectedSymmetricKey": "<new wallet protected key>" } }Save data.id as walletId and cache its protectedSymmetricKey. Each create call makes a new wallet.
Pass walletId and subAccountId to /api/wallet/get. For payouts,
also send walletPin and this wallet's protectedSymmetricKey. Transfers use
fromSubAccountId for the source.
Step 4 — Fund the wallet (on-ramp)
Turn BRL into crypto credited to the wallet. Two ways:
- PIX on-ramp —
POST /api/deposit/assetreturns a PIX charge; once the payer pays, Hodle credits the wallet in the chosen asset. - External transfer — send USDT/USDC to the wallet address from Step 3; use the network selected in Step 3.
curl -X POST https://api.hodle.com.br/api/deposit/asset \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subAccountId": "5b9f...e21a",
"value": 5000,
"asset": "USDT",
"network": "polygon",
"address": "0x4b1f...c9a2"
}'value is in BRL cents (5000 = R$50.00). Listen for DEPOSIT_ASSET_SUCCESS when funds
land. Supported asset/network pairs and request fields: Deposit.
Step 5 — Pay out to PIX (off-ramp)
Pay BRL via PIX from the wallet. Hodle sponsors network fees.
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",
"walletPin": "123456",
"protectedSymmetricKey": "<new wallet protected key>",
"externalId": "payout-001",
"value": 5000,
"network": "polygon",
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL"
}'{ "success": true, "transactionId": "tx_7c1d...", "status": "PROCESSING", "valueInBrl": "50.00", "fee": "2.75" }Keep the same externalId when retrying. Poll until a final status, or use webhooks:
curl https://api.hodle.com.br/api/wallet/payout/tx_7c1d... -H "Authorization: Bearer $API_KEY"Final states are COMPLETED, FAILED and REFUNDED. COMPLETED carries the PIX
reference, endToEndId. On failure, read failureReason; retry only if the failure
webhook has retryable: true, or after confirming the refund. Full reference:
Payout.
For Lightning → PIX, you can issue a Lightning invoice directly instead of provisioning and funding a wallet.
Step 6 — Reconcile
Read operations for a date window. Use txHash for on-chain reconciliation and
endToEndId to match PIX payments to bank reports.
curl -X POST https://api.hodle.com.br/api/account/statement \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "subAccountId": "5b9f...e21a", "from": "2026-06-01", "to": "2026-06-30" }'Reference: Account statement.
Events to handle
Subscribe to webhooks instead of polling. The lifecycle emits:
| Event | When |
|---|---|
KYC_APPROVED / KYC_REJECTED | KYC resolves |
DEPOSIT_ASSET_SUCCESS | on-ramp funds land |
PAYOUT_SUCCESSFUL / PAYOUT_FAILED / PAYOUT_REFUNDED | payout settles, fails or is refunded |
DISPUTE_CREATED / DISPUTE_ACCEPTED / DISPUTE_REJECTED / DISPUTE_CANCELED | a Pix you received is contested (MED) and resolves |
Every webhook is signed with X-Hodle-Signature (HMAC-SHA256) — verify it before trusting the body.