En resumen
La API de Smart Contracts de Blockradar le permite interactuar con cualquier smart contract directamente desde su billetera, sin necesidad de gestionar endpoints RPC, flujos de firma o despliegues de contratos por su cuenta.
Requisitos previos
Antes de utilizar la API de Smart Contracts, asegúrese de contar con:
Billetera creada
Cree una billetera mediante la API Create Wallet o el dashboard. Necesitará el walletId para todas las operaciones de smart contracts.
Saldo en moneda nativa
Financie su billetera con la moneda nativa (ETH, BNB, MATIC, etc.) para cubrir las tarifas de gas. Utilice el endpoint de Network Fee para estimar los costos antes de ejecutar.
Blockchains compatibles
La API de Smart Contracts admite todas las blockchains compatibles con EVM y Tron disponibles en Blockradar. Consulte Integrations para ver la lista completa de redes admitidas y enlaces a faucets.
Solana no es compatible para interacciones con smart contracts. La API de Smart Contracts solo funciona con cadenas compatibles con EVM y Tron.
Comience con testnets durante el desarrollo para evitar gastar fondos reales.
Introducción
La API de Smart Contracts transforma a Blockradar de una infraestructura de billeteras a una capa de ejecución programable. Puede leer el estado de un contrato, ejecutar funciones de contratos, estimar tarifas de gas y firmar transacciones, todo a través de una superficie API unificada.
Operaciones de lectura Recupere datos de cualquier smart contract en las blockchains compatibles.
Operaciones de escritura Ejecute funciones de smart contracts con gestión completa de transacciones.
Estimación de tarifas Calcule los costos de gas antes de ejecutar para asegurar fondos suficientes.
Operaciones por lotes Ejecute múltiples llamadas a contratos en una sola solicitud API.
Casos de uso
La API de Smart Contracts habilita capacidades poderosas para los desarrolladores fintech:
Integración con DeFi : Conéctese a protocolos como Uniswap, Aave o Compound para gestión de rendimiento y liquidez
Operaciones de tesorería : Automatice la gestión de tesorería dentro de su plataforma fintech
Activos tokenizados : Integre activos del mundo real en sus flujos de producto
Liquidaciones programables : Ejecute verificaciones de cumplimiento y liquidaciones automatizadas
Activos personalizados : Gestione activos personalizados, sistemas de recompensas y programas de lealtad
Master Wallet vs Child Address
La API de Smart Contracts está disponible en dos niveles:
Master Wallet Ejecute operaciones de contratos directamente desde su master wallet. Ideal para operaciones de tesorería y gestión centralizada de fondos.
Child Address Ejecute operaciones de contratos desde child addresses individuales. Perfecto para operaciones específicas de usuario y gestión segregada de fondos.
Endpoints de Master Wallet
Operación Endpoint Descripción Lectura POST /v1/wallets/{walletId}/contracts/readRecupera datos de smart contracts Escritura POST /v1/wallets/{walletId}/contracts/writeEjecuta funciones de smart contracts Network Fee POST /v1/wallets/{walletId}/contracts/network-feeEstima los costos de gas Sign Only POST /v1/wallets/{walletId}/contracts/write/signFirma sin transmitir
Endpoints de Child Address
Operación Endpoint Descripción Lectura POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/readRecupera datos de smart contracts Escritura POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/writeEjecuta funciones de smart contracts Network Fee POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-feeEstima los costos de gas Sign Only POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/signFirma sin transmitir
Estructura de la solicitud
Todas las solicitudes de smart contracts requieren estos parámetros:
Parámetro Tipo Requerido Descripción addressstring Sí La dirección del smart contract en la blockchain methodstring Sí El nombre de la función a llamar parametersarray Sí Argumentos en el orden definido por el ABI de la función abiarray Sí La Application Binary Interface del contrato referencestring No Su ID interno de seguimiento para la transacción metadataobject No Pares clave-valor personalizados con detalles adicionales de la transacción
Los campos reference y metadata solo se aplican a operaciones de escritura. Las operaciones de lectura no admiten estos campos.
Comprensión de los ABIs
El ABI (Application Binary Interface) define cómo interactuar con un smart contract. Puede obtener ABIs desde:
Exploradores de bloques : Etherscan, BscScan, PolygonScan (contratos verificados)
Documentación de protocolos : Documentación oficial de los protocolos DeFi
Código fuente del contrato : Compile a partir del código fuente Solidity
Lectura de datos del contrato
Utilice el endpoint de lectura para consultar el estado del contrato sin modificar la blockchain.
Ejemplo de lectura con 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"
}]
}'
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'
}]
})
}
);
Ejemplo de lectura con 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"
}]
}'
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'
}]
})
}
);
Respuesta de lectura
{
"message" : "Contract read successfully" ,
"statusCode" : 200 ,
"data" : "10052335235393043"
}
Respuestas de error de lectura
Dirección de contrato inválida
{
"message" : "Invalid contract address" ,
"statusCode" : 400 ,
"error" : "BAD_REQUEST"
}
{
"message" : "Method 'balanceOf' not found in ABI" ,
"statusCode" : 400 ,
"error" : "ABI_METHOD_NOT_FOUND"
}
Ejecución del 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"
}
Escritura en contratos
Ejecute funciones que modifican el estado de los smart contracts.
Ejemplo de escritura con 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"
}]
}'
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'
}]
})
}
);
Ejemplo de escritura con 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"
}]
}'
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'
}]
})
}
);
Respuesta de escritura
{
"message" : "Contract write initiated" ,
"statusCode" : 200 ,
"data" : {
"id" : "tx-uuid" ,
"hash" : "0x..." ,
"status" : "PENDING"
}
}
Las operaciones de escritura son asíncronas. La respuesta inicial muestra el estado PENDING. Escuche el webhook custom-smart-contract.success para confirmar la finalización de la transacción.
Respuestas de error de escritura
{
"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"
}
Estimación de tarifas de red
Estime siempre las tarifas antes de ejecutar operaciones de escritura para asegurar que su billetera disponga de suficiente moneda nativa.
Estimación de tarifas con 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"
}]
}'
Estimación de tarifas con 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"
}]
}'
Respuesta de tarifas
{
"message" : "Network fee retrieved" ,
"statusCode" : 200 ,
"data" : {
"networkFee" : "0.00001247904" ,
"networkFeeInUSD" : "0.01" ,
"nativeBalance" : "0.5" ,
"nativeBalanceInUSD" : "450.00" ,
"estimatedArrivalTime" : 30
}
}
Ejemplo práctico: intercambio de activos en Uniswap
Esta sección demuestra dos enfoques para ejecutar un intercambio de activos: sin operaciones por lotes (llamadas secuenciales) y con operaciones por lotes (una sola llamada API).
Ejemplo 1: intercambio de activos SIN operaciones por lotes
Este enfoque realiza llamadas API individuales para cada paso. Úselo cuando necesite control detallado sobre cada transacción o cuando las operaciones dependan de los resultados de llamadas anteriores.
Paso 1: verificar el saldo del activo
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 );
Paso 2: aprobar el gasto del activo
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
Espere siempre el webhook custom-smart-contract.success que confirme que la transacción de aprobación fue minada antes de ejecutar el swap.
Paso 3: estimar las tarifas del 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 );
Paso 4: ejecutar el 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 );
Ejemplo 2: intercambio de activos CON operaciones por lotes
Este enfoque combina approve + swap en una sola llamada API utilizando el array calls. Úselo para mayor eficiencia cuando desee encolar múltiples operaciones juntas.
Las operaciones por lotes se ejecutan secuencialmente. Cada operación se envía como una transacción independiente, pero solo necesita una llamada API.
Solicitud por lotes: approve + swap en una sola llamada
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 );
Respuesta del 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" : []
}
}
Manejo de fallos parciales en lotes
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 } ` );
});
Reglas de operaciones por lotes
Regla Valor Tamaño máximo del lote 20 operaciones Orden de ejecución Secuencial Manejo de errores Éxito parcial (los fallos no detienen las operaciones siguientes)
Cuándo usar cada enfoque
Escenario Enfoque recomendado Necesita verificar resultados entre pasos Sin lotes Parámetros dinámicos basados en resultados anteriores Sin lotes Patrones simples de approve + acción Con lotes Múltiples operaciones independientes Con lotes Minimizar llamadas API Con lotes
Eventos de Webhook
Las operaciones de smart contracts disparan notificaciones webhook:
Evento Descripción custom-smart-contract.successOperación de contrato completada con éxito custom-smart-contract.failedOperación de contrato fallida
Payload del Webhook
{
"event" : "custom-smart-contract.success" ,
"data" : {
"id" : "tx-uuid" ,
"hash" : "0x..." ,
"status" : "SUCCESS" ,
"method" : "approve" ,
"contractAddress" : "0x..." ,
"blockchain" : {
"name" : "ethereum" ,
"network" : "mainnet"
}
}
}
Mejores prácticas
Seguridad
Verifique las direcciones de los contratos : Verifique siempre dos veces las direcciones de los contratos antes de interactuar
Use ABIs confiables : Obtenga los ABIs de fuentes verificadas como exploradores de bloques
Establezca límites razonables : Use protección de slippage y topes de monto para operaciones DeFi
Gestión de gas
Estime antes de ejecutar : Llame siempre primero al endpoint network-fee
Monitoree el saldo nativo : Asegúrese de tener suficiente ETH/BNB/MATIC para las tarifas de gas
Use operaciones por lotes : Reduzca la sobrecarga agrupando operaciones relacionadas
Manejo de errores
Implemente listeners de webhook : No dependa solo de las respuestas de la API
Maneje fallos parciales : Verifique tanto los arrays success como errors en respuestas por lotes
Reintente con backoff : Implemente backoff exponencial para fallos transitorios
Referencia API
Endpoints de Master Wallet
Endpoint Descripción Read Contract Lee el estado del contrato Write Contract Ejecuta funciones del contrato Network Fee Estima los costos de gas Sign Only Firma sin transmitir
Endpoints de Child Address
Endpoint Descripción Read Contract Lee el estado del contrato Write Contract Ejecuta funciones del contrato Network Fee Estima los costos de gas Sign Only Firma sin transmitir
Soporte
La API de Smart Contracts le permite construir integraciones blockchain sofisticadas sin gestionar la complejidad de la infraestructura. Comience con operaciones simples de lectura e incorpore progresivamente operaciones de escritura a medida que se familiarice con el sistema.