Aesesdocs

Início rápido

Este guia mostra os quatro passos necessários para começar a aceitar pagamentos em cripto com a Aeses: criar uma API key, consultar seus saldos, gerar um endereço de depósito e verificar um webhook recebido. Ao final, você estará pronto para integrar em produção.

1. Criar uma API key

Entre no Painel Aeses e abra Developers → API keys. Crie uma nova chave em modo de teste para desenvolvimento. O modo de teste usa redes públicas de testnet (Sepolia, Bitcoin testnet, Tron Nile, Solana devnet) e nunca movimenta fundos reais.

Sua chave secreta tem o formato sk_live_4eC39HqLyjWDarjtT1zdp7dc. Guarde-a em uma variável de ambiente — nunca a comite no controle de versão nem exponha em um navegador.

Trate chaves secretas como senhas

Qualquer pessoa com sua chave secreta pode autorizar transferências e ver todos os dados da sua conta. Faça a rotação imediatamente se ela for exposta.

2. Listar seus saldos

Toda conta Aeses tem um livro-razão interno de saldos por ativo. Liste-os para confirmar que a chave está funcionando.

Requisição
curl https://api.aeses.io/v1/balances \
-H "x-api-key: sk_live_4eC39HqLyjWDarjtT1zdp7dc"

Uma conta nova retorna um array data vazio. Após receber seu primeiro depósito, o saldo correspondente aparece aqui.

3. Criar um depósito

Gere um endereço de uso único para o cliente enviar fundos. A Aeses deriva o endereço a partir de uma HD wallet com hardening — você nunca lida com chaves privadas.

Requisição
curl https://api.aeses.io/v1/deposits \
-H "x-api-key: sk_live_4eC39HqLyjWDarjtT1zdp7dc" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
  "asset": "USDT",
  "chain": "ethereum",
  "amount": "10.00",
  "webhook_url": "https://example.com/webhooks/aeses"
}'

A resposta contém um address novo válido por 30 minutos:

Resposta
{
"id": "dep_01HXYZ7M2P5RT4VG3K8AQWE9FN",
"object": "deposit",
"status": "pending",
"asset": "USDT",
"chain": "ethereum",
"address": "0x8f3a9c2bF7e1A4d62D8b9fF6E3c5a7E1d2B4c8A9",
"expected_amount": "10.00",
"expires_at": 1731600000
}

Envie o cliente para o endereço. Em testnet, você pode financiá-lo a partir de uma faucet.

4. Receber e verificar o webhook

Quando o depósito atinge o número de confirmações necessárias, a Aeses faz um POST do evento deposit.completed para a webhook_url. Todo webhook carrega um header X-Webhook-Signature que você precisa verificar antes de confiar no payload — veja Assinaturas de webhook para o algoritmo completo.

Testar o webhook localmente
# Encaminhe webhooks do painel para seu servidor local
ngrok http 3000

# Atualize o webhook_url da requisição de depósito para a URL do ngrok

# Dispare um evento de teste em Developers → Webhooks → Enviar evento de teste

Após receber e verificar o evento, credite o pedido do cliente no seu próprio sistema e retorne 200 OK.

Próximos passos