Smart Contracts - Blockradar

简而言之
Blockradar 的 Smart Contract API 让您可以直接从钱包与任何智能合约交互，无需自行管理 RPC 端点、签名流程或合约部署。

先决条件

在使用 Smart Contract API 之前，请确保您已具备：

API 密钥

从 Blockradar Dashboard 获取您的 API 密钥。前往 Developers 即可生成。

已创建钱包

通过 Create Wallet API 或 dashboard 创建钱包。所有智能合约操作都需要 walletId。

原生币余额

为您的钱包充值原生币（ETH、BNB、MATIC 等）以支付 gas 费用。在执行前，使用 Network Fee 端点估算成本。

支持的区块链

Smart Contract API 支持 Blockradar 上提供的所有 EVM 兼容区块链以及 Tron。请参阅 Integrations 查看支持的网络完整列表和 faucet 链接。

Solana 不支持智能合约交互。Smart Contract API 仅适用于 EVM 兼容链和 Tron。

开发期间从 testnet 开始，避免消耗真实资金。

简介

Smart Contract API 将 Blockradar 从一个钱包基础设施转变为一个可编程的执行层。您可以读取合约状态、执行合约函数、估算 gas 费用并签名交易——全部通过统一的 API 接口完成。

读取操作

从受支持的区块链上的任何智能合约检索数据。

写入操作

执行智能合约函数，并完整管理交易。

费用估算

在执行前计算 gas 成本，以确保资金充足。

批量操作

在单个 API 请求中执行多个合约调用。

用例

Smart Contract API 为金融科技开发者解锁强大的能力：

DeFi 集成：连接到 Uniswap、Aave 或 Compound 等协议，进行收益和流动性管理
资金运营：在您的金融科技平台内自动化资金管理
代币化资产：将真实世界资产集成到产品流程中
可编程结算：执行合规检查和自动化结算
自定义资产：管理自定义资产、奖励系统和忠诚度计划

Master Wallet vs Child Address

Smart Contract API 提供两个层级：

Master Wallet

直接从您的 master wallet 执行合约操作。非常适合资金运营和集中式资金管理。

Child Address

从单个 child address 执行合约操作。非常适合特定用户的操作和分隔式资金管理。

Master Wallet 端点

操作	端点	描述
读取	`POST /v1/wallets/{walletId}/contracts/read`	从智能合约检索数据
写入	`POST /v1/wallets/{walletId}/contracts/write`	执行智能合约函数
Network Fee	`POST /v1/wallets/{walletId}/contracts/network-fee`	估算 gas 成本
Sign Only	`POST /v1/wallets/{walletId}/contracts/write/sign`	签名但不广播

Child Address 端点

操作	端点	描述
读取	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/read`	从智能合约检索数据
写入	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write`	执行智能合约函数
Network Fee	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee`	估算 gas 成本
Sign Only	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/sign`	签名但不广播

请求结构

所有智能合约请求都需要以下参数：

参数	类型	必填	描述
`address`	string	是	智能合约的区块链地址
`method`	string	是	要调用的函数名称
`parameters`	array	是	与函数 ABI 顺序匹配的参数
`abi`	array	是	合约的 Application Binary Interface
`reference`	string	否	您用于跟踪交易的内部 ID
`metadata`	object	否	用于附加交易详情的自定义键值对

reference 和 metadata 字段仅适用于写入操作。读取操作不支持这些字段。

理解 ABI

ABI（Application Binary Interface）定义了如何与智能合约交互。您可以从以下渠道获取 ABI：

区块浏览器：Etherscan、BscScan、PolygonScan（已验证的合约）
协议文档：DeFi 协议的官方文档
合约源代码：从 Solidity 源代码编译

读取合约数据

使用读取端点查询合约状态，而不修改区块链。

Master Wallet 读取示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/read \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
    "method": "balanceOf",
    "parameters": ["0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"],
    "abi": [{
      "constant": true,
      "inputs": [{"name": "account", "type": "address"}],
      "name": "balanceOf",
      "outputs": [{"name": "", "type": "uint256"}],
      "stateMutability": "view",
      "type": "function"
    }]
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/read`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      address: '0x337610d27c682E347C9cD60BD4b3b107C9d34dDd',
      method: 'balanceOf',
      parameters: ['0x947514e4B803e312C312da0F1B41fEDdbe15ae7a'],
      abi: [{
        constant: true,
        inputs: [{ name: 'account', type: 'address' }],
        name: 'balanceOf',
        outputs: [{ name: '', type: 'uint256' }],
        stateMutability: 'view',
        type: 'function'
      }]
    })
  }
);

Child Address 读取示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/contracts/read \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
    "method": "balanceOf",
    "parameters": ["0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"],
    "abi": [{
      "constant": true,
      "inputs": [{"name": "account", "type": "address"}],
      "name": "balanceOf",
      "outputs": [{"name": "", "type": "uint256"}],
      "stateMutability": "view",
      "type": "function"
    }]
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/contracts/read`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      address: '0x337610d27c682E347C9cD60BD4b3b107C9d34dDd',
      method: 'balanceOf',
      parameters: ['0x947514e4B803e312C312da0F1B41fEDdbe15ae7a'],
      abi: [{
        constant: true,
        inputs: [{ name: 'account', type: 'address' }],
        name: 'balanceOf',
        outputs: [{ name: '', type: 'uint256' }],
        stateMutability: 'view',
        type: 'function'
      }]
    })
  }
);

读取响应

{
  "message": "Contract read successfully",
  "statusCode": 200,
  "data": "10052335235393043"
}

读取错误响应

无效的合约地址

{
  "message": "Invalid contract address",
  "statusCode": 400,
  "error": "BAD_REQUEST"
}

未找到方法

{
  "message": "Method 'balanceOf' not found in ABI",
  "statusCode": 400,
  "error": "ABI_METHOD_NOT_FOUND"
}

合约执行被回滚

{
  "message": "Contract execution reverted",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: balance query for zero address"
  }
}

无效的参数

{
  "message": "Parameter count mismatch. Expected 1, got 2",
  "statusCode": 400,
  "error": "INVALID_PARAMETERS"
}

写入合约

执行更改智能合约状态的函数。

Master Wallet 写入示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/write \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0xYOUR_TOKEN_CONTRACT",
    "method": "approve",
    "parameters": ["0xYOUR_SPENDER_ADDRESS", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/write`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      address: '0xYOUR_TOKEN_CONTRACT',
      method: 'approve',
      parameters: ['0xYOUR_SPENDER_ADDRESS', '1000000000000000000'],
      abi: [{
        inputs: [
          { name: 'spender', type: 'address' },
          { name: 'amount', type: 'uint256' }
        ],
        name: 'approve',
        outputs: [{ name: '', type: 'bool' }],
        stateMutability: 'nonpayable',
        type: 'function'
      }]
    })
  }
);

Child Address 写入示例

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/contracts/write \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0xYOUR_TOKEN_CONTRACT",
    "method": "approve",
    "parameters": ["0xYOUR_SPENDER_ADDRESS", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/contracts/write`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      address: '0xYOUR_TOKEN_CONTRACT',
      method: 'approve',
      parameters: ['0xYOUR_SPENDER_ADDRESS', '1000000000000000000'],
      abi: [{
        inputs: [
          { name: 'spender', type: 'address' },
          { name: 'amount', type: 'uint256' }
        ],
        name: 'approve',
        outputs: [{ name: '', type: 'bool' }],
        stateMutability: 'nonpayable',
        type: 'function'
      }]
    })
  }
);

写入响应

{
  "message": "Contract write initiated",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "PENDING"
  }
}

写入操作是异步的。初始响应显示 PENDING 状态。请监听 custom-smart-contract.success webhook 以确认交易完成。

写入错误响应

Gas 不足

{
  "message": "Insufficient native token balance for gas",
  "statusCode": 400,
  "error": "INSUFFICIENT_GAS",
  "data": {
    "required": "0.005",
    "available": "0.001",
    "token": "ETH"
  }
}

余额不足

{
  "message": "Insufficient token balance",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "1000000000000000000",
    "available": "500000000000000000"
  }
}

交易被回滚

{
  "message": "Transaction would revert",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: transfer amount exceeds allowance"
  }
}

无效的 ABI

{
  "message": "Invalid ABI format",
  "statusCode": 400,
  "error": "INVALID_ABI",
  "data": {
    "details": "Missing 'inputs' field in ABI definition"
  }
}

未找到钱包

{
  "message": "Wallet not found",
  "statusCode": 404,
  "error": "NOT_FOUND"
}

估算网络费用

在执行写入操作之前始终估算费用，以确保您的钱包有足够的原生币。

Master Wallet 费用估算

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0xYOUR_TOKEN_CONTRACT",
    "method": "approve",
    "parameters": ["0xYOUR_SPENDER_ADDRESS", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'

Child Address 费用估算

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "address": "0xYOUR_TOKEN_CONTRACT",
    "method": "approve",
    "parameters": ["0xYOUR_SPENDER_ADDRESS", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'

费用响应

{
  "message": "Network fee retrieved",
  "statusCode": 200,
  "data": {
    "networkFee": "0.00001247904",
    "networkFeeInUSD": "0.01",
    "nativeBalance": "0.5",
    "nativeBalanceInUSD": "450.00",
    "estimatedArrivalTime": 30
  }
}

实践示例：在 Uniswap 上进行资产兑换

本节演示了执行资产兑换的两种方法：不使用批量操作（顺序调用）和使用批量操作（单次 API 调用）。

示例 1：不使用批量操作的资产兑换

此方法为每个步骤进行单独的 API 调用。当您需要对每笔交易进行精细控制，或当操作依赖于先前调用的结果时，请使用此方法。

步骤 1：检查资产余额

const balanceOfAbi = {
  constant: true,
  inputs: [{ name: 'account', type: 'address' }],
  name: 'balanceOf',
  outputs: [{ name: '', type: 'uint256' }],
  stateMutability: 'view',
  type: 'function'
};

const balance = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/read`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      address: TOKEN_ADDRESS,
      method: 'balanceOf',
      parameters: [walletAddress],
      abi: [balanceOfAbi]
    })
  }
).then(r => r.json());

console.log('Asset Balance:', balance.data);

步骤 2：批准资产花费

const approveAbi = {
  inputs: [
    { name: 'spender', type: 'address' },
    { name: 'amount', type: 'uint256' }
  ],
  name: 'approve',
  outputs: [{ name: '', type: 'bool' }],
  stateMutability: 'nonpayable',
  type: 'function'
};

const approval = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/write`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      address: TOKEN_ADDRESS,
      method: 'approve',
      parameters: [UNISWAP_ROUTER, amountIn],
      abi: [approveAbi]
    })
  }
).then(r => r.json());

console.log('Approval TX:', approval.data.hash);
// IMPORTANT: Wait for webhook confirmation before proceeding

在执行 swap 之前，请始终等待 custom-smart-contract.success webhook 确认批准交易已被打包。

步骤 3：估算 swap 费用

const swapAbi = {
  inputs: [
    { name: 'amountIn', type: 'uint256' },
    { name: 'amountOutMin', type: 'uint256' },
    { name: 'path', type: 'address[]' },
    { name: 'to', type: 'address' },
    { name: 'deadline', type: 'uint256' }
  ],
  name: 'swapExactTokensForTokens',
  outputs: [{ name: 'amounts', type: 'uint256[]' }],
  stateMutability: 'nonpayable',
  type: 'function'
};

const fees = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/network-fee`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      address: UNISWAP_ROUTER,
      method: 'swapExactTokensForTokens',
      parameters: [
        amountIn,
        amountOutMin,
        [TOKEN_A, TOKEN_B],
        walletAddress,
        deadline
      ],
      abi: [swapAbi]
    })
  }
).then(r => r.json());

console.log('Estimated Fee:', fees.data.networkFee);

步骤 4：执行 swap

const swap = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/write`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      address: UNISWAP_ROUTER,
      method: 'swapExactTokensForTokens',
      parameters: [
        amountIn,
        amountOutMin,
        [TOKEN_A, TOKEN_B],
        walletAddress,
        deadline
      ],
      abi: [swapAbi]
    })
  }
).then(r => r.json());

console.log('Swap TX:', swap.data.hash);

示例 2：使用批量操作的资产兑换

此方法使用 calls 数组将 approve + swap 合并到单次 API 调用中。当您希望将多个操作排队执行以提高效率时，请使用此方法。

批量操作按顺序执行。每个操作作为单独的交易提交，但您只需要一次 API 调用。

批量请求：在一次调用中完成 approve + swap

const approveAbi = {
  inputs: [
    { name: 'spender', type: 'address' },
    { name: 'amount', type: 'uint256' }
  ],
  name: 'approve',
  outputs: [{ name: '', type: 'bool' }],
  stateMutability: 'nonpayable',
  type: 'function'
};

const swapAbi = {
  inputs: [
    { name: 'amountIn', type: 'uint256' },
    { name: 'amountOutMin', type: 'uint256' },
    { name: 'path', type: 'address[]' },
    { name: 'to', type: 'address' },
    { name: 'deadline', type: 'uint256' }
  ],
  name: 'swapExactTokensForTokens',
  outputs: [{ name: 'amounts', type: 'uint256[]' }],
  stateMutability: 'nonpayable',
  type: 'function'
};

const batchSwap = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/contracts/write`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      calls: [
        {
          address: TOKEN_ADDRESS,
          method: 'approve',
          parameters: [UNISWAP_ROUTER, amountIn],
          abi: [approveAbi],
          reference: 'approve-tx',
          metadata: { step: 'approval' }
        },
        {
          address: UNISWAP_ROUTER,
          method: 'swapExactTokensForTokens',
          parameters: [
            amountIn,
            amountOutMin,
            [TOKEN_A, TOKEN_B],
            walletAddress,
            deadline
          ],
          abi: [swapAbi],
          reference: 'swap-tx',
          metadata: { step: 'swap' }
        }
      ]
    })
  }
).then(r => r.json());

console.log('Batch Result:', batchSwap.data);

批量响应

{
  "message": "Batch contract write initiated successfully",
  "statusCode": 200,
  "data": {
    "success": [
      {
        "index": 0,
        "id": "tx-uuid-1",
        "hash": "0xapprove...",
        "status": "PENDING",
        "reference": "approve-tx"
      },
      {
        "index": 1,
        "id": "tx-uuid-2",
        "hash": "0xswap...",
        "status": "PENDING",
        "reference": "swap-tx"
      }
    ],
    "errors": []
  }
}

处理批量中的部分失败

const result = await batchSwap.json();

// Check for successful operations
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Check for failed operations
result.data.errors.forEach(error => {
  console.error(`✗ Operation ${error.index} (${error.method}): ${error.error}`);
});

批量操作规则

规则	值
批量最大大小	20 个操作
执行顺序	顺序
错误处理	部分成功（失败不会阻止后续操作）

何时使用每种方法

场景	推荐方法
需要在步骤之间检查结果	不使用批量
基于先前结果的动态参数	不使用批量
简单的 approve + 操作模式	使用批量
多个独立操作	使用批量
最小化 API 调用	使用批量

Webhook 事件

智能合约操作会触发 webhook 通知：

事件	描述
`custom-smart-contract.success`	合约操作成功完成
`custom-smart-contract.failed`	合约操作失败

Webhook 负载

{
  "event": "custom-smart-contract.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "SUCCESS",
    "method": "approve",
    "contractAddress": "0x...",
    "blockchain": {
      "name": "ethereum",
      "network": "mainnet"
    }
  }
}

最佳实践

安全

验证合约地址：在交互前始终仔细核对合约地址
使用可信的 ABI：从已验证的来源（如区块浏览器）获取 ABI
设置合理的限制：对 DeFi 操作使用滑点保护和金额上限

Gas 管理

执行前估算：始终先调用 network-fee 端点
监控原生币余额：确保有足够的 ETH/BNB/MATIC 用于支付 gas 费用
使用批量操作：通过批量处理相关操作来减少开销

错误处理

实现 webhook 监听器：不要仅依赖 API 响应
处理部分失败：检查批量响应中的 success 和 errors 数组
使用退避重试：为暂时性故障实现指数退避

API 参考

Master Wallet 端点

端点	描述
Read Contract	读取合约状态
Write Contract	执行合约函数
Network Fee	估算 gas 成本
Sign Only	签名但不广播

Child Address 端点

端点	描述
Read Contract	读取合约状态
Write Contract	执行合约函数
Network Fee	估算 gas 成本
Sign Only	签名但不广播

支持

电子邮件：[email protected]
文档：API Reference
博客：How to Interact with Any Smart Contract

Smart Contract API 让您无需管理基础设施复杂性即可构建复杂的区块链集成。从简单的读取操作开始，随着对系统的熟悉逐步引入写入操作。

​先决条件

​支持的区块链

​简介

读取操作

写入操作

费用估算

批量操作

​用例

​Master Wallet vs Child Address

Master Wallet

Child Address

​Master Wallet 端点

​Child Address 端点

​请求结构

​理解 ABI

​读取合约数据

​Master Wallet 读取示例

​Child Address 读取示例

​读取响应

​读取错误响应

​写入合约

​Master Wallet 写入示例

​Child Address 写入示例

​写入响应

​写入错误响应

​估算网络费用

​Master Wallet 费用估算

​Child Address 费用估算

​费用响应

​实践示例：在 Uniswap 上进行资产兑换

​示例 1：不使用批量操作的资产兑换

​步骤 1：检查资产余额

​步骤 2：批准资产花费

​步骤 3：估算 swap 费用

​步骤 4：执行 swap

​示例 2：使用批量操作的资产兑换

​批量请求：在一次调用中完成 approve + swap

​批量响应

​处理批量中的部分失败

​批量操作规则

​何时使用每种方法

​Webhook 事件

​Webhook 负载

​最佳实践

​安全

​Gas 管理

​错误处理

​API 参考

​Master Wallet 端点

​Child Address 端点

​支持

先决条件

支持的区块链

简介

用例

Master Wallet vs Child Address

Master Wallet 端点

Child Address 端点

请求结构

理解 ABI

读取合约数据

Master Wallet 读取示例

Child Address 读取示例

读取响应

读取错误响应

写入合约

Master Wallet 写入示例

Child Address 写入示例

写入响应

写入错误响应

估算网络费用

Master Wallet 费用估算

Child Address 费用估算

费用响应

实践示例：在 Uniswap 上进行资产兑换

示例 1：不使用批量操作的资产兑换

步骤 1：检查资产余额

步骤 2：批准资产花费

步骤 3：估算 swap 费用

步骤 4：执行 swap

示例 2：使用批量操作的资产兑换

批量请求：在一次调用中完成 approve + swap

批量响应

处理批量中的部分失败

批量操作规则

何时使用每种方法

Webhook 事件

Webhook 负载

最佳实践

安全

Gas 管理

错误处理

API 参考

Master Wallet 端点

Child Address 端点

支持