Depositar Stablecoins

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

Chave API

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

Carteira Principal

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

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.

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"
  }'

const asset = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/assets`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'global-asset-id-for-usdc'
    })
  }
).then(r => r.json());

console.log('Ativo habilitado:', asset.data.asset.symbol);

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"
    }
  }'

const address = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Cliente 12345',
      metadata: {
        userId: 'user_12345',
        plan: 'premium'
      }
    })
  }
).then(r => r.json());

console.log('Endereço de depósito:', address.data.address);

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âmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Rótulo legível para o endereço
`metadata`	object	Não	Pares chave-valor personalizados mapeados ao seu sistema interno
`disableAutoSweep`	boolean	Não	Defina `true` para manter os depósitos no endereço em vez de varrê-los para a carteira principal
`enableGaslessWithdraw`	boolean	Não	Habilita 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

Evento	Descrição
`deposit.success`	Um depósito foi confirmado on-chain em um endereço de cliente
`deposit.swept.success`	O 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>'

const balance = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/balance?assetId=${assetId}`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

console.log(`Saldo: ${balance.data.balance} (≈$${balance.data.convertedBalance})`);

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>'

const balances = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/balances`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

balances.data.forEach(b => {
  console.log(`${b.asset.asset.symbol}: ${b.balance} (≈$${b.convertedBalance})`);
});

Endpoints de Saldo

Escopo	Único Ativo	Todos os Ativos
Carteira Principal	`GET /v1/wallets/{walletId}/balance?assetId={assetId}`	`GET /v1/wallets/{walletId}/balances`
Endereço Filho	`GET /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
  }'

const updated = 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({
      name: 'Cliente 12345 — atualizado',
      metadata: {
        userId: 'user_12345',
        plan: 'enterprise'
      },
      disableAutoSweep: true
    })
  }
).then(r => r.json());

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ção	Comportamento
Varredura automática habilitada (padrão)	Depósitos são automaticamente movidos para a carteira principal após confirmação
Varredura automática desabilitada	Depó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

Endpoint	Descrição
Get Wallet	Obter detalhes e configuração da carteira
Get Balance	Consultar saldo de um ativo na carteira principal
Get Balances	Consultar todos os saldos da carteira principal
Trigger Sweep	Varrer depósitos manualmente para a carteira principal
Deposit Finder	Re-escanear blockchain para depósitos ausentes
Webhook Logs	Ver histórico de entrega de webhooks

Endereços

Endpoint	Descrição
Generate Address	Criar um novo endereço de depósito de cliente
Get Addresses	Listar todos os endereços de uma carteira
Get Address	Obter detalhes de um endereço específico
Update Address	Atualizar nome, metadados ou configuração de endereço
Get Balance	Consultar saldo de um ativo em um endereço
Get Balances	Consultar todos os saldos de um endereço
Get Transactions	Ver histórico de depósitos de um endereço

Gestão de Ativos

Endpoint	Descrição
Get Wallet Assets	Listar ativos habilitados em uma carteira
Add Asset	Habilitar uma nova stablecoin para depósitos
Remove Asset	Parar de monitorar uma stablecoin
Update Asset	Atualizar configuração no nível do ativo

​Pré-requisitos

​Como Funciona

Gerar Endereços

Detectar Depósitos

Varredura Automática

Consultar Saldos

​Controle Granular por Design

​Passo 1: Habilitar Ativos na Sua Carteira

​Passo 2: Gerar um Endereço de Cliente

​Resposta

​Parâmetros de Endereço

​Passo 3: Escutar Depósitos

​Eventos de Webhook

​Payload do Webhook

​Consultar Saldos

​Saldo de Um Único Ativo (Carteira)

​Todos os Saldos de Ativos (Endereço)

​Endpoints de Saldo

​Gestão de Endereços

​Listar Todos os Endereços

​Obter um Endereço Específico

​Atualizar um Endereço

​Desativar um Endereço

​Varredura Automática

​Varredura Manual

​Buscador de Depósitos

​Exemplo de Fluxo Completo

​Melhores Práticas

​Gestão de Endereços

​Segurança

​Operações

​Referência API

​Carteira

​Endereços

​Gestão de Ativos

Pré-requisitos

Como Funciona

Controle Granular por Design

Passo 1: Habilitar Ativos na Sua Carteira

Passo 2: Gerar um Endereço de Cliente

Resposta

Parâmetros de Endereço

Passo 3: Escutar Depósitos

Eventos de Webhook

Payload do Webhook

Consultar Saldos

Saldo de Um Único Ativo (Carteira)

Todos os Saldos de Ativos (Endereço)

Endpoints de Saldo

Gestão de Endereços

Listar Todos os Endereços

Obter um Endereço Específico

Atualizar um Endereço

Desativar um Endereço

Varredura Automática

Varredura Manual

Buscador de Depósitos

Exemplo de Fluxo Completo

Melhores Práticas

Gestão de Endereços

Segurança

Operações

Referência API

Carteira

Endereços

Gestão de Ativos