> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # Smart Contracts > Interaja com qualquer smart contract diretamente da sua carteira 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. Smart Contracts ## Pré-requisitos Antes de usar a API de Smart Contracts, certifique-se de ter: Obtenha sua chave de API no [Dashboard da Blockradar](https://dashboard.blockradar.co). Acesse **Developers** para gerar uma. Crie uma carteira via [Create Wallet API](/en/api-reference/wallets/create-wallet) ou pelo dashboard. Você precisará do `walletId` para todas as operações de smart contracts. Abasteça sua carteira com a moeda nativa (ETH, BNB, MATIC, etc.) para cobrir as taxas de gas. Use o [endpoint de Network Fee](#estimando-taxas-de-rede) 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](/en/essentials/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. Recupere dados de qualquer smart contract nas blockchains suportadas. Execute funções de smart contracts com gerenciamento completo de transações. Calcule os custos de gas antes da execução para garantir fundos suficientes. 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: Execute operações de contrato diretamente da sua master wallet. Ideal para operações de tesouraria e gerenciamento centralizado de fundos. 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 ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/read \ --header 'Content-Type: application/json' \ --header 'x-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" }] }' ``` ```javascript JavaScript theme={null} const response = await fetch( `https://api.blockradar.co/v1/wallets/${walletId}/contracts/read`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-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' }] }) } ); ``` ### Exemplo de leitura com Child Address ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/contracts/read \ --header 'Content-Type: application/json' \ --header 'x-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" }] }' ``` ```javascript JavaScript theme={null} 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': '' }, 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 ```json theme={null} { "message": "Contract read successfully", "statusCode": 200, "data": "10052335235393043" } ``` ### Respostas de erro de leitura ```json theme={null} { "message": "Invalid contract address", "statusCode": 400, "error": "BAD_REQUEST" } ``` ```json theme={null} { "message": "Method 'balanceOf' not found in ABI", "statusCode": 400, "error": "ABI_METHOD_NOT_FOUND" } ``` ```json theme={null} { "message": "Contract execution reverted", "statusCode": 400, "error": "EXECUTION_REVERTED", "data": { "reason": "ERC20: balance query for zero address" } } ``` ```json theme={null} { "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 ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/write \ --header 'Content-Type: application/json' \ --header 'x-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" }] }' ``` ```javascript JavaScript theme={null} const response = await fetch( `https://api.blockradar.co/v1/wallets/${walletId}/contracts/write`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-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' }] }) } ); ``` ### Exemplo de escrita com Child Address ```bash Curl theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/contracts/write \ --header 'Content-Type: application/json' \ --header 'x-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" }] }' ``` ```javascript JavaScript theme={null} 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': '' }, 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 ```json theme={null} { "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 ```json theme={null} { "message": "Insufficient native token balance for gas", "statusCode": 400, "error": "INSUFFICIENT_GAS", "data": { "required": "0.005", "available": "0.001", "token": "ETH" } } ``` ```json theme={null} { "message": "Insufficient token balance", "statusCode": 400, "error": "INSUFFICIENT_BALANCE", "data": { "required": "1000000000000000000", "available": "500000000000000000" } } ``` ```json theme={null} { "message": "Transaction would revert", "statusCode": 400, "error": "EXECUTION_REVERTED", "data": { "reason": "ERC20: transfer amount exceeds allowance" } } ``` ```json theme={null} { "message": "Invalid ABI format", "statusCode": 400, "error": "INVALID_ABI", "data": { "details": "Missing 'inputs' field in ABI definition" } } ``` ```json theme={null} { "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 ```bash theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/contracts/network-fee \ --header 'Content-Type: application/json' \ --header 'x-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 ```bash theme={null} 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: ' \ --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 ```json theme={null} { "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 ```javascript theme={null} 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 ```javascript theme={null} 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 ```javascript theme={null} 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 ```javascript theme={null} 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 ```javascript theme={null} 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 ```json theme={null} { "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 ```javascript theme={null} 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 ```json theme={null} { "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](/en/api-reference/smart-contract/master-wallet-read) | Lê o estado do contrato | | [Write Contract](/en/api-reference/smart-contract/master-wallet-write) | Executa funções do contrato | | [Network Fee](/en/api-reference/smart-contract/master-wallet-network-fee) | Estima os custos de gas | | [Sign Only](/en/api-reference/smart-contract/master-wallet-write-sign-only) | Assina sem transmitir | ### Endpoints de Child Address | Endpoint | Descrição | | --------------------------------------------------------------------------- | --------------------------- | | [Read Contract](/en/api-reference/smart-contract/child-address-read) | Lê o estado do contrato | | [Write Contract](/en/api-reference/smart-contract/child-address-write) | Executa funções do contrato | | [Network Fee](/en/api-reference/smart-contract/child-address-network-fee) | Estima os custos de gas | | [Sign Only](/en/api-reference/smart-contract/child-address-write-sign-only) | Assina sem transmitir | ## Suporte * **E-mail**: [support@blockradar.co](mailto:support@blockradar.co) * **Documentação**: [API Reference](/en/api-reference/smart-contract/master-wallet-read) * **Blog**: [How to Interact with Any Smart Contract](https://www.blockradar.co/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.