API Hodle para desenvolvedores
Atualizado em 22 de agosto de 2026.
A API Hodle é uma API REST para mover dinheiro entre o real e o dólar digital: pagar Pix a partir de saldo em stablecoin, emitir invoice Lightning que liquida em Pix, rodar on-ramp e off-ramp, ler carteiras auto-custodiais e enviar KYC de usuário final. Autenticação é por API key no header, respostas são JSON e cada mudança de estado chega por webhook assinado.
Esta página é o índice estável dos recursos de desenvolvimento da Hodle. Os endereços abaixo não mudam: se você é um agente ou um script procurando a especificação da API Hodle, comece por /openapi.json e por /.well-known/api-catalog.
Recursos da API Hodle
Todos os endereços abaixo respondem em hodle.com.br ou em docs.hodle.com.br e são estáveis.
- Especificação OpenAPI 3.1 da API HodleContrato completo em JSON: operationId, parâmetros tipados, schema de resposta e descrição em cada operação. É o arquivo que ferramentas de function calling e geradores de cliente consomem.
- Catálogo de APIs (RFC 9727)Linkset em application/linkset+json apontando para a especificação, a documentação e os canais de suporte. É o ponto de descoberta padronizado.
- Documentação da API HodleGuias por endpoint, fluxos ponta a ponta e referência navegável gerada da mesma especificação.
- AutenticaçãoComo emitir a API key e assinar as chamadas com Authorization: Bearer.
- WebhooksCatálogo de eventos, formato do payload e verificação da assinatura HMAC.
- SandboxAmbiente em sandbox-api.hodle.com.br com USDB de teste na Base Sepolia e nenhum dinheiro real.
- llms.txtResumo legível por máquina do que a Hodle faz, com dados de identificação e o mapa da API.
- llms-full.txtVersão estendida do llms.txt, com mais contexto de produto.
- Código aberto no GitHubRepositórios públicos e exemplos de integração.
Operações da API
A lista abaixo é o resumo do que a especificação declara. Cada linha traz o operationId, que é o identificador estável usado em function calling e na geração de clientes.
| POST /api/wallet/payout | walletPayout — dispara um payout Pix a partir do saldo em stablecoin da carteira, com gas patrocinado. |
|---|---|
| GET /api/wallet/payout/{transactionId} | walletPayoutStatus — estado final de um payout. |
| POST /api/lightning/invoice | createLightningInvoice — invoice BOLT11 que dispara um payout Pix quando pago. |
| POST /api/deposit/asset | depositAsset — on-ramp: Pix entra, cripto sai. |
| POST /api/quote | quote — preço indicativo e composição da taxa de um par BRL ↔ ativo. |
| GET /api/wallet | walletGet — endereços e saldos por rede de uma carteira. |
| POST /api/wallet/keys | walletKeys — devolve o protectedSymmetricKey necessário para assinar no cliente. |
| POST /api/wallet/transfer | walletTransfer — envia USDT para qualquer endereço nas redes suportadas. |
| POST /api/subaccount | subAccountCreate — cria a subconta de um usuário final. |
| GET /api/subaccount | subAccountList — lista as subcontas da sua plataforma. |
| GET /api/subaccount/{subAccountId} | subAccountGet — lê uma subconta. |
| POST /api/kyc | kycCreate — inicia uma tentativa de KYC. |
| GET /api/kyc | kycGet — estado atual do KYC. |
| POST /api/kyc/import-token | kycImportToken — importa uma verificação Sumsub já existente. |
| GET /api/account/statement | accountStatement — saldo por ativo e operações paginadas em uma janela. |
| POST /webhook/{webhookId} | webhookDelivery — o payload que o seu servidor recebe, declarado na especificação para você gerar o handler. |
Ambientes
| Produção | https://api.hodle.com.br |
|---|---|
| Sandbox | https://sandbox-api.hodle.com.br — USDB de teste na Base Sepolia, sem dinheiro real |
| Autenticação | Authorization: Bearer SUA_API_KEY em toda requisição |
| Formato | JSON em requisição e resposta; especificação OpenAPI 3.1.0 |
| Assinatura de webhook | HMAC no header, verificável com o segredo do endpoint |
Para agentes e LLMs
O site responde em markdown para quem pede. Envie Accept: text/markdown em qualquer página listada em /llms.txt e a resposta volta como text/markdown; a resposta declara Vary: Accept, então um cache intermediário não entrega a variante errada. Um tipo que não sabemos servir recebe 406.
Caminhos inexistentes respondem 404 de verdade, com um corpo curto apontando para o sitemap, o llms.txt e a documentação — nunca 200 com o shell da aplicação.
A especificação em /openapi.json tem operationId único, descrição e schema de resposta em cada operação, que é o formato esperado pelos conversores de OpenAPI para tool calling. Os limites de taxa declarados hoje estão nas respostas 429 das operações que os têm.
Começar a integrar
Crie a chave no painel, aponte para o sandbox e rode o primeiro fluxo.
- DocumentaçãoGuias por endpoint e fluxos ponta a ponta.
- API Pix stablecoinA visão de produto do que a API resolve.
- Para agentes de IAComo um agente usa a Hodle como trilho de pagamento.