De 0 a Integração

Este guia percorre tudo o que você precisa para aceitar depósitos de stablecoin usando o Blockradar, desde a configuração da conta até o tratamento do seu primeiro evento de webhook. Você pode integrar e lançar em produção com um único desenvolvedor em menos de 2 horas.

Siga e construa enquanto lê. Ao final você terá um fluxo de pagamento em stablecoin funcionando.

O que você vai construir

Ao final deste guia você terá:

Uma conta Blockradar e uma carteira principal na testnet
Endereços secundários gerados e vinculados aos seus usuários
Um handler de webhooks recebendo eventos de depósito em tempo real
Um padrão para atualizar saldos de usuários após um depósito

Passo 1: Crie sua conta

Cadastre-se

Acesse dashboard.blockradar.co/signup e complete o processo de integração. Leva menos de 60 segundos.

Verifique o Modo Live

No canto superior direito do dashboard você verá um botão de Modo Live. Está desativado por padrão, o que significa que cada ação é executada na testnet, um ambiente seguro sem fundos reais. Deixe desativado enquanto segue este guia.

Passo 2: Crie uma carteira principal

O que é uma carteira principal?

A carteira principal é a base da sua infraestrutura de stablecoin. Pense nela como sua tesouraria — ela controla todos os endereços secundários que você cria para seus usuários. Cada carteira principal está vinculada a uma blockchain específica, então se você quiser suportar depósitos no Ethereum, Base e BNB Chain, criará uma carteira principal separada para cada um.

Crie sua primeira carteira

Vá para a página de Carteiras

No dashboard, clique em Criar Carteira Principal.

Selecione uma rede

Escolha Base Sepolia (Testnet) para seguir este guia. Você pode criar carteiras em outras redes depois.

Nomeie sua carteira

Dê um nome como base-testnet e clique em Criar.

Agora você tem uma carteira principal. É nela que todos os endereços secundários dos seus usuários serão gerados.

Passo 3: Gere endereços para seus usuários

O que são endereços secundários?

Quando um usuário se cadastra no seu app e precisa receber stablecoins, ele precisa de um endereço de carteira, como um número de conta bancária, mas na blockchain. No Blockradar, esses são chamados de endereços secundários. São gerados sob sua carteira principal e herdam sua configuração de rede.

Endereços gerados em qualquer rede compatível com EVM (Base, Ethereum, BNB Chain etc.) funcionam em todas as redes EVM. Um endereço cobre todas as suas redes EVM.

Gere um endereço via API

Chame este endpoint quando um usuário se cadastrar na sua plataforma:

curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Wallet",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": true,
    "metadata": {
      "user_id": 1234,
      "email": "[email protected]"
    }
  }'

const options = {
  method: "POST",
  headers: {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Wallet",
    disableAutoSweep: false,
    enableGaslessWithdraw: true,
    metadata: { user_id: 1234, email: "[email protected]" },
  }),
};

fetch("https://api.blockradar.co/v1/wallets/{walletId}/addresses", options)
  .then((res) => res.json())
  .then(console.log);

Onde encontrar seu walletId e sua chave de API

Vá para sua carteira principal no dashboard
Role até a seção API Config
Clique no ícone de revelar (você precisará passar pela 2FA)
Copie sua API Key e seu Wallet ID

O campo metadata

O objeto metadata é uma das partes mais importantes desta requisição. Tudo que você anexar aqui será incluído em cada webhook que o Blockradar enviar para aquele endereço: depósitos, saques, varreduras. É assim que seu backend identifica a qual usuário uma transação pertence.

{
  "user_id": 1234,
  "email": "[email protected]"
}

Boa prática: Sempre inclua um user_id no metadata para mapear cada depósito diretamente a um usuário no seu banco de dados, sem nenhuma consulta adicional.

Passo 4: Configure a varredura automática e transações sem gas

Varredura automática

Quando a varredura automática está habilitada (disableAutoSweep: false), os fundos depositados em um endereço secundário são automaticamente consolidados na sua carteira principal. Isso simplifica a gestão da tesouraria: todos os fundos ficam em um só lugar, e você acompanha os saldos dos usuários no seu próprio banco de dados.

Para que a varredura automática funcione, sua carteira principal deve ter tokens nativos para cobrir as taxas de gas. Encontre o endereço de depósito da carteira principal na página de visão geral da carteira e envie tokens de testnet para ele.

Faucets de testnet para tokens de gas:

Rede	Token	Faucet
Base Sepolia	ETH	alchemy.com/faucets/base-sepolia
Ethereum Sepolia	ETH	alchemy.com/faucets/ethereum-sepolia
BNB Testnet	BNB	bnbchain.org/en/testnet-faucet
Polygon Testnet	MATIC	faucet.polygon.technology
Tron Testnet	TRX	nileex.io
Solana Devnet	SOL	faucet.solana.com
Celo Alfajores	CELO	faucet.celo.org/alfajores
Avalanche Fuji	AVAX	core.app/tools/testnet-faucet

Faucets de stablecoins na testnet:

Rede	Token	Faucet
Base / Ethereum / Polygon / Solana	USDC	faucet.circle.com
BNB Testnet	USDT	bnbchain.org/en/testnet-faucet

Transações sem gas

Quando enableGaslessWithdraw: true, seus usuários podem enviar stablecoins do endereço deles sem ter tokens nativos. Sua carteira principal cobre o gas em nome deles. Isso elimina o maior ponto de fricção de UX no onboarding em cripto.

Defina padrões globalmente

Em vez de configurar cada endereço individualmente, você pode definir padrões para toda a carteira principal:

Vá para sua carteira principal
Clique em Configurations
Defina disableAutoSweep e enableGaslessWithdraw

A configuração definida no nível do endereço substitui a configuração da carteira principal. Use a configuração no nível do endereço apenas quando precisar de exceções.

Passo 5: Configure os webhooks

O Blockradar usa webhooks para notificar seu backend quando eventos blockchain acontecem: depósitos, saques, varreduras e mais. Configure isso antes de testar transações.

Registre seu endpoint de webhook

Vá para sua carteira principal no dashboard
Clique em Desenvolvedor → Webhook
Insira a URL do seu endpoint backend (deve ser um endpoint POST)

Trate webhooks no seu backend

app.post("/webhook-handler", (req, res) => {
  const event = req.body;
  console.log("Webhook received:", event);
  // Handle event based on event type
  res.sendStatus(200);
});

Eventos de webhook comuns

Evento	Descrição
`deposit.success`	Um depósito foi recebido em um endereço secundário
`deposit.swept.success`	Fundos foram varridos de um endereço secundário para a carteira principal
`withdraw.success`	Um saque foi enviado com sucesso
`swap.success`	Uma troca foi executada com sucesso

Referência completa de webhooks

Veja todos os tipos de evento, esquemas de payload, lógica de novas tentativas e verificação HMAC.

Passo 6: Trate um evento de depósito

Quando um usuário envia USDC para o endereço dele, o Blockradar dispara um evento deposit.success para o seu endpoint de webhook.

Payload de exemplo

{
  "event": "deposit.success",
  "data": {
    "amountPaid": "10.0",
    "currency": "USD",
    "senderAddress": "0xabc...",
    "recipientAddress": "0xdef...",
    "metadata": {
      "user_id": 1234
    }
  }
}

Como processar

Identifique o usuário

Extraia metadata.user_id do payload. Isso mapeia o depósito a um usuário no seu banco de dados.

Leia o valor

Use data.amountPaid para determinar quanto foi depositado. Aplique qualquer taxa de depósito subtraindo-a desse valor antes de salvar.

Atualize o saldo

Credite o saldo do usuário no seu banco de dados. Se a varredura automática estiver habilitada, os fundos já estão na sua carteira principal.

O que você construiu

Agora você tem um fluxo completo de pagamento em stablecoin:

Uma carteira principal na testnet
Endereços secundários vinculados a usuários via metadata
Varredura automática consolidando fundos na sua tesouraria
Transações sem gas eliminando fricção para seus usuários
Um handler de webhooks atualizando saldos em tempo real

Para onde ir agora

Enviar pagamentos

Envie stablecoins para seus usuários ou parceiros programaticamente.

Adicionar verificação AML

Verifique endereços antes de enviar ou receber fundos.

Explorar trocas

Permita que usuários troquem entre stablecoins com uma única chamada de API.

Lançar em produção

Ative o Modo Live no dashboard e comece a aceitar fundos reais.

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

O que você vai construir

Passo 1: Crie sua conta

Passo 2: Crie uma carteira principal

O que é uma carteira principal?

Crie sua primeira carteira

Passo 3: Gere endereços para seus usuários

O que são endereços secundários?

Gere um endereço via API

Onde encontrar seu walletId e sua chave de API

O campo metadata

Passo 4: Configure a varredura automática e transações sem gas

Varredura automática

Transações sem gas

Defina padrões globalmente

Passo 5: Configure os webhooks

Registre seu endpoint de webhook

Trate webhooks no seu backend

Eventos de webhook comuns

Referência completa de webhooks

Passo 6: Trate um evento de depósito

Payload de exemplo

Como processar

O que você construiu

Para onde ir agora

Enviar pagamentos

Adicionar verificação AML

Explorar trocas

Lançar em produção

​O que você vai construir

​Passo 1: Crie sua conta

​Passo 2: Crie uma carteira principal

​O que é uma carteira principal?

​Crie sua primeira carteira

​Passo 3: Gere endereços para seus usuários

​O que são endereços secundários?

​Gere um endereço via API

​Onde encontrar seu walletId e sua chave de API

​O campo metadata

​Passo 4: Configure a varredura automática e transações sem gas

​Varredura automática

​Transações sem gas

​Defina padrões globalmente

​Passo 5: Configure os webhooks

​Registre seu endpoint de webhook

​Trate webhooks no seu backend

​Eventos de webhook comuns

Referência completa de webhooks

​Passo 6: Trate um evento de depósito

​Payload de exemplo

​Como processar

​O que você construiu

​Para onde ir agora

Enviar pagamentos

Adicionar verificação AML

Explorar trocas

Lançar em produção

O que você vai construir

Passo 1: Crie sua conta

Passo 2: Crie uma carteira principal

O que é uma carteira principal?

Crie sua primeira carteira

Passo 3: Gere endereços para seus usuários

O que são endereços secundários?

Gere um endereço via API

Onde encontrar seu walletId e sua chave de API

O campo metadata

Passo 4: Configure a varredura automática e transações sem gas

Varredura automática

Transações sem gas

Defina padrões globalmente

Passo 5: Configure os webhooks

Registre seu endpoint de webhook

Trate webhooks no seu backend

Eventos de webhook comuns

Passo 6: Trate um evento de depósito

Payload de exemplo

Como processar

O que você construiu

Para onde ir agora