Saltar al contenido principal
En resumen
La API de Contratos Inteligentes de Blockradar te permite interactuar con cualquier contrato inteligente directamente desde tu billetera sin necesidad de gestionar endpoints RPC, flujos de firma o despliegues de contratos por tu cuenta.
Contratos Inteligentes

Prerrequisitos

Antes de usar la API de Contratos Inteligentes, asegúrate de tener:
1

Clave API

Obtén tu clave API desde el Panel de Blockradar. Navega a Configuración → Claves API para generar una.
2

Billetera Creada

Crea una billetera mediante la API de Crear Billetera o el panel. Necesitarás el walletId para todas las operaciones de contratos inteligentes.
3

Saldo de Token Nativo

Financia tu billetera con moneda nativa (ETH, BNB, MATIC, etc.) para cubrir las tarifas de gas. Usa el endpoint de Tarifa de Red para estimar costos antes de ejecutar.

Blockchains Soportadas

La API de Contratos Inteligentes soporta todas las blockchains compatibles con EVM y Tron disponibles en Blockradar. Consulta Integraciones para la lista completa de redes soportadas y enlaces de faucets.
Solana no está soportada para interacciones con contratos inteligentes. La API de Contratos Inteligentes solo funciona con cadenas compatibles con EVM y Tron.
Comienza con testnets durante el desarrollo para evitar gastar fondos reales.

Introducción

La API de Contratos Inteligentes transforma Blockradar de una infraestructura de billeteras en una capa de ejecución programable. Puedes leer el estado de contratos, ejecutar funciones de contratos, estimar tarifas de gas y firmar transacciones—todo a través de una superficie de API unificada.

Operaciones de Lectura

Recupera datos de cualquier contrato inteligente en las blockchains soportadas.

Operaciones de Escritura

Ejecuta funciones de contratos inteligentes con gestión completa de transacciones.

Estimación de Tarifas

Calcula costos de gas antes de la ejecución para asegurar fondos suficientes.

Operaciones por Lote

Ejecuta múltiples llamadas a contratos en una sola solicitud de API.

Casos de Uso

La API de Contratos Inteligentes desbloquea capacidades poderosas para desarrolladores fintech:
  • Integración DeFi: Conecta con protocolos como Uniswap, Aave o Compound para gestión de rendimientos y liquidez
  • Operaciones de Tesorería: Automatiza la gestión de tesorería dentro de tu plataforma fintech
  • Activos Tokenizados: Integra activos del mundo real en tus flujos de productos
  • Liquidaciones Programables: Ejecuta verificaciones de cumplimiento y liquidaciones automatizadas
  • Activos Personalizados: Gestiona activos personalizados, sistemas de recompensas y programas de fidelidad

Billetera Principal vs Dirección Hija

La API de Contratos Inteligentes está disponible en dos niveles:

Billetera Principal

Ejecuta operaciones de contratos directamente desde tu billetera principal. Ideal para operaciones de tesorería y gestión centralizada de fondos.

Dirección Hija

Ejecuta operaciones de contratos desde direcciones hijas individuales. Perfecto para operaciones específicas de usuarios y gestión segregada de fondos.

Endpoints de Billetera Principal

OperaciónEndpointDescripción
LecturaPOST /v1/wallets/{walletId}/contracts/readRecupera datos de contratos inteligentes
EscrituraPOST /v1/wallets/{walletId}/contracts/writeEjecuta funciones de contratos inteligentes
Tarifa de RedPOST /v1/wallets/{walletId}/contracts/network-feeEstima costos de gas
Solo FirmarPOST /v1/wallets/{walletId}/contracts/write/signFirma sin transmitir

Endpoints de Dirección Hija

OperaciónEndpointDescripción
LecturaPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/readRecupera datos de contratos inteligentes
EscrituraPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/writeEjecuta funciones de contratos inteligentes
Tarifa de RedPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-feeEstima costos de gas
Solo FirmarPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/signFirma sin transmitir

Estructura de la Solicitud

Todas las solicitudes de contratos inteligentes requieren estos parámetros:
ParámetroTipoRequeridoDescripción
addressstringLa dirección blockchain del contrato inteligente
methodstringEl nombre de la función a llamar
parametersarrayArgumentos que coinciden con el orden del ABI de la función
abiarrayLa Interfaz Binaria de Aplicación del contrato
referencestringNoTu ID de seguimiento interno para la transacción
metadataobjectNoPares clave-valor personalizados para detalles adicionales de la transacción
Los campos reference y metadata solo son aplicables para operaciones de escritura. Las operaciones de lectura no admiten estos campos.

Entendiendo los ABIs

El ABI (Application Binary Interface) define cómo interactuar con un contrato inteligente. Puedes obtener ABIs de:
  • Exploradores de bloques: Etherscan, BscScan, PolygonScan (contratos verificados)
  • Documentación de protocolos: Documentación oficial de protocolos DeFi
  • Código fuente del contrato: Compilar desde código fuente Solidity

Lectura de Datos del Contrato

Usa el endpoint de lectura para consultar el estado del contrato sin modificar la blockchain.

Ejemplo de Lectura con Billetera 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"
    }]
  }'

Ejemplo de Lectura con Dirección Hija

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"
    }]
  }'

Respuesta de Lectura

{
  "message": "Contrato leído exitosamente",
  "statusCode": 200,
  "data": "10052335235393043"
}

Respuestas de Error de Lectura

{
  "message": "Dirección de contrato inválida",
  "statusCode": 400,
  "error": "BAD_REQUEST"
}
{
  "message": "Método 'balanceOf' no encontrado en el ABI",
  "statusCode": 400,
  "error": "ABI_METHOD_NOT_FOUND"
}
{
  "message": "Ejecución del contrato revertida",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: consulta de saldo para dirección cero"
  }
}
{
  "message": "Discrepancia en el número de parámetros. Esperado 1, recibido 2",
  "statusCode": 400,
  "error": "INVALID_PARAMETERS"
}

Escritura en Contratos

Ejecuta funciones que cambian el estado en contratos inteligentes.

Ejemplo de Escritura con Billetera 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": "0xTU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xTU_DIRECCION_GASTADOR", "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 Dirección Hija

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": "0xTU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xTU_DIRECCION_GASTADOR", "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": "Escritura de contrato iniciada",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "PENDING"
  }
}
Las operaciones de escritura son asíncronas. La respuesta inicial muestra estado PENDING. Escucha el webhook custom-smart-contract.success para confirmar la finalización de la transacción.

Respuestas de Error de Escritura

{
  "message": "Saldo de token nativo insuficiente 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": "La transacción sería revertida",
  "statusCode": 400,
  "error": "EXECUTION_REVERTED",
  "data": {
    "reason": "ERC20: cantidad de transferencia excede la autorización"
  }
}
{
  "message": "Formato de ABI inválido",
  "statusCode": 400,
  "error": "INVALID_ABI",
  "data": {
    "details": "Falta el campo 'inputs' en la definición del ABI"
  }
}
{
  "message": "Billetera no encontrada",
  "statusCode": 404,
  "error": "NOT_FOUND"
}

Estimación de Tarifas de Red

Siempre estima las tarifas antes de ejecutar operaciones de escritura para asegurar que tu billetera tenga suficiente moneda nativa.

Estimación de Tarifas con Billetera 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": "0xTU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xTU_DIRECCION_GASTADOR", "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 Dirección Hija

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": "0xTU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xTU_DIRECCION_GASTADOR", "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": "Tarifa de red obtenida",
  "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 lote (llamadas secuenciales) y con operaciones por lote (una sola llamada de API).

Ejemplo 1: Intercambio de Activos SIN Operaciones por Lote

Este enfoque hace llamadas de API individuales para cada paso. Úsalo cuando necesites control detallado sobre cada transacción o cuando las operaciones dependan de los resultados de llamadas anteriores.

Paso 1: Verificar Saldo de Activos

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 Activos:', balance.data);

Paso 2: Aprobar Gasto de Activos

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 Aprobación:', approval.data.hash);
// IMPORTANTE: Espera la confirmación del webhook antes de continuar
Siempre espera el webhook custom-smart-contract.success confirmando que la transacción de aprobación fue minada antes de ejecutar el intercambio.

Paso 3: Estimar Tarifas del Intercambio

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

Paso 4: Ejecutar Intercambio

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 Intercambio:', swap.data.hash);

Ejemplo 2: Intercambio de Activos CON Operaciones por Lote

Este enfoque combina aprobar + intercambiar en una sola llamada de API usando el array calls. Úsalo para eficiencia cuando quieras agrupar múltiples operaciones juntas.
Las operaciones por lote se ejecutan secuencialmente. Cada operación se envía como una transacción separada, pero solo necesitas una llamada de API.

Solicitud por Lote: Aprobar + Intercambiar en Una 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: 'aprobación' }
        },
        {
          address: UNISWAP_ROUTER,
          method: 'swapExactTokensForTokens',
          parameters: [
            amountIn,
            amountOutMin,
            [TOKEN_A, TOKEN_B],
            walletAddress,
            deadline
          ],
          abi: [swapAbi],
          reference: 'swap-tx',
          metadata: { step: 'intercambio' }
        }
      ]
    })
  }
).then(r => r.json());

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

Respuesta del Lote

{
  "message": "Escritura de contrato por lote iniciada exitosamente",
  "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();

// Verificar operaciones exitosas
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Verificar operaciones fallidas
result.data.errors.forEach(error => {
  console.error(`✗ Operación ${error.index} (${error.method}): ${error.error}`);
});

Reglas de Operaciones por Lote

ReglaValor
Tamaño máximo del lote20 operaciones
Orden de ejecuciónSecuencial
Manejo de erroresÉxito parcial (los fallos no detienen las operaciones subsiguientes)

Cuándo Usar Cada Enfoque

EscenarioEnfoque Recomendado
Necesitas verificar resultados entre pasosSin Lote
Parámetros dinámicos basados en resultados anterioresSin Lote
Patrones simples de aprobar + acciónCon Lote
Múltiples operaciones independientesCon Lote
Minimizar llamadas de APICon Lote

Eventos de Webhook

Las operaciones de contratos inteligentes disparan notificaciones de webhook:
EventoDescripción
custom-smart-contract.successOperación de contrato completada exitosamente
custom-smart-contract.failedOperación de contrato falló

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

  • Verifica direcciones de contratos: Siempre verifica las direcciones de contratos antes de interactuar
  • Usa ABIs confiables: Obtén ABIs de fuentes verificadas como exploradores de bloques
  • Establece límites razonables: Usa protección contra deslizamiento y límites de cantidad para operaciones DeFi

Gestión de Gas

  • Estima antes de ejecutar: Siempre llama al endpoint de tarifa de red primero
  • Monitorea el saldo nativo: Asegura suficiente ETH/BNB/MATIC para tarifas de gas
  • Usa operaciones por lote: Reduce la sobrecarga agrupando operaciones relacionadas

Manejo de Errores

  • Implementa escuchadores de webhooks: No dependas únicamente de las respuestas de la API
  • Maneja fallos parciales: Verifica ambos arrays success y errors en respuestas de lotes
  • Reintenta con retroceso: Implementa retroceso exponencial para fallos transitorios

Referencia de API

Endpoints de Billetera Principal

EndpointDescripción
Leer ContratoLee el estado del contrato
Escribir ContratoEjecuta funciones del contrato
Tarifa de RedEstima costos de gas
Solo FirmarFirma sin transmitir

Endpoints de Dirección Hija

EndpointDescripción
Leer ContratoLee el estado del contrato
Escribir ContratoEjecuta funciones del contrato
Tarifa de RedEstima costos de gas
Solo FirmarFirma sin transmitir

Soporte

La API de Contratos Inteligentes te permite construir integraciones blockchain sofisticadas sin gestionar la complejidad de la infraestructura. Comienza con operaciones de lectura simples e incorpora gradualmente operaciones de escritura a medida que te familiarices con el sistema.