> ## 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

> Interactúe con cualquier smart contract directamente desde su billetera Blockradar

<Note>
  En resumen<br />
  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.
</Note>

<img src="https://mintcdn.com/blockradar/FrE2zfJ4u32QicMn/images/custom-smart-contract.jpg?fit=max&auto=format&n=FrE2zfJ4u32QicMn&q=85&s=0c082e90929d18a8b976aed86785d98a" alt="Smart Contracts" width="2880" height="1620" data-path="images/custom-smart-contract.jpg" />

## Requisitos previos

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

<Steps>
  <Step title="Clave de API">
    Obtenga su clave de API desde el [Dashboard de Blockradar](https://dashboard.blockradar.co). Vaya a **Developers** para generar una.
  </Step>

  <Step title="Billetera creada">
    Cree una billetera mediante la [API Create Wallet](/en/api-reference/wallets/create-wallet) o el dashboard. Necesitará el `walletId` para todas las operaciones de smart contracts.
  </Step>

  <Step title="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](#estimacion-de-tarifas-de-red) para estimar los costos antes de ejecutar.
  </Step>
</Steps>

## Blockchains compatibles

La API de Smart Contracts admite **todas las blockchains compatibles con EVM y Tron** disponibles en Blockradar. Consulte [Integrations](/en/essentials/integrations) para ver la lista completa de redes admitidas y enlaces a faucets.

<Warning>
  **Solana no es compatible** para interacciones con smart contracts. La API de Smart Contracts solo funciona con cadenas compatibles con EVM y Tron.
</Warning>

<Tip>
  Comience con testnets durante el desarrollo para evitar gastar fondos reales.
</Tip>

## 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.

<CardGroup cols={2}>
  <Card title="Operaciones de lectura" icon="book-open">
    Recupere datos de cualquier smart contract en las blockchains compatibles.
  </Card>

  <Card title="Operaciones de escritura" icon="pen">
    Ejecute funciones de smart contracts con gestión completa de transacciones.
  </Card>

  <Card title="Estimación de tarifas" icon="calculator">
    Calcule los costos de gas antes de ejecutar para asegurar fondos suficientes.
  </Card>

  <Card title="Operaciones por lotes" icon="layer-group">
    Ejecute múltiples llamadas a contratos en una sola solicitud API.
  </Card>
</CardGroup>

## 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:

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Ejecute operaciones de contratos directamente desde su master wallet. Ideal para operaciones de tesorería y gestión centralizada de fondos.
  </Card>

  <Card title="Child Address" icon="address-card">
    Ejecute operaciones de contratos desde child addresses individuales. Perfecto para operaciones específicas de usuario y gestión segregada de fondos.
  </Card>
</CardGroup>

### Endpoints de Master Wallet

| Operación   | Endpoint                                            | Descripción                          |
| ----------- | --------------------------------------------------- | ------------------------------------ |
| Lectura     | `POST /v1/wallets/{walletId}/contracts/read`        | Recupera datos de smart contracts    |
| Escritura   | `POST /v1/wallets/{walletId}/contracts/write`       | Ejecuta funciones de smart contracts |
| Network Fee | `POST /v1/wallets/{walletId}/contracts/network-fee` | Estima los costos de gas             |
| Sign Only   | `POST /v1/wallets/{walletId}/contracts/write/sign`  | Firma sin transmitir                 |

### Endpoints de Child Address

| Operación   | Endpoint                                                                  | Descripción                          |
| ----------- | ------------------------------------------------------------------------- | ------------------------------------ |
| Lectura     | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/read`        | Recupera datos de smart contracts    |
| Escritura   | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write`       | Ejecuta funciones de smart contracts |
| Network Fee | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee` | Estima los costos de gas             |
| Sign Only   | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/sign`  | Firma sin transmitir                 |

## Estructura de la solicitud

Todas las solicitudes de smart contracts requieren estos parámetros:

| Parámetro    | Tipo   | Requerido | Descripción                                                                 |
| ------------ | ------ | --------- | --------------------------------------------------------------------------- |
| `address`    | string | Sí        | La dirección del smart contract en la blockchain                            |
| `method`     | string | Sí        | El nombre de la función a llamar                                            |
| `parameters` | array  | Sí        | Argumentos en el orden definido por el ABI de la función                    |
| `abi`        | array  | Sí        | La Application Binary Interface del contrato                                |
| `reference`  | string | No        | Su ID interno de seguimiento para la transacción                            |
| `metadata`   | object | No        | Pares clave-valor personalizados con detalles adicionales de la transacción |

<Info>
  Los campos `reference` y `metadata` solo se aplican a operaciones de escritura. Las operaciones de lectura no admiten estos campos.
</Info>

### 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

<CodeGroup>
  ```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: <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': '<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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Ejemplo de lectura con Child Address

<CodeGroup>
  ```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: <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': '<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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Respuesta de lectura

```json theme={null}
{
  "message": "Contract read successfully",
  "statusCode": 200,
  "data": "10052335235393043"
}
```

### Respuestas de error de lectura

<AccordionGroup>
  <Accordion title="Dirección de contrato inválida">
    ```json theme={null}
    {
      "message": "Invalid contract address",
      "statusCode": 400,
      "error": "BAD_REQUEST"
    }
    ```
  </Accordion>

  <Accordion title="Método no encontrado">
    ```json theme={null}
    {
      "message": "Method 'balanceOf' not found in ABI",
      "statusCode": 400,
      "error": "ABI_METHOD_NOT_FOUND"
    }
    ```
  </Accordion>

  <Accordion title="Ejecución del contrato revertida">
    ```json theme={null}
    {
      "message": "Contract execution reverted",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: balance query for zero address"
      }
    }
    ```
  </Accordion>

  <Accordion title="Parámetros inválidos">
    ```json theme={null}
    {
      "message": "Parameter count mismatch. Expected 1, got 2",
      "statusCode": 400,
      "error": "INVALID_PARAMETERS"
    }
    ```
  </Accordion>
</AccordionGroup>

## Escritura en contratos

Ejecute funciones que modifican el estado de los smart contracts.

### Ejemplo de escritura con Master Wallet

<CodeGroup>
  ```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: <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': '<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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Ejemplo de escritura con Child Address

<CodeGroup>
  ```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: <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': '<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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Respuesta de escritura

```json theme={null}
{
  "message": "Contract write initiated",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "PENDING"
  }
}
```

<Warning>
  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.
</Warning>

### Respuestas de error de escritura

<AccordionGroup>
  <Accordion title="Gas insuficiente">
    ```json theme={null}
    {
      "message": "Insufficient native token balance for gas",
      "statusCode": 400,
      "error": "INSUFFICIENT_GAS",
      "data": {
        "required": "0.005",
        "available": "0.001",
        "token": "ETH"
      }
    }
    ```
  </Accordion>

  <Accordion title="Saldo insuficiente">
    ```json theme={null}
    {
      "message": "Insufficient token balance",
      "statusCode": 400,
      "error": "INSUFFICIENT_BALANCE",
      "data": {
        "required": "1000000000000000000",
        "available": "500000000000000000"
      }
    }
    ```
  </Accordion>

  <Accordion title="Transacción revertida">
    ```json theme={null}
    {
      "message": "Transaction would revert",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: transfer amount exceeds allowance"
      }
    }
    ```
  </Accordion>

  <Accordion title="ABI inválido">
    ```json theme={null}
    {
      "message": "Invalid ABI format",
      "statusCode": 400,
      "error": "INVALID_ABI",
      "data": {
        "details": "Missing 'inputs' field in ABI definition"
      }
    }
    ```
  </Accordion>

  <Accordion title="Billetera no encontrada">
    ```json theme={null}
    {
      "message": "Wallet not found",
      "statusCode": 404,
      "error": "NOT_FOUND"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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

```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: <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

```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: <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

```json theme={null}
{
  "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

```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);
```

#### Paso 2: aprobar el gasto del activo

```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
```

<Warning>
  Espere siempre el webhook `custom-smart-contract.success` que confirme que la transacción de aprobación fue minada antes de ejecutar el swap.
</Warning>

#### Paso 3: estimar las tarifas del 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);
```

#### Paso 4: ejecutar el 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);
```

***

### 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.

<Note>
  Las operaciones por lotes se ejecutan secuencialmente. Cada operación se envía como una transacción independiente, pero solo necesita una llamada API.
</Note>

#### Solicitud por lotes: approve + swap en una sola llamada

```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);
```

#### Respuesta del 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": []
  }
}
```

#### Manejo de fallos parciales en lotes

```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}`);
});
```

### 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.success` | Operación de contrato completada con éxito |
| `custom-smart-contract.failed`  | Operación de contrato fallida              |

### Payload del 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"
    }
  }
}
```

## 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](/en/api-reference/smart-contract/master-wallet-read)        | Lee el estado del contrato     |
| [Write Contract](/en/api-reference/smart-contract/master-wallet-write)      | Ejecuta funciones del contrato |
| [Network Fee](/en/api-reference/smart-contract/master-wallet-network-fee)   | Estima los costos de gas       |
| [Sign Only](/en/api-reference/smart-contract/master-wallet-write-sign-only) | Firma sin transmitir           |

### Endpoints de Child Address

| Endpoint                                                                    | Descripción                    |
| --------------------------------------------------------------------------- | ------------------------------ |
| [Read Contract](/en/api-reference/smart-contract/child-address-read)        | Lee el estado del contrato     |
| [Write Contract](/en/api-reference/smart-contract/child-address-write)      | Ejecuta funciones del contrato |
| [Network Fee](/en/api-reference/smart-contract/child-address-network-fee)   | Estima los costos de gas       |
| [Sign Only](/en/api-reference/smart-contract/child-address-write-sign-only) | Firma sin transmitir           |

## Soporte

* **Correo electrónico**: [support@blockradar.co](mailto:support@blockradar.co)
* **Documentación**: [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)

<Note>
  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.
</Note>
