API Hodle para desenvolvedores
Atualizado em 4 de outubro 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.
Documentação por fluxo de pagamento
A documentação da Hodle é pública. Escolha o fluxo para consultar requisitos, exemplos de requisição, confirmação por webhook e limitações da operação. A moeda que financia o pagamento e a moeda recebida pelo destinatário podem ser diferentes.
- Pagar Pix usando saldo em USDT ou USDCFluxo stablecoin → reais via Pix: carteira, autorização, beneficiário, cotação e acompanhamento da liquidação.
- Receber Pix e entregar cripto na carteiraReferência do on-ramp: dados do pagador, ativo e rede de destino, cobrança Pix e entrega após confirmação. Confira os fluxos habilitados para sua conta.
- Receber Bitcoin via Lightning e liquidar em PixInvoice BOLT11 para um destinatário Pix, com contrato e acompanhamento específicos de Lightning.
- Consultar e autorizar operações de uma walletCriação, PIN, chave protegida e cache por carteira. Leia o modelo de assinatura antes de integrar pagamentos de usuários.
- Confirmar pagamentos e conciliar webhooksEventos assinados, identificadores e estados da operação; a aceitação de uma requisição não confirma a liquidação.
Tutoriais de API Pix em português
Implemente um fluxo de cada vez. Os exemplos de Node.js incluem testes locais e deixam explícito o que exige habilitação ou liquidação real.
- Integrar API Pix com Node.jsAutenticação, cobrança e consulta da operação.
- Validar webhook e tratar duplicatasAssinatura HMAC sobre o corpo original e processamento idempotente.
- Conciliar Pix pela APIIdentificadores, consulta e estados finais da operação.
- Criar um link de pagamento PixProduto de checkout, página hospedada e confirmação de pagamento.
- Comparar APIs Pix e BaaSCritérios e fontes oficiais para avaliar cinco fornecedores.
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çãoAuthorization: Bearer é usado nos exemplos da API; X-API-Key também é aceito. Guarde a chave no backend, nunca em URLs ou no frontend.
- WebhooksCatálogo de eventos, formato do payload e verificação da assinatura HMAC.
- SandboxAmbiente em sandbox-api.hodle.com.br com tokens 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 — consulta o estado de um payout, inclusive operações ainda pendentes. |
| 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 — recupera a chave protegida da carteira selecionada para o fluxo de payout ou transferência, conforme o modelo de assinatura documentado. |
| POST /api/wallet/transfer | walletTransfer — transfere um ativo na rede selecionada, conforme a matriz e a habilitação do endpoint. Não é uma operação de bridge entre redes. |
| 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 — tokens de teste na Base Sepolia, sem dinheiro real |
| Autenticação | Authorization: Bearer SUA_API_KEY; o header X-API-Key também é aceito |
| 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 |
MCP, skill e API REST para agentes de IA
A Hodle documenta o servidor MCP @hodle/mcp para clientes locais compatíveis com stdio. Ele usa sandbox e modo de leitura por padrão; operações de escrita exigem habilitação explícita e os requisitos de autorização de cada fluxo. Confira a configuração antes de permitir que um agente inicie pagamentos.
Na verificação de 4 de outubro de 2026, o pacote @hodle/mcp não estava disponível no registro público do npm. Confirme o acesso ao pacote com a equipe antes de seguir a instalação descrita na documentação; a integração REST permanece documentada separadamente.
O MCP local não é um conector remoto pronto para instalar no ChatGPT web ou no Claude web. Um agente também pode integrar diretamente pela API REST ou consultar o guia da skill. O repositório indicado para instalar a skill também não estava acessível publicamente nessa verificação; confirme o acesso com a equipe.
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 no mesmo endereço canônico. 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.
- MCP documentado: configuração e controlesConfiguração de @hodle/mcp, clientes compatíveis, ambiente e habilitação de escrita; confirme a disponibilidade do pacote.
- Guia da skill para agentesInstruções de integração; confirme o acesso ao repositório antes de instalar a skill.
- Requisitos de KYC e KYBVerificação dos participantes e requisitos para operar em produção.
Começar a integrar
Faça o cadastro separado no ambiente de sandbox, crie sua chave e rode primeiro uma cotação. Base Sepolia usa tokens de teste; Pix é simulado. Produção exige verificação e habilitação.
- Criar conta de sandboxCadastro separado, sem dinheiro real.
- Infraestrutura para neobankMódulos, responsabilidades e requisitos de operação.
- Preços e taxasTaxas públicas e condições por volume.
- 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.