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:
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/readRecupera dados de smart contracts Escrita POST /v1/wallets/{walletId}/contracts/writeExecuta funções de smart contracts Network Fee POST /v1/wallets/{walletId}/contracts/network-feeEstima os custos de gas Sign Only POST /v1/wallets/{walletId}/contracts/write/signAssina sem transmitir
Endpoints de Child Address
Operação Endpoint Descrição Leitura POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/readRecupera dados de smart contracts Escrita POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/writeExecuta funções de smart contracts Network Fee POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-feeEstima os custos de gas Sign Only POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/signAssina sem transmitir
Estrutura da requisição
Todas as requisições de smart contracts exigem estes parâmetros:
Parâmetro Tipo Obrigatório Descrição addressstring Sim O endereço do smart contract na blockchain methodstring Sim O nome da função a ser chamada parametersarray Sim Argumentos na ordem definida pelo ABI da função abiarray Sim A Application Binary Interface do contrato referencestring Não Seu ID interno de rastreamento da transação metadataobject 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.
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'
}]
})
}
);
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'
}]
})
}
);
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"
}
{
"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"
}
}
{
"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.
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'
}]
})
}
);
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'
}]
})
}
);
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
{
"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"
}
}
{
"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"
}
Estimando taxas de rede
Sempre estime as taxas antes de executar operações de escrita para garantir que sua carteira tenha moeda nativa suficiente.
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"
}]
}'
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 );
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.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"
}
}
}
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
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.