Recuperação de Ativos

Em resumo
A API de Asset Recovery do Blockradar permite recuperar ativos enviados por engano para o endereço correto na blockchain errada. Ela suporta a moeda nativa e ativos personalizados (ERC-20 e padrões compatíveis) em todas as redes suportadas.

O que é a Recuperação de Ativos?

A recuperação de ativos permite recuperar fundos enviados para o endereço de carteira correto, mas na rede blockchain errada. Isso costuma acontecer quando:

Usuários enviam ativos na Ethereum, mas queriam enviar na Polygon
Ativos são enviados na BNB Smart Chain em vez da Arbitrum
Ocorre qualquer confusão de endereço entre cadeias, já que o mesmo endereço existe em várias redes compatíveis com EVM

Como as blockchains compatíveis com EVM compartilham o mesmo formato de endereço, o mesmo endereço pode receber ativos em várias redes. A recuperação de ativos permite acessar esses fundos de forma programática.

Para um guia detalhado sobre os conceitos de recuperação de ativos e o uso no painel, leia nosso post no blog: How to Recover Assets Sent to the Wrong Blockchain

Pré-requisitos

Antes de usar a API de Asset Recovery, verifique se você tem:

Chave de API

Obtenha sua chave de API no Painel do Blockradar. Acesse Developers para gerar uma.

Carteira criada

Crie uma carteira no painel (consulte Criar uma Master Wallet). Você precisará do walletId para as operações de recuperação.

ID da blockchain

Obtenha o blockchainId da rede onde os ativos estão presos. Você o encontra no painel ou pela API Get Blockchains.

Saldo de moeda nativa

Garanta que o endereço de origem tenha moeda nativa suficiente (ETH, BNB, MATIC, etc.) na blockchain de recuperação para cobrir as taxas de gas.

Como funciona

A API de Asset Recovery transfere ativos de um endereço de origem (onde os ativos estão presos) para um endereço de destino na mesma blockchain:

Recuperação de moeda nativa

Recupere moedas nativas como ETH, BNB, MATIC ou AVAX enviadas para a rede errada.

Recuperação de ativos personalizados

Recupere ativos ERC-20 e compatíveis informando o endereço do contrato.

Estimativa de taxas

Calcule as taxas de rede antes da execução para garantir saldo suficiente.

Suporte a RPC personalizado

Recupere ativos em blockchains não suportadas informando seu próprio endpoint RPC.

Blockchains suportadas

A recuperação de ativos está disponível em todas as blockchains suportadas pelo Blockradar, incluindo redes compatíveis com EVM, Tron e Solana. Consulte Integrações para ver a lista completa de redes suportadas e os links de faucet.

Para redes EVM sem suporte direto, você pode informar uma URL de RPC personalizada e, opcionalmente, ativar o modo Layer 2 para redes baseadas em rollup.

Comece pelas testnets durante o desenvolvimento para não gastar fundos reais.

Recuperar ativos

Inicie uma operação de recuperação de ativos para transferir os ativos presos para um endereço de destino.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`senderAddress`	string	Sim	O endereço Blockradar onde os ativos estão presos atualmente.
`recipientAddress`	string	Sim	O endereço de destino para onde os ativos recuperados serão enviados.
`amount`	string	Sim	O valor a recuperar. Use o valor total ou uma parte dele.
`blockchainId`	string (UUID)	Sim	O UUID da blockchain onde a recuperação ocorrerá. Obtenha-o pela API Get Blockchains.
`tokenAddress`	string	Não	Endereço do contrato para a recuperação de ativos personalizados. Omita para a moeda nativa.
`crossNetwork`	boolean	Não	Defina como `true` para recuperar ativos enviados para o ambiente de rede errado (por exemplo, ativos de mainnet em um endereço derivado na testnet). O padrão é `false`.
`rpcUrl`	string	Não	Endpoint RPC personalizado para blockchains não suportadas. Não pode ser usado com `crossNetwork`.
`isL2`	boolean	Não	Defina como `true` se a URL de RPC apontar para uma rede Layer 2.

Recuperação de moeda nativa

Recupere a 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: YOUR_API_KEY' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "0.5",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
  }'

const response = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
      recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: '0.5',
      blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa'
    })
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
        'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
        'amount': '0.5',
        'blockchainId': 'polygon-mainnet'
    }
)

print(response.json())

Recuperação de ativos personalizados

Recupere ativos ERC-20 ou compatíveis informando o endereço do contrato:

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

const response = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
      recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: '100',
      blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
      tokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
    })
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
        'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
        'amount': '100',
        'blockchainId': 'polygon-mainnet',
        'tokenAddress': '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
    }
)

print(response.json())

Recuperação com RPC personalizado

Recupere ativos em blockchains não suportadas informando seu próprio endpoint RPC:

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

const response = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
      recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: '0.5',
      blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
      rpcUrl: 'https://rpc.custom-network.io',
      isL2: true
    })
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
        'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
        'amount': '0.5',
        'blockchainId': 'custom',
        'rpcUrl': 'https://rpc.custom-network.io',
        'isL2': True
    }
)

print(response.json())

Recuperação entre redes

Recupere ativos enviados por engano na mainnet para um endereço derivado na testnet, ou vice-versa. Isso funciona porque os endereços EVM, Tron e Solana são derivados das mesmas chaves, independentemente do ambiente de rede.

A recuperação entre redes exige blockchainId e não pode ser usada com rpcUrl. A blockchain deve ser a mesma da carteira: não é possível fazer uma recuperação entre cadeias e entre redes ao mesmo tempo.

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

const response = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
      recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: '100',
      blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
      tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
      crossNetwork: true
    })
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.blockradar.co/v1/wallets/{walletId}/salvage',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
        'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
        'amount': '100',
        'blockchainId': 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa',
        'tokenAddress': '0xdAC17F958D2ee523a2206206994597C13D831ec7',
        'crossNetwork': True
    }
)

print(response.json())

Quando crossNetwork está ativado, os metadados da transação incluem os campos crossNetwork: true e keyDerivationNetwork para fins de auditoria.

Resposta de sucesso

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

Estimativa de taxas de rede

Antes de executar uma recuperação, estime as taxas de rede para garantir saldo suficiente.

Requisição 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: YOUR_API_KEY' \
  --data '{
    "senderAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "recipientAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "0.5",
    "blockchainId": "b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa"
  }'

const response = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/salvage/network-fee',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      senderAddress: '0x1234567890abcdef1234567890abcdef12345678',
      recipientAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
      amount: '0.5',
      blockchainId: 'b80d3d5e-16f1-4d99-be5e-6dfcd27f89aa'
    })
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.blockradar.co/v1/wallets/{walletId}/salvage/network-fee',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'senderAddress': '0x1234567890abcdef1234567890abcdef12345678',
        'recipientAddress': '0xabcdef1234567890abcdef1234567890abcdef12',
        'amount': '0.5',
        'blockchainId': 'polygon-mainnet'
    }
)

print(response.json())

Parâmetros da resposta de taxa

Parâmetro	Descrição
`networkFee`	Taxa de gas estimada em unidades da moeda nativa
`networkFeeInUSD`	Taxa de gas convertida para USD
`nativeBalance`	Saldo atual de moeda nativa do endereço de origem
`nativeBalanceInUSD`	Saldo nativo convertido para USD

Sempre estime as taxas antes de executar operações de recuperação. O endereço de origem precisa ter moeda nativa suficiente para cobrir as taxas de gas na blockchain de recuperação.

Webhooks

Assine eventos de webhook para receber notificações em tempo real sobre as operações de recuperação.

Eventos de recuperação

Evento	Descrição
`salvage.success`	Disparado quando uma operação de recuperação é concluída com sucesso.
`salvage.failed`	Disparado quando uma operação de recuperação falha por saldo insuficiente, problemas de rede ou outros erros.
`salvage.cancelled`	Disparado quando uma operação de recuperação é cancelada antes da conclusão.

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 os webhooks no Painel do Blockradar em Settings → Webhooks. Consulte a documentação de Webhooks para ver as instruções de configuração.

Casos de uso comuns

Usuário enviou USDC na rede errada

Um usuário queria enviar USDC na Ethereum, mas enviou por engano na Polygon. Como o endereço é o mesmo, os fundos chegaram na Polygon. Use a recuperação de ativos com o endereço do contrato de USDC na Polygon para recuperar os fundos.

ETH enviado na Arbitrum em vez da Ethereum

Um usuário fez a ponte de ETH para a Arbitrum, mas o enviou para um endereço Blockradar. O mesmo endereço existe na Arbitrum graças à compatibilidade com EVM. Recupere o ETH da Arbitrum usando a recuperação de moeda nativa.

Ativo personalizado em Layer 2

Um usuário enviou um ativo ERC-20 personalizado em uma rede L2 como a Optimism. Informe o endereço do contrato do ativo e use a API de recuperação para recuperá-lo.

Ativos em rede não suportada

Os ativos estão presos em uma blockchain sem suporte direto do Blockradar. Informe seu próprio endpoint RPC e defina isL2: true se for um rollup para recuperar os fundos.

Ativos de mainnet enviados para um endereço derivado na testnet

Um usuário enviou USDT de mainnet para um endereço criado na testnet. Como a mesma chave privada deriva o mesmo endereço nas duas redes, use a recuperação entre redes com crossNetwork: true para recuperar os fundos de mainnet usando as chaves da carteira de testnet.

Tratamento de erros

Saldo nativo insuficiente

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

Solução: Abasteça o endereço de origem com moeda nativa suficiente para cobrir as taxas de gas antes de tentar novamente.

Endereço de origem inválido

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

Solução: Garanta que o endereço de origem pertença à sua carteira Blockradar e seja um child address válido.

Ativo não encontrado

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

Solução: Verifique o endereço do contrato e a blockchain. Use um explorador de blocos para confirmar que o ativo existe no endereço de origem.

Falha na conexão com o RPC

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

Solução: Verifique se a sua URL de RPC está correta e acessível. Garanta que ela suporte os métodos JSON-RPC necessários.

Boas práticas

Sempre estime as taxas primeiro

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

Verifique os endereços

Confira os endereços de origem e de destino em um explorador de blocos antes de iniciar a recuperação.

Use webhooks

Configure webhooks para receber atualizações de status em tempo real em vez de consultar a API periodicamente.

Teste na testnet

Teste sua integração de recuperação na testnet antes de usá-la em produção.

Referência da API

Endpoint	Descrição
Salvage	Iniciar a operação de recuperação de ativos
Salvage Network Fee	Estimar as taxas de rede da recuperação

Boas recuperações!

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Recuperação de Ativos

O que é a Recuperação de Ativos?

Pré-requisitos

Como funciona

Recuperação de moeda nativa

Recuperação de ativos personalizados

Estimativa de taxas

Suporte a RPC personalizado

Blockchains suportadas

Recuperar ativos

Parâmetros da requisição

Recuperação de moeda nativa

Recuperação de ativos personalizados

Recuperação com RPC personalizado

Recuperação entre redes

Resposta de sucesso

Estimativa de taxas de rede

Requisição de estimativa de taxa

Parâmetros da resposta de taxa

Webhooks

Eventos de recuperação

Payload do Webhook

Casos de uso comuns

Tratamento de erros

Boas práticas

Sempre estime as taxas primeiro

Verifique os endereços

Use webhooks

Teste na testnet

Referência da API

​O que é a Recuperação de Ativos?

​Pré-requisitos

​Como funciona

Recuperação de moeda nativa

Recuperação de ativos personalizados

Estimativa de taxas

Suporte a RPC personalizado

​Blockchains suportadas

​Recuperar ativos

​Parâmetros da requisição

​Recuperação de moeda nativa

​Recuperação de ativos personalizados

​Recuperação com RPC personalizado

​Recuperação entre redes

​Resposta de sucesso

​Estimativa de taxas de rede

​Requisição de estimativa de taxa

​Parâmetros da resposta de taxa

​Webhooks

​Eventos de recuperação

​Payload do Webhook

​Casos de uso comuns

​Tratamento de erros

​Boas práticas

Sempre estime as taxas primeiro

Verifique os endereços

Use webhooks

Teste na testnet

​Referência da API

O que é a Recuperação de Ativos?

Pré-requisitos

Como funciona

Blockchains suportadas

Recuperar ativos

Parâmetros da requisição

Recuperação de moeda nativa

Recuperação de ativos personalizados

Recuperação com RPC personalizado

Recuperação entre redes

Resposta de sucesso

Estimativa de taxas de rede

Requisição de estimativa de taxa

Parâmetros da resposta de taxa

Webhooks

Eventos de recuperação

Payload do Webhook

Casos de uso comuns

Tratamento de erros

Boas práticas

Referência da API