Endereços

Em resumo
Endereços dedicados permitem criar endereços blockchain únicos para cada cliente. Esses endereços podem receber stablecoins em várias chains compatíveis com EVM, com depósitos varridos automaticamente para sua carteira mestra.

Pré-requisitos

Antes de gerar endereços, certifique-se de ter:

Chave API

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

Carteira Mestra Criada

Crie pelo menos uma carteira mestra via API Criar Carteira ou painel. Você precisará do walletId para gerar endereços.

Carteira Financiada

Financie sua carteira mestra com tokens nativos (ETH, BNB, MATIC, etc.) para cobrir taxas de gas das operações de varredura automática.

Webhook Configurado

Configure sua URL de webhook na carteira mestra para receber notificações de depósito. Veja Webhooks para detalhes de configuração.

Como Funciona

Endereços Dedicados é um recurso crucial na Blockradar que permite criar endereços exclusivos para seus clientes. Esses endereços permitem que seus clientes depositem stablecoins em seu aplicativo fintech perfeitamente. Quando você cria um endereço dedicado para um cliente, ele pode usar esse único endereço para depositar stablecoins em várias blockchains compatíveis com EVM. Por exemplo, se você tiver carteiras mestras Ethereum, Binance Smart Chain, Polygon e Base criadas, cada endereço que você gerar através de qualquer uma dessas carteiras mestras pode ser usado para receber stablecoins em qualquer uma das blockchains e ativos suportados. Isso garante que você não precise se preocupar com seu cliente enviando stablecoins para a blockchain errada. Além disso, quando stablecoins são depositadas em um endereço específico, os ativos são automaticamente movidos para o endereço da carteira mestra da chain.

Exceto para Tron e Solana, endereços gerados de uma carteira podem ser usados para depositar stablecoins em outras blockchains que tenham o parâmetro de blockchain isEvmCompatible: true.

Parâmetros de Endereço Explicados

Ao criar ou atualizar um endereço, você pode usar os seguintes parâmetros opcionais para personalizar seu comportamento:

Parâmetro	Tipo	Padrão	Descrição
`disableAutoSweep`	Boolean (Opcional)	`false`	Se definido como `true`, a varredura automática de fundos deste endereço é desabilitada.
`enableGaslessWithdraw`	Boolean (Opcional)	`false`	Se definido como `true`, permite saques sem exigir que o usuário pague taxas de gas diretamente.
`metadata`	Object (Opcional)	`null`	Metadados personalizados que você pode anexar ao endereço para sua própria referência ou finalidades de rastreamento.
`name`	String (Opcional)	`null`	Um nome legível para o endereço, útil para identificação no seu painel ou logs.
`showPrivateKey`	Boolean (Opcional)	`false`	Se definido como `true`, a chave privada para este endereço será retornada na resposta da API. Use com cautela.

Os parâmetros disableAutoSweep, enableGaslessWithdraw e showPrivateKey substituirão as configurações correspondentes na configuração da carteira mestra para este endereço específico. Isso permite um controle granular no nível do endereço, independentemente das configurações padrão da carteira.

Notas:

Todos esses parâmetros são opcionais; você só precisa incluir aqueles relevantes para seu caso de uso.
Habilitar showPrivateKey pode expor informações sensíveis. Use isso apenas em ambientes seguros e confiáveis.
Tenha cuidado com showPrivateKey, expor chaves privadas pode comprometer a segurança.

Criar um Endereço Dedicado

Você pode gerar um endereço dedicado para seu cliente usando o painel da Blockradar ou a API, dependendo do seu fluxo de trabalho e necessidades de integração.

1. Usando o Painel

O painel da Blockradar fornece uma interface simples e amigável para gerar novos endereços.

Esta captura de tela demonstra o processo de geração de um novo endereço através do painel da Blockradar. Este método é ideal para criação manual de endereços ou para equipes que preferem uma interface gráfica.

2. Usando a API

Para geração de endereços programática ou automatizada, você pode usar a API de Criar Endereço Dedicado. Isso é útil para integrar a criação de endereços em seus próprios aplicativos ou sistemas backend. Para criar um endereço dedicado para um cliente, envie uma solicitação POST para nossa API de Criar Endereço Dedicado.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "disableAutoSweep": "OPTIONAL_BOOLEAN",
  "enableGaslessWithdraw": "OPTIONAL_BOOLEAN",
  "metadata": "OPTIONAL_METADATA",
  "name": "OPTIONAL_ADDRESS_NAME",
  "showPrivateKey": "OPTIONAL_BOOLEAN"
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Resposta

{
  "data": {
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "blockchain": {
      "createdAt": "2024-05-14T11:53:33.095Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "85ffc132-3972-4c9e-99a5-5cf0ccb688bf",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800081/crypto-assets/ethereum-eth-logo_idraq2.png",
      "name": "ethereum",
      "slug": "ethereum",
      "symbol": "eth",
      "tokenStandard": "ERC20",
      "updatedAt": "2024-06-14T22:32:11.983Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      },
      "disableAutoSweep": false,
      "enableGaslessWithdraw": false,
      "showPrivateKey": false
    },
    "createdAt": "2024-10-23T11:13:40.446Z",
    "derivationPath": "m/44'/60'/0'/0/87",
    "id": "0a69c48a-6c6f-422c-bd6a-70de3306a3ac",
    "isActive": true,
    "metadata": {
      "user_id": 1
    },
    "name": "Customer 1",
    "network": "testnet",
    "type": "INTERNAL",
    "updatedAt": "2024-10-23T11:13:40.446Z"
  },
  "message": "Address generated successfully",
  "statusCode": 200
}

Emissão e Indexação de Endereços

A Blockradar separa duas coisas que antes aconteciam juntas ao criar um endereço:

Emitir (issue) um endereço é barato. Deriva um novo endereço da sua master wallet e o armazena, para que você possa entregá-lo a um cliente imediatamente.
Indexar um endereço é a parte custosa. Coloca o endereço sob monitoramento on-chain para que os depósitos sejam detectados em tempo real, e a indexação é a base da cobrança.

Isso permite emitir um endereço por cliente com antecedência e ativar a indexação apenas quando o cliente demonstrar intenção de depositar, de modo que você só paga pelos endereços que realmente monitora.

Dois interruptores independentes

Cada endereço tem duas configurações que controlam seu estado:

Configuração	Valores	Controla
`isActive`	`true` / `false`	O interruptor principal de liga/desliga. `false` desativa o endereço por completo.
`indexingStatus`	`ACTIVE` / `INACTIVE`	O interruptor de monitoramento e cobrança. `INACTIVE` significa inativo: não é monitorado nem cobrado.

Um endereço é monitorado on-chain e contabilizado para cobrança somente quando ambos estão ativados: isActive: true e indexingStatus: ACTIVE.

Os endereços existentes não são afetados. indexingStatus assume o valor ACTIVE por padrão, portanto cada endereço que você já criou, e cada endereço que você criar sem optar pelo contrário, se comporta exatamente como antes.

Emitir um endereço inativo

Ao gerar um endereço, passe enableIndexing: false para criar um endereço inativo que não é monitorado nem cobrado. Omita o campo ou passe true para o comportamento padrão (indexado imediatamente). Um endereço inativo retorna "indexingStatus": "INACTIVE" na resposta.

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": "Customer 123",
  "metadata": { "customerId": "123" },
  "enableIndexing": false
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"name":"Customer 123","metadata":{"customerId":"123"},"enableIndexing":false}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\": \"Customer 123\",\n  \"metadata\": { \"customerId\": \"123\" },\n  \"enableIndexing\": false\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Ativar a indexação

Ative a indexação quando o cliente demonstrar intenção de depositar. Isso inscreve o endereço, inicia o monitoramento em tempo real e o inclui na cobrança. A chamada não tem corpo e é idempotente (não faz nada se a indexação já estiver ativada). O parâmetro de rota addressId aceita tanto o UUID do endereço quanto a string do endereço on-chain. A resposta mostra "indexingStatus": "ACTIVE". Retorna 400 se o endereço tiver sido desativado (isActive: false).

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Desativar a indexação

Desative a indexação para clientes inativos ou que cancelaram, e assim parar de cobrar por endereços que você não monitora mais. Isso interrompe o monitoramento e remove o endereço da cobrança no próximo ciclo. A chamada não tem corpo e é idempotente. Os fundos já recebidos permanecem seguros on-chain, e você pode reativar a indexação mais tarde sem custo adicional além da cobrança normal. A resposta mostra "indexingStatus": "INACTIVE".

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Cobrança

A cobrança de endereços é uma contagem ao vivo feita a cada renovação, não uma cobrança por endereço. Em cada ciclo, a Blockradar conta os endereços que estão ativos e indexados na mainnet e cobra pelo uso acima do limite do seu plano.

Estado do endereço	Contabilizado para cobrança	Monitorado on-chain
Inativo (`indexingStatus: INACTIVE`)	Não — gratuito	Não
Indexado (`indexingStatus: ACTIVE`)	Sim	Sim
Desativado no meio do ciclo	Sai da próxima contagem	Não

Gerar endereços inativos não cobra nada, e desativar a indexação libera essa vaga no próximo ciclo.

Melhores práticas

Emita um endereço inativo quando atribuí-lo a um cliente. Não custa nada.
Ative a indexação quando o cliente demonstrar intenção de depositar (KYC aprovado, checkout aberto, tela de depósito visualizada).
Sempre ative a indexação antes de compartilhar um endereço para um depósito real, para que o depósito seja detectado em tempo real.
Desative a indexação para clientes inativos ou que cancelaram, e reative-a mais tarde quando necessário.

Os depósitos feitos em um endereço inativo não são detectados em tempo real. Se um cliente depositar em um endereço antes de a indexação estar ativada, os fundos ficam seguros on-chain, mas não são registrados automaticamente. Ative a indexação e acione o Localizador de Depósitos para recuperá-los. Sempre ative a indexação antes de compartilhar um endereço para evitar isso.

Lista de Permissões de Endereços

Este recurso permite que você adicione à lista de permissões um endereço externo para ser monitorado com base nos requisitos da carteira. Já possui carteiras emitidas por outro provedor? Você ainda pode conectá-las ao Blockradar e monitorar depósitos sem alterar sua configuração existente.

Parâmetros do Corpo

Chave	Obrigatório	Tipo	Descrição
`name`	false	string	O nome do endereço.
`address`	true	string	O endereço da carteira.
`metadata`	false	object	Metadados adicionais para o endereço. Isso fará parte de qualquer transação vinculada a isso.
`showPrivateKey`	false	boolean	Se você deseja que a chave privada do endereço faça parte da resposta.
`disableAutoSweep`	false	boolean	Desabilitar varredura automática de ativos enviados para o endereço em sua carteira mestra.
`enableGaslessWithdraw`	false	boolean	Habilitar transações sem gas a partir deste endereço.
`privateKey`	false	string	A chave privada associada ao endereço. Necessária para executar ações com segurança.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "name": "Whitelisted Address",
  "metadata": {"purpose": "external_monitoring", "source": "manual"},
  "showPrivateKey": false,
  "disableAutoSweep": false,
  "enableGaslessWithdraw": true,
  "privateKey": "0x1234567890abcdef..."
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"address":"ADDRESS_TO_WHITELIST","metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"address\": \"ADDRESS_TO_WHITELIST\",\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key": <api-key>
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Resposta

{
  "data": {
    "address": "0x3375154fa32Cb434B044E73a2582C4D2E6518AE4",
    "blockchain": {
      "createdAt": "2024-05-27T08:31:14.966Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "74733889-4ecd-403e-9840-94e87c043f24",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800080/crypto-assets/Base_Network_Logo_vqyh7r.png",
      "name": "base",
      "slug": "base",
      "symbol": "eth",
      "tokenStandard": null,
      "updatedAt": "2024-10-27T07:52:16.115Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      }
    },
    "createdAt": "2024-11-11T16:57:19.160Z",
    "derivationPath": null,
    "id": "b87901a2-45c1-4d2d-8ee7-205ef0c4ddf1",
    "isActive": true,
    "metadata": null,
    "name": "External address",
    "network": "testnet",
    "type": "EXTERNAL",
    "updatedAt": "2024-11-11T16:57:19.160Z"
  },
  "message": "Address whitelisted successfully",
  "statusCode": 200
}

Testes

Endereços gerados através de uma carteira mestra de testnet só podem receber ativos na testnet.

Aqui está uma lista de lugares onde você pode obter ativos de testnet para testar:

Ethereum - Obtenha USDC de teste aqui: Circle
Binance Smart Chain - Obtenha USDT de teste aqui: Binance
Polygon - Obtenha USDC de teste aqui: Circle
Base - Obtenha USDC de teste aqui: Circle
Tron - Obtenha USDT de teste aqui: Nileex
Solana - Obtenha USDC de teste aqui: Circle
Optimism - Obtenha USDC de teste aqui: Circle
Arbitrum - Obtenha USDC de teste aqui: Circle
Celo - Obtenha USDC de teste aqui: Circle

Bons hacks! 💚

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Pré-requisitos

Como Funciona

Parâmetros de Endereço Explicados

Criar um Endereço Dedicado

1. Usando o Painel

2. Usando a API

Resposta

Emissão e Indexação de Endereços

Dois interruptores independentes

Emitir um endereço inativo

Ativar a indexação

Desativar a indexação

Cobrança

Melhores práticas

Lista de Permissões de Endereços

Parâmetros do Corpo

Resposta

Testes

​Pré-requisitos

​Como Funciona

​Parâmetros de Endereço Explicados

​Criar um Endereço Dedicado

​1. Usando o Painel

​2. Usando a API

​Resposta

​Emissão e Indexação de Endereços

​Dois interruptores independentes

​Emitir um endereço inativo

​Ativar a indexação

​Desativar a indexação

​Cobrança

​Melhores práticas

​Lista de Permissões de Endereços

​Parâmetros do Corpo

​Resposta

​Testes

Pré-requisitos

Como Funciona

Parâmetros de Endereço Explicados

Criar um Endereço Dedicado

1. Usando o Painel

2. Usando a API

Resposta

Emissão e Indexação de Endereços

Dois interruptores independentes

Emitir um endereço inativo

Ativar a indexação

Desativar a indexação

Cobrança

Melhores práticas

Lista de Permissões de Endereços

Parâmetros do Corpo

Resposta

Testes