资产恢复

简而言之
Blockradar 资产恢复 API 允许您找回意外发送到正确地址、但错误区块链上的资产。它支持在所有受支持的网络上恢复原生代币和自定义资产（ERC-20 及兼容标准）。

什么是资产恢复？

资产恢复可以帮助您找回发送到正确钱包地址、但发错区块链网络的资金。这种情况通常发生在：

用户本想在 Polygon 上发送资产，却在 Ethereum 上发送了
资产被发送到 BNB Smart Chain，而不是 Arbitrum
同一地址存在于多个 EVM 兼容网络上时出现的任何跨链地址混淆

由于 EVM 兼容区块链共享相同的地址格式，同一地址可以在多个网络上接收资产。资产恢复让您能够以编程方式取回这些资金。

如需了解资产恢复概念和控制台使用方法的详细指南，请阅读我们的博客文章：How to Recover Assets Sent to the Wrong Blockchain

前提条件

在使用资产恢复 API 之前，请确保您已具备：

API 密钥

从 Blockradar 控制台获取您的 API 密钥。前往 Developers 生成密钥。

已创建钱包

在控制台中（参见创建主钱包）创建钱包。恢复操作需要使用 walletId。

区块链 ID

获取资产滞留所在网络的 blockchainId。您可以在控制台中或通过 Get Blockchains API 找到它。

原生代币余额

确保来源地址在恢复所用的区块链上有足够的原生代币（ETH、BNB、MATIC 等）来支付 gas 费用。

工作原理

资产恢复 API 会将资产从来源地址（资产滞留的地址）转移到同一区块链上的目标地址：

原生代币恢复

恢复发送到错误网络的 ETH、BNB、MATIC 或 AVAX 等原生代币。

自定义资产恢复

通过指定合约地址，恢复 ERC-20 及兼容资产。

费用估算

在执行前计算网络费用，确保余额充足。

自定义 RPC 支持

通过提供您自己的 RPC 端点，在不受支持的区块链上恢复资产。

支持的区块链

资产恢复适用于 Blockradar 支持的所有区块链，包括 EVM 兼容网络、Tron 和 Solana。完整的受支持网络列表和水龙头链接请参见集成。

对于未被直接支持的 EVM 网络，您可以提供自定义 RPC URL，并可为基于 rollup 的网络启用二层网络（Layer 2）模式。

开发期间请先使用测试网，以免花费真实资金。

恢复资产

发起资产恢复操作，将滞留的资产转移到目标地址。

请求参数

参数	类型	必填	描述
`senderAddress`	string	Yes	资产当前滞留的 Blockradar 地址。
`recipientAddress`	string	Yes	接收恢复资产的目标地址。
`amount`	string	Yes	要恢复的金额。可以是全部金额，也可以是部分金额。
`blockchainId`	string (UUID)	Yes	执行恢复的区块链 UUID。可通过 Get Blockchains API 获取。
`tokenAddress`	string	No	恢复自定义资产时使用的合约地址。恢复原生代币时省略。
`crossNetwork`	boolean	No	设为 `true` 可恢复发送到错误网络环境的资产（例如发送到由测试网派生地址上的主网资产）。默认为 `false`。
`rpcUrl`	string	No	用于不受支持区块链的自定义 RPC 端点。不能与 `crossNetwork` 同时使用。
`isL2`	boolean	No	如果 RPC URL 指向二层网络，请设为 `true`。

原生代币恢复

从错误网络恢复原生代币（ETH、BNB、MATIC 等）：

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())

自定义资产恢复

通过指定合约地址，恢复 ERC-20 或兼容资产：

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())

自定义 RPC 恢复

通过提供您自己的 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())

跨网络恢复

恢复意外发送到主网上某个由测试网派生的地址的资产，反之亦然。之所以可行，是因为 EVM、Tron 和 Solana 地址无论处于哪种网络环境，都由相同的密钥派生。

跨网络恢复需要提供 blockchainId，且不能与 rpcUrl 同时使用。区块链必须与钱包所在的区块链一致——您不能同时进行跨链和跨网络恢复。

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())

启用 crossNetwork 后，交易元数据中将包含 crossNetwork: true 和 keyDerivationNetwork 字段，便于审计。

成功响应

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

网络费用估算

在执行恢复之前，请先估算网络费用，以确保余额充足。

费用估算请求

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())

费用响应参数

参数	描述
`networkFee`	以原生代币单位计的预估 gas 费用
`networkFeeInUSD`	换算为美元的 gas 费用
`nativeBalance`	来源地址当前的原生代币余额
`nativeBalanceInUSD`	换算为美元的原生代币余额

执行恢复操作前务必先估算费用。来源地址必须持有足够的原生代币，以支付恢复所用区块链上的 gas 费用。

Webhooks

订阅 webhook 事件，即可实时接收有关恢复操作的通知。

恢复事件

事件	描述
`salvage.success`	恢复操作成功完成时触发。
`salvage.failed`	恢复操作因资金不足、网络问题或其他错误而失败时触发。
`salvage.cancelled`	恢复操作在完成前被取消时触发。

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

在 Blockradar 控制台的 Settings → Webhooks 中配置 webhook。设置说明请参见 Webhooks 文档。

常见用例

用户在错误的网络上发送了 USDC

用户本想在 Ethereum 上发送 USDC，却意外在 Polygon 上发送了。由于地址相同，资金到达了 Polygon。使用 Polygon 上的 USDC 合约地址进行资产恢复，即可取回资金。

ETH 发送到了 Arbitrum 而非 Ethereum

用户将 ETH 跨链桥接到 Arbitrum，却发送到了一个 Blockradar 地址。由于 EVM 兼容性，同一地址也存在于 Arbitrum 上。使用原生代币恢复，从 Arbitrum 取回 ETH。

二层网络上的自定义资产

用户在 Optimism 等 L2 网络上发送了自定义 ERC-20 资产。提供该资产的合约地址，并使用恢复 API 将其取回。

不受支持网络上的资产

资产滞留在 Blockradar 未直接支持的区块链上。提供您自己的 RPC 端点，如果该链是 rollup，请设置 isL2: true，即可恢复资金。

主网资产发送到了由测试网派生的地址

用户将主网 USDT 发送到了一个在测试网上创建的地址。由于同一私钥在两个网络上派生出相同的地址，可以使用 crossNetwork: true 进行跨网络恢复，用测试网钱包的密钥取回主网资金。

错误处理

原生代币余额不足

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

解决方法：为来源地址充入足够的原生代币以支付 gas 费用，然后重试。

无效的来源地址

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

解决方法：确保来源地址属于您的 Blockradar 钱包，并且是有效的子地址。

未找到资产

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

解决方法：核对合约地址和区块链。使用区块浏览器确认该资产确实存在于来源地址。

RPC 连接失败

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

解决方法：确认您的 RPC URL 正确且可访问，并确保它支持所需的 JSON-RPC 方法。

最佳实践

始终先估算费用

恢复前调用网络费用端点，确保 gas 余额充足并展示准确的成本。

核对地址

发起恢复前，使用区块浏览器再次核对来源地址和目标地址。

使用 Webhooks

配置 webhook 以接收实时状态更新，而不是轮询 API。

在测试网上测试

在生产环境中使用之前，先在测试网上测试您的恢复集成。

API 参考

端点	描述
Salvage	发起资产恢复操作
Salvage Network Fee	估算恢复所需的网络费用

恢复愉快！

开始使用

钱包

收款

付款

转换与管理

合规与工具

什么是资产恢复？

前提条件

工作原理

原生代币恢复

自定义资产恢复

费用估算

自定义 RPC 支持

支持的区块链

恢复资产

请求参数

原生代币恢复

自定义资产恢复

自定义 RPC 恢复

跨网络恢复

成功响应

网络费用估算

费用估算请求

费用响应参数

Webhooks

恢复事件

Webhook 载荷

常见用例

错误处理

最佳实践

始终先估算费用

核对地址

使用 Webhooks

在测试网上测试

API 参考

​什么是资产恢复？

​前提条件

​工作原理

原生代币恢复

自定义资产恢复

费用估算

自定义 RPC 支持

​支持的区块链

​恢复资产

​请求参数

​原生代币恢复

​自定义资产恢复

​自定义 RPC 恢复

​跨网络恢复

​成功响应

​网络费用估算

​费用估算请求

​费用响应参数

​Webhooks

​恢复事件

​Webhook 载荷

​常见用例

​错误处理

​最佳实践

始终先估算费用

核对地址

使用 Webhooks

在测试网上测试

​API 参考

什么是资产恢复？

前提条件

工作原理

支持的区块链

恢复资产

请求参数

原生代币恢复

自定义资产恢复

自定义 RPC 恢复

跨网络恢复

成功响应

网络费用估算

费用估算请求

费用响应参数

Webhooks

恢复事件

Webhook 载荷

常见用例

错误处理

最佳实践

API 参考