Smart Contracts - Blockradar

Em resumo
A API de Smart Contracts da Blockradar permite que você interaja com qualquer smart contract diretamente da sua carteira, sem precisar gerenciar endpoints RPC, fluxos de assinatura ou implantações de contratos por conta própria.

Pré-requisitos

Antes de usar a API de Smart Contracts, certifique-se de ter:

Chave de API

Obtenha sua chave de API no Dashboard da Blockradar. Acesse Developers para gerar uma.

Carteira criada

Crie uma carteira via Create Wallet API ou pelo dashboard. Você precisará do walletId para todas as operações de smart contracts.

Saldo em moeda nativa

Abasteça sua carteira com a moeda nativa (ETH, BNB, MATIC, etc.) para cobrir as taxas de gas. Use o endpoint de Network Fee para estimar os custos antes de executar.

Blockchains suportadas

A API de Smart Contracts suporta todas as blockchains compatíveis com EVM e Tron disponíveis na Blockradar. Consulte Integrations para a lista completa de redes suportadas e links de faucets.

Solana não é suportada para interações com smart contracts. A API de Smart Contracts funciona apenas com cadeias compatíveis com EVM e Tron.

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

Introdução

A API de Smart Contracts transforma a Blockradar de uma infraestrutura de carteiras em uma camada de execução programável. Você pode ler o estado do contrato, executar funções de contratos, estimar taxas de gas e assinar transações — tudo por meio de uma superfície API unificada.

Operações de leitura

Recupere dados de qualquer smart contract nas blockchains suportadas.

Operações de escrita

Execute funções de smart contracts com gerenciamento completo de transações.

Estimativa de taxas

Calcule os custos de gas antes da execução para garantir fundos suficientes.

Operações em lote

Execute várias chamadas a contratos em uma única requisição API.

Casos de uso

A API de Smart Contracts desbloqueia recursos poderosos para desenvolvedores fintech:

Integração com DeFi: Conecte-se a protocolos como Uniswap, Aave ou Compound para gerenciamento de rendimento e liquidez
Operações de tesouraria: Automatize a gestão de tesouraria dentro da sua plataforma fintech
Ativos tokenizados: Integre ativos do mundo real aos seus fluxos de produto
Liquidações programáveis: Execute verificações de conformidade e liquidações automatizadas
Ativos personalizados: Gerencie ativos personalizados, sistemas de recompensas e programas de fidelidade

Master Wallet vs Child Address

A API de Smart Contracts está disponível em dois níveis:

Master Wallet

Execute operações de contrato diretamente da sua master wallet. Ideal para operações de tesouraria e gerenciamento centralizado de fundos.

Child Address

Execute operações de contrato a partir de child addresses individuais. Perfeito para operações específicas de usuário e gerenciamento segregado de fundos.

Endpoints de Master Wallet

Operação	Endpoint	Descrição
Leitura	`POST /v1/wallets/{walletId}/contracts/read`	Recupera dados de smart contracts
Escrita	`POST /v1/wallets/{walletId}/contracts/write`	Executa funções de smart contracts
Network Fee	`POST /v1/wallets/{walletId}/contracts/network-fee`	Estima os custos de gas
Sign Only	`POST /v1/wallets/{walletId}/contracts/write/sign`	Assina sem transmitir

Endpoints de Child Address

Operação	Endpoint	Descrição
Leitura	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/read`	Recupera dados de smart contracts
Escrita	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write`	Executa funções de smart contracts
Network Fee	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee`	Estima os custos de gas
Sign Only	`POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/sign`	Assina sem transmitir

Estrutura da requisição

Todas as requisições de smart contracts exigem estes parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string	Sim	O endereço do smart contract na blockchain
`method`	string	Sim	O nome da função a ser chamada
`parameters`	array	Sim	Argumentos na ordem definida pelo ABI da função
`abi`	array	Sim	A Application Binary Interface do contrato
`reference`	string	Não	Seu ID interno de rastreamento da transação
`metadata`	object	Não	Pares chave-valor personalizados com detalhes adicionais da transação

Os campos reference e metadata aplicam-se apenas a operações de escrita. Operações de leitura não suportam esses campos.

Entendendo os ABIs

O ABI (Application Binary Interface) define como interagir com um smart contract. Você pode obter ABIs de:

Block explorers: Etherscan, BscScan, PolygonScan (contratos verificados)
Documentação dos protocolos: Documentação oficial dos protocolos DeFi
Código-fonte do contrato: Compile a partir do código-fonte Solidity

Lendo dados do contrato

Use o endpoint de leitura para consultar o estado do contrato sem modificar a blockchain.

Exemplo de leitura com 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"
    }]
  }'

Exemplo de leitura com 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"
    }]
  }'

Resposta de leitura

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

Respostas de erro de leitura

Endereço de contrato inválido

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

Método não encontrado

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

Execução do contrato revertida

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

Parâmetros inválidos

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

Escrevendo em contratos

Execute funções que alteram o estado de smart contracts.

Exemplo de escrita com 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"
    }]
  }'

Exemplo de escrita com 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"
    }]
  }'

Resposta de escrita

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

As operações de escrita são assíncronas. A resposta inicial mostra o status PENDING. Escute o webhook custom-smart-contract.success para confirmar a conclusão da transação.

Respostas de erro de escrita

Gas insuficiente

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

Saldo insuficiente

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

Transação revertida

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

ABI inválido

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

Carteira não encontrada

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

Estimando taxas de rede

Sempre estime as taxas antes de executar operações de escrita para garantir que sua carteira tenha moeda nativa suficiente.

Estimativa de taxas com 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"
    }]
  }'

Estimativa de taxas com 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"
    }]
  }'

Resposta de taxa

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

Exemplo prático: troca de ativos no Uniswap

Esta seção demonstra duas abordagens para executar uma troca de ativos: sem operações em lote (chamadas sequenciais) e com operações em lote (chamada API única).

Exemplo 1: troca de ativos SEM operações em lote

Esta abordagem faz chamadas API individuais para cada etapa. Use-a quando precisar de controle detalhado sobre cada transação ou quando as operações dependerem dos resultados de chamadas anteriores.

Etapa 1: verificar o saldo do ativo

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

Etapa 2: aprovar o gasto do ativo

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

Sempre aguarde o webhook custom-smart-contract.success confirmando que a transação de aprovação foi minerada antes de executar o swap.

Etapa 3: estimar as taxas do 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);

Etapa 4: executar o 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);

Exemplo 2: troca de ativos COM operações em lote

Esta abordagem combina approve + swap em uma única chamada API usando o array calls. Use-a para maior eficiência quando quiser enfileirar múltiplas operações juntas.

As operações em lote são executadas sequencialmente. Cada operação é submetida como uma transação separada, mas você só precisa de uma chamada API.

Requisição em lote: approve + swap em uma única chamada

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

Resposta do lote

{
  "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": []
  }
}

Tratamento de falhas parciais em lote

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}`);
});

Regras das operações em lote

Regra	Valor
Tamanho máximo do lote	20 operações
Ordem de execução	Sequencial
Tratamento de erros	Sucesso parcial (falhas não interrompem operações subsequentes)

Quando usar cada abordagem

Cenário	Abordagem recomendada
Necessidade de verificar resultados entre etapas	Sem lote
Parâmetros dinâmicos baseados em resultados anteriores	Sem lote
Padrões simples de approve + ação	Com lote
Múltiplas operações independentes	Com lote
Minimizar chamadas API	Com lote

Eventos de Webhook

As operações de smart contracts disparam notificações webhook:

Evento	Descrição
`custom-smart-contract.success`	Operação de contrato concluída com sucesso
`custom-smart-contract.failed`	Operação de contrato falhou

Payload do Webhook

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

Boas práticas

Segurança

Verifique os endereços dos contratos: Sempre confira duas vezes os endereços dos contratos antes de interagir
Use ABIs confiáveis: Obtenha ABIs de fontes verificadas, como block explorers
Defina limites razoáveis: Use proteção contra slippage e tetos de valor para operações DeFi

Gerenciamento de gas

Estime antes de executar: Sempre chame primeiro o endpoint network-fee
Monitore o saldo nativo: Garanta ETH/BNB/MATIC suficientes para as taxas de gas
Use operações em lote: Reduza o overhead agrupando operações relacionadas

Tratamento de erros

Implemente listeners de webhook: Não dependa apenas das respostas da API
Lide com falhas parciais: Verifique tanto os arrays success quanto errors em respostas de lote
Repita com backoff: Implemente backoff exponencial para falhas transitórias

Referência da API

Endpoints de Master Wallet

Endpoint	Descrição
Read Contract	Lê o estado do contrato
Write Contract	Executa funções do contrato
Network Fee	Estima os custos de gas
Sign Only	Assina sem transmitir

Endpoints de Child Address

Endpoint	Descrição
Read Contract	Lê o estado do contrato
Write Contract	Executa funções do contrato
Network Fee	Estima os custos de gas
Sign Only	Assina sem transmitir

Suporte

E-mail: [email protected]
Documentação: API Reference
Blog: How to Interact with Any Smart Contract

A API de Smart Contracts permite criar integrações blockchain sofisticadas sem gerenciar a complexidade da infraestrutura. Comece com operações simples de leitura e incorpore gradualmente operações de escrita à medida que se familiarizar com o sistema.

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Documentation Index

​Pré-requisitos

​Blockchains suportadas

​Introdução

Operações de leitura

Operações de escrita

Estimativa de taxas

Operações em lote

​Casos de uso

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints de Master Wallet

​Endpoints de Child Address

​Estrutura da requisição

​Entendendo os ABIs

​Lendo dados do contrato

​Exemplo de leitura com Master Wallet

​Exemplo de leitura com Child Address

​Resposta de leitura

​Respostas de erro de leitura

​Escrevendo em contratos

​Exemplo de escrita com Master Wallet

​Exemplo de escrita com Child Address

​Resposta de escrita

​Respostas de erro de escrita

​Estimando taxas de rede

​Estimativa de taxas com Master Wallet

​Estimativa de taxas com Child Address

​Resposta de taxa

​Exemplo prático: troca de ativos no Uniswap

​Exemplo 1: troca de ativos SEM operações em lote

​Etapa 1: verificar o saldo do ativo

​Etapa 2: aprovar o gasto do ativo

​Etapa 3: estimar as taxas do swap

​Etapa 4: executar o swap

​Exemplo 2: troca de ativos COM operações em lote

​Requisição em lote: approve + swap em uma única chamada

​Resposta do lote

​Tratamento de falhas parciais em lote

​Regras das operações em lote

​Quando usar cada abordagem

​Eventos de Webhook

​Payload do Webhook

​Boas práticas

​Segurança

​Gerenciamento de gas

​Tratamento de erros

​Referência da API

​Endpoints de Master Wallet

​Endpoints de Child Address

​Suporte

Pré-requisitos

Blockchains suportadas

Introdução

Casos de uso

Master Wallet vs Child Address

Endpoints de Master Wallet

Endpoints de Child Address

Estrutura da requisição

Entendendo os ABIs

Lendo dados do contrato

Exemplo de leitura com Master Wallet

Exemplo de leitura com Child Address

Resposta de leitura

Respostas de erro de leitura

Escrevendo em contratos

Exemplo de escrita com Master Wallet

Exemplo de escrita com Child Address

Resposta de escrita

Respostas de erro de escrita

Estimando taxas de rede

Estimativa de taxas com Master Wallet

Estimativa de taxas com Child Address

Resposta de taxa

Exemplo prático: troca de ativos no Uniswap

Exemplo 1: troca de ativos SEM operações em lote

Etapa 1: verificar o saldo do ativo

Etapa 2: aprovar o gasto do ativo

Etapa 3: estimar as taxas do swap

Etapa 4: executar o swap

Exemplo 2: troca de ativos COM operações em lote

Requisição em lote: approve + swap em uma única chamada

Resposta do lote

Tratamento de falhas parciais em lote

Regras das operações em lote

Quando usar cada abordagem

Eventos de Webhook

Payload do Webhook

Boas práticas

Segurança

Gerenciamento de gas

Tratamento de erros

Referência da API

Endpoints de Master Wallet

Endpoints de Child Address

Suporte