Saltar para o conteúdo principal
Em resumo
A API de Contratos Inteligentes da Blockradar permite que você interaja com qualquer contrato inteligente diretamente da sua carteira sem precisar gerenciar endpoints RPC, fluxos de assinatura ou implantações de contratos por conta própria.
Contratos Inteligentes

Pré-requisitos

Antes de usar a API de Contratos Inteligentes, certifique-se de ter:
1

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Configurações → Chaves API para gerar uma.
2

Carteira Criada

Crie uma carteira via API Criar Carteira ou pelo painel. Você precisará do walletId para todas as operações de contrato inteligente.
3

Saldo em Token Nativo

Adicione fundos à sua carteira com moeda nativa (ETH, BNB, MATIC, etc.) para cobrir as taxas de gas. Use o endpoint de Taxa de Rede para estimar custos antes de executar.

Blockchains Suportadas

A API de Contratos Inteligentes suporta todas as blockchains compatíveis com EVM e Tron disponíveis na Blockradar. Consulte Integrações para a lista completa de redes suportadas e links de faucets.
Solana não é suportada para interações com contratos inteligentes. A API de Contratos Inteligentes 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 Contratos Inteligentes transforma a Blockradar de uma infraestrutura de carteira em uma camada de execução programável. Você pode ler o estado de contratos, executar funções de contratos, estimar taxas de gas e assinar transações—tudo através de uma superfície de API unificada.

Operações de Leitura

Recupere dados de qualquer contrato inteligente nas blockchains suportadas.

Operações de Escrita

Execute funções de contrato inteligente com gerenciamento completo de transações.

Estimativa de Taxas

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

Operações em Lote

Execute múltiplas chamadas de contrato em uma única requisição de API.

Casos de Uso

A API de Contratos Inteligentes desbloqueia capacidades poderosas para desenvolvedores fintech:
  • Integração DeFi: Conecte-se a protocolos como Uniswap, Aave ou Compound para gerenciamento de rendimento e liquidez
  • Operações de Tesouraria: Automatize o gerenciamento de tesouraria dentro da sua plataforma fintech
  • Ativos Tokenizados: Integre ativos do mundo real nos seus fluxos de produtos
  • 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

Carteira Principal vs Endereço Filho

A API de Contratos Inteligentes está disponível em dois níveis:

Carteira Principal

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

Endereço Filho

Execute operações de contrato a partir de endereços filhos individuais. Perfeito para operações específicas de usuários e gerenciamento segregado de fundos.

Endpoints da Carteira Principal

OperaçãoEndpointDescrição
LeituraPOST /v1/wallets/{walletId}/contracts/readRecuperar dados de contratos inteligentes
EscritaPOST /v1/wallets/{walletId}/contracts/writeExecutar funções de contrato inteligente
Taxa de RedePOST /v1/wallets/{walletId}/contracts/network-feeEstimar custos de gas
Apenas AssinarPOST /v1/wallets/{walletId}/contracts/write/signAssinar sem transmitir

Endpoints do Endereço Filho

OperaçãoEndpointDescrição
LeituraPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/readRecuperar dados de contratos inteligentes
EscritaPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/writeExecutar funções de contrato inteligente
Taxa de RedePOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-feeEstimar custos de gas
Apenas AssinarPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/signAssinar sem transmitir

Estrutura da Requisição

Todas as requisições de contrato inteligente requerem estes parâmetros:
ParâmetroTipoObrigatórioDescrição
addressstringSimO endereço blockchain do contrato inteligente
methodstringSimO nome da função a ser chamada
parametersarraySimArgumentos correspondentes à ordem do ABI da função
abiarraySimA Interface Binária de Aplicação do contrato
referencestringNãoSeu ID de rastreamento interno para a transação
metadataobjectNãoPares chave-valor personalizados para detalhes adicionais da transação
Os campos reference e metadata são aplicáveis apenas para operações de escrita. Operações de leitura não suportam esses campos.

Entendendo ABIs

O ABI (Application Binary Interface) define como interagir com um contrato inteligente. Você pode obter ABIs de:
  • Exploradores de blocos: Etherscan, BscScan, PolygonScan (contratos verificados)
  • Documentação de protocolos: Docs oficiais de protocolos DeFi
  • Código fonte do contrato: Compilar 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 Carteira Principal

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 Endereço Filho

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": "Contrato lido com sucesso",
  "statusCode": 200,
  "data": "10052335235393043"
}

Respostas de Erro de Leitura

{
  "message": "Endereço de contrato inválido",
  "statusCode": 400,
  "error": "BAD_REQUEST"
}
{
  "message": "Método 'balanceOf' não encontrado no ABI",
  "statusCode": 400,
  "error": "ABI_METHOD_NOT_FOUND"
}
{
  "message": "Execução do contrato revertida",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: consulta de saldo para endereço zero"
  }
}
{
  "message": "Incompatibilidade no número de parâmetros. Esperado 1, recebido 2",
  "statusCode": 400,
  "error": "INVALID_PARAMETERS"
}

Escrevendo em Contratos

Execute funções que alteram o estado em contratos inteligentes.

Exemplo de Escrita com Carteira Principal

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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "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 Endereço Filho

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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "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": "Escrita de contrato iniciada",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "PENDING"
  }
}
As operações de escrita são assíncronas. A resposta inicial mostra status PENDING. Escute o webhook custom-smart-contract.success para confirmar a conclusão da transação.

Respostas de Erro de Escrita

{
  "message": "Saldo insuficiente de token nativo para gas",
  "statusCode": 400,
  "error": "INSUFFICIENT_GAS",
  "data": {
    "required": "0.005",
    "available": "0.001",
    "token": "ETH"
  }
}
{
  "message": "Saldo de token insuficiente",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "1000000000000000000",
    "available": "500000000000000000"
  }
}
{
  "message": "A transação seria revertida",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: valor de transferência excede autorização"
  }
}
{
  "message": "Formato de ABI inválido",
  "statusCode": 400,
  "error": "INVALID_ABI",
  "data": {
    "details": "Campo 'inputs' ausente na definição do ABI"
  }
}
{
  "message": "Carteira não encontrada",
  "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 Taxa com Carteira Principal

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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'

Estimativa de Taxa com Endereço Filho

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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "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": "Taxa de rede obtida",
  "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 (única chamada de API).

Exemplo 1: Troca de Ativos SEM Operações em Lote

Esta abordagem faz chamadas de API individuais para cada etapa. Use quando você precisar de controle granular sobre cada transação ou quando as operações dependem dos resultados de chamadas anteriores.

Etapa 1: Verificar Saldo de Ativos

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('Saldo de Ativos:', balance.data);

Etapa 2: Aprovar Gasto de Ativos

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('TX de Aprovação:', approval.data.hash);
// IMPORTANTE: Aguarde a confirmação do webhook antes de prosseguir
Sempre aguarde o webhook custom-smart-contract.success confirmando que a transação de aprovação foi minerada antes de executar a troca.

Etapa 3: Estimar Taxas da Troca

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('Taxa Estimada:', fees.data.networkFee);

Etapa 4: Executar Troca

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('TX de Troca:', swap.data.hash);

Exemplo 2: Troca de Ativos COM Operações em Lote

Esta abordagem combina aprovar + trocar em uma única chamada de API usando o array calls. Use para eficiência quando quiser enfileirar múltiplas operações juntas.
As operações em lote são executadas sequencialmente. Cada operação é enviada como uma transação separada, mas você só precisa de uma chamada de API.

Requisição em Lote: Aprovar + Trocar em Uma 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: 'aprovação' }
        },
        {
          address: UNISWAP_ROUTER,
          method: 'swapExactTokensForTokens',
          parameters: [
            amountIn,
            amountOutMin,
            [TOKEN_A, TOKEN_B],
            walletAddress,
            deadline
          ],
          abi: [swapAbi],
          reference: 'swap-tx',
          metadata: { step: 'troca' }
        }
      ]
    })
  }
).then(r => r.json());

console.log('Resultado do Lote:', batchSwap.data);

Resposta do Lote

{
  "message": "Escrita de contrato em lote iniciada com sucesso",
  "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": []
  }
}

Tratando Falhas Parciais em Lote

const result = await batchSwap.json();

// Verificar operações bem-sucedidas
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Verificar operações com falha
result.data.errors.forEach(error => {
  console.error(`✗ Operação ${error.index} (${error.method}): ${error.error}`);
});

Regras de Operações em Lote

RegraValor
Tamanho máximo do lote20 operações
Ordem de execuçãoSequencial
Tratamento de errosSucesso parcial (falhas não param operações subsequentes)

Quando Usar Cada Abordagem

CenárioAbordagem Recomendada
Precisa verificar resultados entre etapasSem Lote
Parâmetros dinâmicos baseados em resultados anterioresSem Lote
Padrões simples de aprovar + açãoCom Lote
Múltiplas operações independentesCom Lote
Minimizar chamadas de APICom Lote

Eventos de Webhook

Operações de contrato inteligente disparam notificações de webhook:
EventoDescrição
custom-smart-contract.successOperação de contrato concluída com sucesso
custom-smart-contract.failedOperaçã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"
    }
  }
}

Melhores Práticas

Segurança

  • Verifique endereços de contrato: Sempre verifique os endereços de contrato antes de interagir
  • Use ABIs confiáveis: Obtenha ABIs de fontes verificadas como exploradores de blocos
  • Defina limites razoáveis: Use proteção contra slippage e limites de valor para operações DeFi

Gerenciamento de Gas

  • Estime antes de executar: Sempre chame o endpoint de taxa de rede primeiro
  • Monitore o saldo nativo: Garanta ETH/BNB/MATIC suficiente para taxas de gas
  • Use operações em lote: Reduza a sobrecarga agrupando operações relacionadas

Tratamento de Erros

  • Implemente listeners de webhook: Não dependa apenas das respostas da API
  • Trate falhas parciais: Verifique ambos os arrays success e errors nas respostas de lote
  • Tente novamente com backoff: Implemente backoff exponencial para falhas transitórias

Referência da API

Endpoints da Carteira Principal

EndpointDescrição
Ler ContratoLer estado do contrato
Escrever ContratoExecutar funções do contrato
Taxa de RedeEstimar custos de gas
Apenas AssinarAssinar sem transmitir

Endpoints do Endereço Filho

EndpointDescrição
Ler ContratoLer estado do contrato
Escrever ContratoExecutar funções do contrato
Taxa de RedeEstimar custos de gas
Apenas AssinarAssinar sem transmitir

Suporte

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