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_KEY

Step 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" }'
201 Created
{ "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"   # one

Step 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_..."
  }'
202 Accepted
{ "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" }'
201 Created
{ "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/asset returns 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"
  }'
202 Accepted
{ "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:

EventWhen
KYC_APPROVED / KYC_REJECTEDKYC resolves
DEPOSIT_ASSET_SUCCESSon-ramp funds land
PAYOUT_SUCCESSFUL / PAYOUT_FAILED / PAYOUT_REFUNDEDpayout settles, fails or is refunded
DISPUTE_CREATED / DISPUTE_ACCEPTED / DISPUTE_REJECTED / DISPUTE_CANCELEDa Pix you received is contested (MED) and resolves

Every webhook is signed with X-Hodle-Signature (HMAC-SHA256) — verify it before trusting the body.