Overview

What the Hodle API is, how the pieces fit, and the path from API key to a settled payment.

The Hodle API is payment infrastructure for Brazil: move money between BRL (PIX), Bitcoin Lightning, and USD-pegged stablecoins through one HTTP API. You can on-ramp (PIX → crypto), off-ramp (crypto → PIX), issue Lightning invoices that settle to PIX, and hold balances in managed wallets.

It's non-custodial by design. Wallet keys are derived on the client and encrypted; the server never holds a user's mnemonic, PIN, or symmetric key in clear. Funds stay under the user's control throughout the flow.

The building blocks

You'll touch these concepts in roughly this order:

Block	What it is	Endpoints
API key	Authenticates every request. Identifies your platform.	Authentication
Subaccount	A segregated account under your platform — one per end-user or business unit.	`/api/subaccount`
KYC	Identity verification. Required before money can move for a user.	`/api/kyc`
Wallet	A non-custodial multi-chain wallet (Polygon, Base, Tron, Liquid).	Wallet
Deposit (on-ramp)	Turn BRL (PIX) into crypto credited to a wallet.	`/api/deposit/asset`
Payout (off-ramp)	Turn crypto into a BRL PIX payment to any key.	`/api/wallet/payout`
Lightning	Issue a BOLT11 invoice that settles to PIX.	Lightning invoice
Webhooks	Server-to-server events for KYC, deposits, and payouts.	Webhooks
Sandbox	A testnet environment to integrate without moving real money.	Sandbox

The integration lifecycle

 1. Get your API key          (from the Hodle team)
 2. Onboard a user            create a subaccount + run KYC  → APPROVED
 3. Provision a wallet        addresses on Polygon / Base / Tron / Liquid
 4. Fund it (on-ramp)         PIX → crypto, or an external transfer
 5. Move money (off-ramp)     payout to PIX, or a Lightning invoice
 6. Reconcile                 account statement joins on-chain + PIX references

Steps 1–3 happen once per user. Steps 4–6 repeat per transaction. KYC must be APPROVED before deposit or payout — those endpoints return 403 otherwise.

Base URL & auth

Production   https://api.hodle.com.br
Sandbox      https://sandbox-api.hodle.com.br

Every request carries your key:

Authorization: Bearer YOUR_API_KEY

Production keys are prefixed hodle_live_, sandbox keys hodle_test_. A key only works in its own environment. See Authentication.

Money never moves silently

Every state change emits a webhook (KYC_APPROVED, DEPOSIT_ASSET_SUCCESS, PAYOUT_SUCCESSFUL, PAYOUT_FAILED, …) signed with X-Hodle-Signature. Prefer webhooks over polling for server-to-server flows. Every payout and deposit also carries an on-chain txHash and a PIX endToEndId so you can reconcile against your bank report.

Where to next

Start here: Full integration guide — the complete path, end to end.
Test first: Sandbox — integrate against testnet USDB, no real money.
Use cases: Stable ↔ PIX · Lightning ↔ PIX
Reference: KYC · Wallet · Deposit · Payout · Webhooks