Saltar al contenido principal

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.

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.
Smart Contracts

Requisitos previos

Antes de utilizar la API de Smart Contracts, asegúrese de contar con:
1

Clave de API

Obtenga su clave de API desde el Dashboard de Blockradar. Vaya a Developers para generar una.
2

Billetera creada

Cree una billetera mediante la API Create Wallet o el dashboard. Necesitará el walletId para todas las operaciones de smart contracts.
3

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ónEndpointDescripción
LecturaPOST /v1/wallets/{walletId}/contracts/readRecupera datos de smart contracts
EscrituraPOST /v1/wallets/{walletId}/contracts/writeEjecuta funciones de smart contracts
Network FeePOST /v1/wallets/{walletId}/contracts/network-feeEstima los costos de gas
Sign OnlyPOST /v1/wallets/{walletId}/contracts/write/signFirma sin transmitir

Endpoints de Child Address

OperaciónEndpointDescripción
LecturaPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/readRecupera datos de smart contracts
EscrituraPOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/writeEjecuta funciones de smart contracts
Network FeePOST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-feeEstima los costos de gas
Sign OnlyPOST /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ámetroTipoRequeridoDescripción
addressstringLa dirección del smart contract en la blockchain
methodstringEl nombre de la función a llamar
parametersarrayArgumentos en el orden definido por el ABI de la función
abiarrayLa Application Binary Interface del contrato
referencestringNoSu ID interno de seguimiento para la transacción
metadataobjectNoPares 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"
    }]
  }'

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

Respuesta de lectura

{
  "message": "Contract read successfully",
  "statusCode": 200,
  "data": "10052335235393043"
}

Respuestas de error de lectura

{
  "message": "Invalid contract address",
  "statusCode": 400,
  "error": "BAD_REQUEST"
}
{
  "message": "Method 'balanceOf' not found in ABI",
  "statusCode": 400,
  "error": "ABI_METHOD_NOT_FOUND"
}
{
  "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"
    }]
  }'

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

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

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

Cuándo usar cada enfoque

EscenarioEnfoque recomendado
Necesita verificar resultados entre pasosSin lotes
Parámetros dinámicos basados en resultados anterioresSin lotes
Patrones simples de approve + acciónCon lotes
Múltiples operaciones independientesCon lotes
Minimizar llamadas APICon lotes

Eventos de Webhook

Las operaciones de smart contracts disparan notificaciones webhook:
EventoDescripció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

EndpointDescripción
Read ContractLee el estado del contrato
Write ContractEjecuta funciones del contrato
Network FeeEstima los costos de gas
Sign OnlyFirma sin transmitir

Endpoints de Child Address

EndpointDescripción
Read ContractLee el estado del contrato
Write ContractEjecuta funciones del contrato
Network FeeEstima los costos de gas
Sign OnlyFirma 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.