Saltar para o conteúdo principal
Em resumo
A Blockradar permite que você aceite depósitos de stablecoins gerando endereços blockchain dedicados para cada cliente. Os depósitos são detectados automaticamente, disparam notificações por webhook e podem ser varridos para sua carteira principal — dando a você controle total sobre como os fundos fluem pela sua plataforma.

Pré-requisitos

1

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.
2

Carteira Principal

Crie uma carteira através do painel ou API. Você precisará do walletId para todas as operações de depósito.
3

Ativos Habilitados

Habilite as stablecoins que deseja aceitar na sua carteira. Sua carteira só detecta depósitos de ativos que você adicionou explicitamente — consulte Gestão de Ativos.
4

URL de Webhook

Configure um endpoint de webhook no seu painel em Developers → Webhooks para receber notificações de depósitos em tempo real.

Como Funciona

O fluxo de depósitos da Blockradar é construído em torno de um princípio simples: cada cliente recebe seu próprio endereço, e cada depósito é rastreado automaticamente.

Gerar Endereços

Crie um endereço blockchain único para cada cliente ou sessão de pagamento. Depósitos nesse endereço são atribuídos ao cliente automaticamente.

Detectar Depósitos

A Blockradar monitora todos os endereços gerados e dispara um webhook no momento em que um depósito chega — sem necessidade de polling.

Varredura Automática

Os depósitos são consolidados automaticamente na sua carteira principal, mantendo os endereços dos clientes limpos e sua tesouraria centralizada.

Consultar Saldos

Consulte saldos no nível da carteira ou endereço, para um único ativo ou todos os ativos de uma vez, com conversão para USD incluída.

Controle Granular por Design

A maioria da infraestrutura blockchain trata carteiras como contêineres planos e uniformes. A Blockradar é diferente. Cada camada da hierarquia de carteiras — carteira principal, endereço filho e ativo individual — é configurável de forma independente, para que as fintechs possam adaptar a experiência de depósito às necessidades exatas do seu produto. Isso significa que você pode:
  • Aceitar diferentes stablecoins por carteira — habilite USDC em uma carteira e USDT em outra, ou ambas na mesma carteira. Você decide o que cada carteira monitora.
  • Configurar o comportamento de varredura por endereço — varra automaticamente os depósitos para a carteira principal por padrão, mas desative para endereços específicos onde você quer que os fundos permaneçam.
  • Anexar metadados a cada endereço — marque endereços com seus próprios IDs de usuário, tokens de sessão ou referências internas para que os depósitos se mapeiem diretamente ao seu sistema.
  • Ativar ou desativar endereços sob demanda — pause um endereço sem excluí-lo, e reative quando necessário.
Essa granularidade importa quando você está construindo produtos como carteiras multi-moeda, escrow de marketplace ou fluxos de depósito por usuário — onde um modelo de carteira rígido forçaria soluções alternativas que a Blockradar lida nativamente.

Passo 1: Habilitar Ativos na Sua Carteira

Antes de poder aceitar depósitos, sua carteira precisa saber quais stablecoins monitorar. Obtenha os ativos disponíveis com o endpoint Get Assets e depois adicione os que desejar.
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "global-asset-id-for-usdc"
  }'
Uma vez adicionado, a Blockradar começa imediatamente a monitorar sua carteira e todos os seus endereços para depósitos desse token.
Use Get Wallet Assets para obter os IDs de ativos específicos da carteira. Esses são os IDs que você usará em consultas de saldo e outras chamadas de API — eles são diferentes dos IDs de ativos globais.

Passo 2: Gerar um Endereço de Cliente

Crie um endereço dedicado para cada cliente ou sessão de depósito. Cada depósito neste endereço é automaticamente atribuído ao cliente.
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Cliente 12345",
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    }
  }'

Resposta

{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Cliente 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Parâmetros de Endereço

ParâmetroTipoObrigatórioDescrição
namestringNãoRótulo legível para o endereço
metadataobjectNãoPares chave-valor personalizados mapeados ao seu sistema interno
disableAutoSweepbooleanNãoDefina true para manter os depósitos no endereço em vez de varrê-los para a carteira principal
enableGaslessWithdrawbooleanNãoHabilita saques sem gas deste endereço
Compartilhe o address gerado com seu cliente. Quando eles enviarem stablecoins para ele, a Blockradar detecta o depósito e dispara um webhook.

Passo 3: Escutar Depósitos

Configure seu endpoint de webhook para receber notificações em tempo real quando depósitos chegarem.

Eventos de Webhook

EventoDescrição
deposit.successUm depósito foi confirmado on-chain em um endereço de cliente
deposit.swept.successO depósito foi varrido automaticamente para a carteira principal

Payload do Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Os metadata que você anexou ao gerar o endereço são incluídos em cada webhook para esse endereço, para que você possa mapear depósitos de volta aos seus usuários sem uma consulta adicional.

Consultar Saldos

Consulte saldos em qualquer nível da hierarquia — carteira principal ou endereço individual, um único ativo ou todos os ativos.

Saldo de Um Único Ativo (Carteira)

curl --request GET \
  --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
  --header 'x-api-key: <api-key>'

Todos os Saldos de Ativos (Endereço)

curl --request GET \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
  --header 'x-api-key: <api-key>'

Endpoints de Saldo

EscopoÚnico AtivoTodos os Ativos
Carteira PrincipalGET /v1/wallets/{walletId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/balances
Endereço FilhoGET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/addresses/{addressId}/balances

Gestão de Endereços

Listar Todos os Endereços

Obtenha todos os endereços de uma carteira, com analíticos de contagem de ativos vs. inativos.
GET /v1/wallets/{walletId}/addresses

Obter um Endereço Específico

Recupere todos os detalhes de um endereço, incluindo sua configuração e metadados.
GET /v1/wallets/{walletId}/addresses/{addressId}

Atualizar um Endereço

Modifique o nome, metadados, status ativo ou configuração de varredura de um endereço.
curl --request PATCH \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Cliente 12345 — atualizado",
    "metadata": {
      "userId": "user_12345",
      "plan": "enterprise"
    },
    "disableAutoSweep": true
  }'

Desativar um Endereço

Defina isActive como false para parar de monitorar um endereço. O endereço e seu histórico são preservados — você pode reativá-lo a qualquer momento.
await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);

Varredura Automática

Por padrão, depósitos em endereços filhos são automaticamente varridos para a carteira principal. Isso mantém os endereços dos clientes limpos e consolida fundos para gestão de tesouraria ou pagamentos. Você pode controlar isso no nível do endereço:
ConfiguraçãoComportamento
Varredura automática habilitada (padrão)Depósitos são automaticamente movidos para a carteira principal após confirmação
Varredura automática desabilitadaDepósitos permanecem no endereço filho até serem varridos manualmente ou sacados

Varredura Manual

Se a varredura automática estiver desabilitada, você pode acionar uma varredura sob demanda:
POST /v1/wallets/{walletId}/sweep/assets
{
  "forceSweep": true
}

Buscador de Depósitos

Se um depósito não aparecer (ex.: webhook perdido), use o buscador de depósitos para re-escanear a blockchain:
POST /v1/wallets/{walletId}/rescan/blocks
{
  "transactionHash": "0xabc123..."
}

Exemplo de Fluxo Completo

Aqui está uma implementação completa: habilitar um ativo, gerar um endereço de cliente e lidar com o webhook de depósito.
async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Passo 1: Gerar um endereço dedicado para o cliente
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `Usuário ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Compartilhe este endereço com o cliente:', depositAddress);

  return depositAddress;
}

// Handler de webhook (exemplo com Express.js)
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Depósito recebido: ${amount} ${symbol} do usuário ${userId}`);

    // Creditar a conta do usuário no seu sistema
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Depósito varrido para carteira principal: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});

Melhores Práticas

Gestão de Endereços

  • Um endereço por cliente — gere um endereço único para cada usuário ou sessão de pagamento para simplificar a atribuição
  • Use metadados — anexe seus IDs de usuário internos e referências para que os payloads de webhook se mapeiem diretamente ao seu sistema
  • Desative, não exclua — defina isActive: false em endereços que você não precisa mais, preservando o histórico

Segurança

  • Valide webhooks — verifique que as solicitações de webhook recebidas originam-se da Blockradar
  • Habilite verificação AML — a Blockradar pode verificar endereços de depósito automaticamente (consulte Verificação AML)
  • Monitore os logs de webhook — use GET /v1/wallets/{walletId}/webhooks para depurar entregas falhas

Operações

  • Habilite apenas os ativos que precisa — uma lista de ativos focada reduz o ruído de webhooks e mantém as consultas de saldo rápidas
  • Teste primeiro na testnet — gere endereços, simule depósitos e verifique seu handler de webhook antes de ir para a mainnet
  • Use o buscador de depósitos — se um cliente reportar um depósito que você não recebeu, re-escaneie a blockchain antes de investigar mais

Referência API

Carteira

EndpointDescrição
Get WalletObter detalhes e configuração da carteira
Get BalanceConsultar saldo de um ativo na carteira principal
Get BalancesConsultar todos os saldos da carteira principal
Trigger SweepVarrer depósitos manualmente para a carteira principal
Deposit FinderRe-escanear blockchain para depósitos ausentes
Webhook LogsVer histórico de entrega de webhooks

Endereços

EndpointDescrição
Generate AddressCriar um novo endereço de depósito de cliente
Get AddressesListar todos os endereços de uma carteira
Get AddressObter detalhes de um endereço específico
Update AddressAtualizar nome, metadados ou configuração de endereço
Get BalanceConsultar saldo de um ativo em um endereço
Get BalancesConsultar todos os saldos de um endereço
Get TransactionsVer histórico de depósitos de um endereço

Gestão de Ativos

EndpointDescrição
Get Wallet AssetsListar ativos habilitados em uma carteira
Add AssetHabilitar uma nova stablecoin para depósitos
Remove AssetParar de monitorar uma stablecoin
Update AssetAtualizar configuração no nível do ativo