与任意智能合约交互

Blockradar 的核心 API 覆盖了最常见的金融科技流程：稳定币存款、付款、兑换与结算。但如果您需要突破原生支持的范围呢？如果您需要与某个 DeFi 协议、自有代币合约，或业务专属的链上服务交互呢？这正是智能合约 API 的用武之地。它让您可以直接通过 Blockradar 钱包与任意智能合约交互，而无需自行管理 RPC 端点、签名流程或节点基础设施。借助它，您可以：

连接 DeFi 协议，进行收益或流动性管理
自动执行稳定币借贷、质押或资金管理操作
将**代币化的现实世界资产（RWA）**接入您的产品流程
使用链上逻辑驱动可编程的结算、付款或合规检查
通过自定义代币、奖励体系或费用规则扩展您的平台

智能合约 API 提供三项能力：读取合约状态、写入合约，以及在执行前估算 gas。

前提条件

API 密钥

在 Blockradar 控制台获取您的 API 密钥。进入 Developers 即可生成。

已创建钱包

所有智能合约操作都需要 walletId。

合约 ABI

您需要所调用合约函数的 ABI（应用二进制接口）。对于已验证的合约，可在 Etherscan 等区块浏览器上公开获取。

合约地址

您要交互的智能合约的链上地址。

工作原理

本指南将带您完成一个真实示例：使用 Uniswap V2 把不受支持的代币兑换成 USDT。同样的模式适用于任何智能合约交互。流程如下：

读取合约中的代币余额
授权 Uniswap 使用该代币
估算兑换的网络费用
执行兑换
通过 webhook 确认

第 1 步：了解合约

我们将使用 Uniswap V2 路由合约的 swapExactTokensForTokens 方法。 方法签名：

function swapExactTokensForTokens(
  uint amountIn,
  uint amountOutMin,
  address[] calldata path,
  address to,
  uint deadline
) external returns (uint[] memory amounts);

参数	说明
`amountIn`	您要卖出的代币数量
`amountOutMin`	您可接受的最少输出代币数量（滑点保护）
`path`	构成兑换路径的代币地址
`to`	您的 Blockradar 钱包地址（接收输出代币）
`deadline`	交易过期的 Unix 时间戳

第 2 步：读取代币余额

兑换之前，请使用 contracts/read 查询钱包中该代币的数量。

const res = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/contracts/read',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<api-key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      abi: [{
        "constant": true,
        "inputs": [{ "name": "_owner", "type": "address" }],
        "name": "balanceOf",
        "outputs": [{ "name": "balance", "type": "uint256" }],
        "stateMutability": "view",
        "type": "function"
      }],
      address: "0xUnsupportedTokenAddress",
      method: "balanceOf",
      parameters: ["0xYourWalletAddress"]
    })
  }
).then(r => r.json());

// Response:
// { "data": "1000000000000000000", "message": "Contract read successfully" }

参数	说明
`abi`	您所调用合约函数的 ABI
`address`	代币的智能合约地址
`method`	要调用的函数名称
`parameters`	函数的参数

请将这里返回的余额用作兑换调用中的 amountIn 值。

第 3 步：授权合约使用您的代币

在 Uniswap 能够转移您的代币之前，您需要通过代币合约的 approve 函数授予权限。

await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/contracts/write',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<api-key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      abi: [{
        "inputs": [
          { "name": "_spender", "type": "address" },
          { "name": "_value", "type": "uint256" }
        ],
        "name": "approve",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function"
      }],
      address: "0xUnsupportedTokenAddress",
      method: "approve",
      parameters: ["0xUniswapRouterAddress", "1000000000000000000"]
    })
  }
);

提交授权后请勿立即执行兑换。请先等待 custom-smart-contract.success webhook 确认授权交易已被打包，再进入下一步。

授权 webhook 负载：

{
  "event": "custom-smart-contract.success",
  "data": {
    "status": "SUCCESS",
    "type": "CUSTOM_SMART_CONTRACT",
    "hash": "0xfedcba098765...",
    "tokenAddress": "0xUnsupportedTokenAddress"
  }
}

第 4 步：估算网络费用

执行兑换之前，请估算 gas 成本，确认钱包中有足够的原生代币来支付。

const fee = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/contracts/network-fee',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<api-key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      abi: [ /* ABI of swapExactTokensForTokens */ ],
      address: "0xUniswapRouterAddress",
      method: "swapExactTokensForTokens",
      parameters: [
        "1000000000000000000",
        "990000",
        ["0xUnsupportedTokenAddress", "0xUSDTAddress"],
        "0xYourWalletAddress",
        Math.floor(Date.now() / 1000) + 60 * 20
      ]
    })
  }
).then(r => r.json());

// Response:
// { "data": { "balance": "1.0123", "fee": "0.00422" } }

第 5 步：执行兑换

授权确认并核对费用后，即可执行兑换。

const swap = await fetch(
  'https://api.blockradar.co/v1/wallets/{walletId}/contracts/write',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<api-key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      abi: [ /* ABI of swapExactTokensForTokens */ ],
      address: "0xUniswapRouterAddress",
      method: "swapExactTokensForTokens",
      parameters: [
        "1000000000000000000",
        "990000",
        ["0xUnsupportedTokenAddress", "0xUSDTAddress"],
        "0xYourWalletAddress",
        Math.floor(Date.now() / 1000) + 60 * 20
      ]
    })
  }
).then(r => r.json());

// Response:
// { "message": "Contract write initiated successfully", "data": { "status": "PENDING" } }

监听 webhook 以确认完成：

{
  "event": "custom-smart-contract.success",
  "data": {
    "status": "SUCCESS",
    "type": "CUSTOM_SMART_CONTRACT",
    "hash": "0xfedcba098765...",
    "tokenAddress": "0xUniswapRouterAddress"
  }
}

Webhook 事件

事件	说明
`custom-smart-contract.success`	合约写入已在链上确认
`custom-smart-contract.failed`	合约写入失败

其他端点

端点	说明
`POST /v1/wallets/{walletId}/contracts/read`	读取任意合约的状态
`POST /v1/wallets/{walletId}/contracts/write`	执行任意合约函数
`POST /v1/wallets/{walletId}/contracts/network-fee`	在执行前估算 gas
`POST /v1/wallets/{walletId}/contracts/write/sign`	仅签名交易而不广播

安全说明

所有交易都通过 Blockradar 的基础设施签名并广播——您无需管理私钥或 RPC 节点
在条件允许的情况下会应用原生的 AML 与合规检查
每次合约交互都是真实的链上交易，需要使用该链的原生代币支付 gas

API 参考

端点	说明
Master Wallet Read	通过主钱包读取合约状态
Master Wallet Write	通过主钱包执行合约函数
Master Wallet Network Fee	通过主钱包估算 gas
Child Address Read	通过子地址读取合约状态
Child Address Write	通过子地址执行合约函数
Child Address Network Fee	通过子地址估算 gas

开始使用

钱包

收款

付款

转换与管理

合规与工具

与任意智能合约交互

前提条件

工作原理

第 1 步：了解合约

第 2 步：读取代币余额

第 3 步：授权合约使用您的代币

第 4 步：估算网络费用

第 5 步：执行兑换

Webhook 事件

其他端点

安全说明

API 参考

​前提条件

​工作原理

​第 1 步：了解合约

​第 2 步：读取代币余额

​第 3 步：授权合约使用您的代币

​第 4 步：估算网络费用

​第 5 步：执行兑换

​Webhook 事件

​其他端点

​安全说明

​API 参考

前提条件

工作原理

第 1 步：了解合约

第 2 步：读取代币余额

第 3 步：授权合约使用您的代币

第 4 步：估算网络费用

第 5 步：执行兑换

Webhook 事件

其他端点

安全说明

API 参考