Recuperacao de Ativos

Em resumo
A API de Recuperacao de Ativos da Blockradar permite que voce recupere ativos que foram acidentalmente enviados para o endereco correto na blockchain errada. Ela suporta moeda nativa e ativos personalizados (ERC-20 e padroes compativeis) em todas as redes suportadas.

O que e Recuperacao de Ativos?

A recuperacao de ativos permite que voce recupere fundos que foram enviados para o endereco de carteira correto, mas na rede blockchain errada. Isso comumente acontece quando:

Usuarios enviam ativos no Ethereum mas queriam enviar no Polygon
Ativos sao enviados na BNB Smart Chain em vez do Arbitrum
Qualquer confusao de enderecos entre cadeias onde o mesmo endereco existe em multiplas redes compativeis com EVM

Como blockchains compativeis com EVM compartilham o mesmo formato de endereco, o mesmo endereco pode receber ativos em multiplas redes. A recuperacao de ativos permite que voce acesse esses fundos programaticamente.

Para um guia detalhado sobre conceitos de recuperacao de ativos e uso do painel, leia nosso artigo: Como Recuperar Ativos Enviados para a Blockchain Errada

Pre-requisitos

Antes de usar a API de Recuperacao de Ativos, certifique-se de ter:

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue ate Configuracoes → Chaves API para gerar uma.

Carteira Criada

Crie uma carteira atraves da API Criar Carteira ou do painel. Voce precisara do walletId para operacoes de recuperacao.

ID da Blockchain

Obtenha o blockchainId para a rede onde os ativos estao presos. Voce pode encontra-lo no painel ou atraves da API Obter Blockchains.

Saldo de Moeda Nativa

Certifique-se de que o endereco remetente tenha moeda nativa suficiente (ETH, BNB, MATIC, etc.) na blockchain de recuperacao para cobrir as taxas de gas.

Como Funciona

A API de Recuperacao de Ativos transfere ativos de um endereco remetente (onde os ativos estao presos) para um endereco destinatario na mesma blockchain:

Recuperacao de Moeda Nativa

Recupere moeda nativa como ETH, BNB, MATIC ou AVAX enviada para a rede errada.

Recuperacao de Ativos Personalizados

Recupere ativos ERC-20 e compativeis especificando o endereco do contrato.

Estimativa de Taxas

Calcule as taxas de rede antes da execucao para garantir saldo suficiente.

Suporte a RPC Personalizado

Recupere ativos em blockchains nao suportadas fornecendo seu proprio endpoint RPC.

Blockchains Suportadas

A recuperacao de ativos esta disponivel em todas as blockchains suportadas pela Blockradar, incluindo redes compativeis com EVM, Tron e Solana. Consulte Integracoes para a lista completa de redes suportadas e links de faucets.

Para redes EVM nao diretamente suportadas, voce pode fornecer uma URL RPC personalizada e opcionalmente habilitar o modo Layer 2 para redes baseadas em rollup.

Comece com testnets durante o desenvolvimento para evitar gastar fundos reais.

Recuperar Ativos

Inicie uma operacao de recuperacao de ativos para transferir ativos presos para um endereco destinatario.

Parametros da Requisicao

Parametro	Tipo	Obrigatorio	Descricao
`senderAddress`	string	Sim	O endereco Blockradar onde os ativos estao atualmente presos.
`recipientAddress`	string	Sim	O endereco de destino para onde os ativos recuperados serao enviados.
`amount`	string	Sim	A quantidade a recuperar. Use a quantidade total ou uma porcao.
`blockchainId`	string (UUID)	Sim	O UUID da blockchain onde a recuperacao ocorrera. Obtenha-o via API Obter Blockchains.
`tokenAddress`	string	Nao	Endereco do contrato para recuperacao de ativos personalizados. Omita para moeda nativa.
`rpcUrl`	string	Nao	Endpoint RPC personalizado para blockchains nao suportadas.
`isL2`	boolean	Nao	Defina como `true` se a URL RPC apontar para uma rede Layer 2.

Recuperacao de Moeda Nativa

Recupere moeda nativa (ETH, BNB, MATIC, etc.) da rede errada:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/salvage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: SUA_CHAVE_API' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "0.5",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
  }'

Recuperacao de Ativos Personalizados

Recupere ativos ERC-20 ou compativeis especificando o endereco do contrato:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/salvage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: SUA_CHAVE_API' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "100",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa",
    "tokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
  }'

Recuperacao com RPC Personalizado

Recupere ativos em blockchains nao suportadas fornecendo seu proprio endpoint RPC:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/salvage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: SUA_CHAVE_API' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "0.5",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa",
    "rpcUrl": "https://rpc.custom-network.io",
    "isL2": true
  }'

Resposta de Sucesso

{
  "message": "Salvage asset initiated successfully",
  "statusCode": 200
}

Estimativa de Taxa de Rede

Antes de executar uma recuperacao, estime as taxas de rede para garantir saldo suficiente.

Requisicao de Estimativa de Taxa

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/salvage/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: SUA_CHAVE_API' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "0.5",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
  }'

Parametros de Resposta de Taxa

Parametro	Descricao
`networkFee`	Taxa de gas estimada em unidades de moeda nativa
`networkFeeInUSD`	Taxa de gas convertida para USD
`nativeBalance`	Saldo atual de moeda nativa do remetente
`nativeBalanceInUSD`	Saldo nativo convertido para USD

Sempre estime as taxas antes de executar operacoes de recuperacao. O endereco remetente deve ter moeda nativa suficiente para cobrir as taxas de gas na blockchain de recuperacao.

Webhooks

Inscreva-se em eventos de webhook para receber notificacoes em tempo real sobre operacoes de recuperacao.

Eventos de Recuperacao

Evento	Descricao
`salvage.success`	Acionado quando uma operacao de recuperacao e concluida com sucesso.
`salvage.failed`	Acionado quando uma operacao de recuperacao falha devido a fundos insuficientes, problemas de rede ou outros erros.
`salvage.cancelled`	Acionado quando uma operacao de recuperacao e cancelada antes da conclusao.

Payload do Webhook

{
  "event": "salvage.success",
  "data": {
    "id": "txn_abc123",
    "type": "SALVAGE",
    "status": "SUCCESS",
    "amount": "0.5",
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "blockchain": "polygon-mainnet",
    "txHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
    "networkFee": "0.001",
    "createdAt": "2025-01-12T10:30:00Z"
  }
}

Configure webhooks no Painel da Blockradar em Configuracoes → Webhooks. Consulte a documentacao de Webhooks para instrucoes de configuracao.

Casos de Uso Comuns

Usuario enviou USDC na rede errada

Um usuario queria enviar USDC no Ethereum mas acidentalmente enviou no Polygon. Como o endereco e o mesmo, os fundos chegaram no Polygon. Use a recuperacao de ativos com o endereco do contrato USDC no Polygon para recuperar os fundos.

ETH enviado para Arbitrum em vez de Ethereum

Um usuario fez bridge de ETH para Arbitrum mas enviou para um endereco Blockradar. O mesmo endereco existe no Arbitrum devido a compatibilidade EVM. Recupere o ETH do Arbitrum usando a recuperacao de moeda nativa.

Ativo personalizado em Layer 2

Um usuario enviou um ativo ERC-20 personalizado em uma rede L2 como Optimism. Forneca o endereco do contrato do ativo e use a API de recuperacao para recupera-lo.

Ativos em rede nao suportada

Ativos estao presos em uma blockchain nao suportada diretamente pela Blockradar. Forneca seu proprio endpoint RPC e defina isL2: true se for um rollup para recuperar os fundos.

Tratamento de Erros

Saldo Nativo Insuficiente

{
  "error": "Insufficient native balance for gas",
  "code": "INSUFFICIENT_GAS",
  "details": {
    "required": "0.01",
    "available": "0.001",
    "currency": "MATIC"
  }
}

Solucao: Financie o endereco remetente com moeda nativa suficiente para cobrir as taxas de gas antes de tentar novamente.

Endereco Remetente Invalido

{
  "error": "Sender address not found in wallet",
  "code": "INVALID_SENDER"
}

Solucao: Certifique-se de que o endereco remetente pertence a sua carteira Blockradar e e um endereco filho valido.

Ativo Nao Encontrado

{
  "error": "No balance found for specified asset",
  "code": "ASSET_NOT_FOUND",
  "details": {
    "tokenAddress": "0x...",
    "blockchain": "polygon-mainnet"
  }
}

Solucao: Verifique o endereco do contrato e a blockchain. Use um explorador de blocos para confirmar que o ativo existe no endereco remetente.

Falha na Conexao RPC

{
  "error": "Failed to connect to custom RPC",
  "code": "RPC_ERROR"
}

Solucao: Verifique se sua URL RPC esta correta e acessivel. Certifique-se de que ela suporta os metodos JSON-RPC necessarios.

Melhores Praticas

Sempre Estime Taxas Primeiro

Use o endpoint de taxa de rede antes da recuperacao para garantir saldo de gas suficiente e exibir custos precisos.

Verifique Enderecos

Verifique os enderecos remetente e destinatario usando um explorador de blocos antes de iniciar a recuperacao.

Use Webhooks

Configure webhooks para receber atualizacoes de status em tempo real em vez de consultar a API.

Teste na Testnet

Teste sua integracao de recuperacao na testnet antes de usa-la em producao.

Referencia da API

Endpoint	Descricao
Salvage	Iniciar operacao de recuperacao de ativos
Salvage Network Fee	Estimar taxas de rede para recuperacao

Boa recuperacao!

Começar

Essenciais

Recuperacao de Ativos

O que e Recuperacao de Ativos?

Pre-requisitos

Como Funciona

Recuperacao de Moeda Nativa

Recuperacao de Ativos Personalizados

Estimativa de Taxas

Suporte a RPC Personalizado

Blockchains Suportadas

Recuperar Ativos

Parametros da Requisicao

Recuperacao de Moeda Nativa

Recuperacao de Ativos Personalizados

Recuperacao com RPC Personalizado

Resposta de Sucesso

Estimativa de Taxa de Rede

Requisicao de Estimativa de Taxa

Parametros de Resposta de Taxa

Webhooks

Eventos de Recuperacao

Payload do Webhook

Casos de Uso Comuns

Tratamento de Erros

Melhores Praticas

Sempre Estime Taxas Primeiro

Verifique Enderecos

Use Webhooks

Teste na Testnet

Referencia da API

Começar

Essenciais

​O que e Recuperacao de Ativos?

​Pre-requisitos

​Como Funciona

Recuperacao de Moeda Nativa

Recuperacao de Ativos Personalizados

Estimativa de Taxas

Suporte a RPC Personalizado

​Blockchains Suportadas

​Recuperar Ativos

​Parametros da Requisicao

​Recuperacao de Moeda Nativa

​Recuperacao de Ativos Personalizados

​Recuperacao com RPC Personalizado

​Resposta de Sucesso

​Estimativa de Taxa de Rede

​Requisicao de Estimativa de Taxa

​Parametros de Resposta de Taxa

​Webhooks

​Eventos de Recuperacao

​Payload do Webhook

​Casos de Uso Comuns

​Tratamento de Erros

​Melhores Praticas

Sempre Estime Taxas Primeiro

Verifique Enderecos

Use Webhooks

Teste na Testnet

​Referencia da API

O que e Recuperacao de Ativos?

Pre-requisitos

Como Funciona

Blockchains Suportadas

Recuperar Ativos

Parametros da Requisicao

Recuperacao de Moeda Nativa

Recuperacao de Ativos Personalizados

Recuperacao com RPC Personalizado

Resposta de Sucesso

Estimativa de Taxa de Rede

Requisicao de Estimativa de Taxa

Parametros de Resposta de Taxa

Webhooks

Eventos de Recuperacao

Payload do Webhook

Casos de Uso Comuns

Tratamento de Erros

Melhores Praticas

Referencia da API