> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yiksipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contratos Inteligentes

> Interactúa con cualquier contrato inteligente directamente desde tu billetera Yiksi Pay

<Note>
  En resumen<br />
  La API de Contratos Inteligentes de Yiksi Pay 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.
</Note>

## Prerrequisitos

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

<Steps>
  <Step title="Clave API">
    Obtén tu clave API desde el [Panel de Yiksi Pay](https://dashboard.yiksipay.com). Navega a **Developers** para generar una.
  </Step>

  <Step title="Billetera Creada">
    Crea una billetera mediante la [API de Crear Billetera](/es/api-reference/wallets/create-wallet) o el panel. Necesitarás el `walletId` para todas las operaciones de contratos inteligentes.
  </Step>

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

## Blockchains Soportadas

La API de Contratos Inteligentes soporta **todas las blockchains compatibles con EVM y Tron** disponibles en Yiksi Pay. Consulta [Integraciones](/es/essentials/integrations) para la lista completa de redes soportadas y enlaces de faucets.

<Warning>
  **Solana no está soportada** para interacciones con contratos inteligentes. La API de Contratos Inteligentes solo funciona con cadenas compatibles con EVM y Tron.
</Warning>

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

## Introducción

La API de Contratos Inteligentes transforma Yiksi Pay 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.

<CardGroup cols={2}>
  <Card title="Operaciones de Lectura" icon="book-open">
    Recupera datos de cualquier contrato inteligente en las blockchains soportadas.
  </Card>

  <Card title="Operaciones de Escritura" icon="pen">
    Ejecuta funciones de contratos inteligentes con gestión completa de transacciones.
  </Card>

  <Card title="Estimación de Tarifas" icon="calculator">
    Calcula costos de gas antes de la ejecución para asegurar fondos suficientes.
  </Card>

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

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

<CardGroup cols={2}>
  <Card title="Billetera Principal" icon="wallet">
    Ejecuta operaciones de contratos directamente desde tu billetera principal. Ideal para operaciones de tesorería y gestión centralizada de fondos.
  </Card>

  <Card title="Dirección Hija" icon="address-card">
    Ejecuta operaciones de contratos desde direcciones hijas individuales. Perfecto para operaciones específicas de usuarios y gestión segregada de fondos.
  </Card>
</CardGroup>

### Endpoints de Billetera Principal

| Operación     | Endpoint                                            | Descripción                                 |
| ------------- | --------------------------------------------------- | ------------------------------------------- |
| Lectura       | `POST /v1/wallets/{walletId}/contracts/read`        | Recupera datos de contratos inteligentes    |
| Escritura     | `POST /v1/wallets/{walletId}/contracts/write`       | Ejecuta funciones de contratos inteligentes |
| Tarifa de Red | `POST /v1/wallets/{walletId}/contracts/network-fee` | Estima costos de gas                        |
| Solo Firmar   | `POST /v1/wallets/{walletId}/contracts/write/sign`  | Firma sin transmitir                        |

### Endpoints de Dirección Hija

| Operación     | Endpoint                                                                  | Descripción                                 |
| ------------- | ------------------------------------------------------------------------- | ------------------------------------------- |
| Lectura       | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/read`        | Recupera datos de contratos inteligentes    |
| Escritura     | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write`       | Ejecuta funciones de contratos inteligentes |
| Tarifa de Red | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee` | Estima costos de gas                        |
| Solo Firmar   | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/sign`  | Firma sin transmitir                        |

## Estructura de la Solicitud

Todas las solicitudes de contratos inteligentes requieren estos parámetros:

| Parámetro    | Tipo   | Requerido | Descripción                                                                  |
| ------------ | ------ | --------- | ---------------------------------------------------------------------------- |
| `address`    | string | Sí        | La dirección blockchain del contrato inteligente                             |
| `method`     | string | Sí        | El nombre de la función a llamar                                             |
| `parameters` | array  | Sí        | Argumentos que coinciden con el orden del ABI de la función                  |
| `abi`        | array  | Sí        | La Interfaz Binaria de Aplicación del contrato                               |
| `reference`  | string | No        | Tu ID de seguimiento interno para la transacción                             |
| `metadata`   | object | No        | Pares clave-valor personalizados para detalles adicionales de la transacción |

<Info>
  Los campos `reference` y `metadata` solo son aplicables para operaciones de escritura. Las operaciones de lectura no admiten estos campos.
</Info>

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

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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.yiksipay.com/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 Dirección Hija

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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.yiksipay.com/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": "Contrato leído exitosamente",
  "statusCode": 200,
  "data": "10052335235393043"
}
```

### Respuestas de Error de Lectura

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

  <Accordion title="Método No Encontrado">
    ```json theme={null}
    {
      "message": "Método 'balanceOf' no encontrado en el ABI",
      "statusCode": 400,
      "error": "ABI_METHOD_NOT_FOUND"
    }
    ```
  </Accordion>

  <Accordion title="Ejecución de Contrato Revertida">
    ```json theme={null}
    {
      "message": "Ejecución del contrato revertida",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: consulta de saldo para dirección cero"
      }
    }
    ```
  </Accordion>

  <Accordion title="Parámetros Inválidos">
    ```json theme={null}
    {
      "message": "Discrepancia en el número de parámetros. Esperado 1, recibido 2",
      "statusCode": 400,
      "error": "INVALID_PARAMETERS"
    }
    ```
  </Accordion>
</AccordionGroup>

## Escritura en Contratos

Ejecuta funciones que cambian el estado en contratos inteligentes.

### Ejemplo de Escritura con Billetera Principal

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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"
      }]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.yiksipay.com/v1/wallets/${walletId}/contracts/write`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': '<api-key>'
      },
      body: JSON.stringify({
        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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Ejemplo de Escritura con Dirección Hija

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/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"
      }]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.yiksipay.com/v1/wallets/${walletId}/addresses/${addressId}/contracts/write`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': '<api-key>'
      },
      body: JSON.stringify({
        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'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Respuesta de Escritura

```json theme={null}
{
  "message": "Escritura de contrato iniciada",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid",
    "hash": "0x...",
    "status": "PENDING"
  }
}
```

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

### Respuestas de Error de Escritura

<AccordionGroup>
  <Accordion title="Gas Insuficiente">
    ```json theme={null}
    {
      "message": "Saldo de token nativo insuficiente para gas",
      "statusCode": 400,
      "error": "INSUFFICIENT_GAS",
      "data": {
        "required": "0.005",
        "available": "0.001",
        "token": "ETH"
      }
    }
    ```
  </Accordion>

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

  <Accordion title="Transacción Revertida">
    ```json theme={null}
    {
      "message": "La transacción sería revertida",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: cantidad de transferencia excede la autorización"
      }
    }
    ```
  </Accordion>

  <Accordion title="ABI Inválido">
    ```json theme={null}
    {
      "message": "Formato de ABI inválido",
      "statusCode": 400,
      "error": "INVALID_ABI",
      "data": {
        "details": "Falta el campo 'inputs' en la definición del ABI"
      }
    }
    ```
  </Accordion>

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

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

```bash theme={null}
curl --request POST \
  --url https://api.yiksipay.com/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

```bash theme={null}
curl --request POST \
  --url https://api.yiksipay.com/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

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

```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.yiksipay.com/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

```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.yiksipay.com/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
```

<Warning>
  Siempre espera el webhook `custom-smart-contract.success` confirmando que la transacción de aprobación fue minada antes de ejecutar el intercambio.
</Warning>

#### Paso 3: Estimar Tarifas del Intercambio

```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.yiksipay.com/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

```javascript theme={null}
const swap = await fetch(
  `https://api.yiksipay.com/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.

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

#### Solicitud por Lote: Aprobar + Intercambiar en Una 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.yiksipay.com/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

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

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

| 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 subsiguientes) |

### Cuándo Usar Cada Enfoque

| Escenario                                             | Enfoque Recomendado |
| ----------------------------------------------------- | ------------------- |
| Necesitas verificar resultados entre pasos            | Sin Lote            |
| Parámetros dinámicos basados en resultados anteriores | Sin Lote            |
| Patrones simples de aprobar + acción                  | Con Lote            |
| Múltiples operaciones independientes                  | Con Lote            |
| Minimizar llamadas de API                             | Con Lote            |

***

## Eventos de Webhook

Las operaciones de contratos inteligentes disparan notificaciones de webhook:

| Evento                          | Descripción                                   |
| ------------------------------- | --------------------------------------------- |
| `custom-smart-contract.success` | Operación de contrato completada exitosamente |
| `custom-smart-contract.failed`  | Operación de contrato falló                   |

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

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

| Endpoint                                                                      | Descripción                    |
| ----------------------------------------------------------------------------- | ------------------------------ |
| [Leer Contrato](/es/api-reference/smart-contract/master-wallet-read)          | Lee el estado del contrato     |
| [Escribir Contrato](/es/api-reference/smart-contract/master-wallet-write)     | Ejecuta funciones del contrato |
| [Tarifa de Red](/es/api-reference/smart-contract/master-wallet-network-fee)   | Estima costos de gas           |
| [Solo Firmar](/es/api-reference/smart-contract/master-wallet-write-sign-only) | Firma sin transmitir           |

### Endpoints de Dirección Hija

| Endpoint                                                                      | Descripción                    |
| ----------------------------------------------------------------------------- | ------------------------------ |
| [Leer Contrato](/es/api-reference/smart-contract/child-address-read)          | Lee el estado del contrato     |
| [Escribir Contrato](/es/api-reference/smart-contract/child-address-write)     | Ejecuta funciones del contrato |
| [Tarifa de Red](/es/api-reference/smart-contract/child-address-network-fee)   | Estima costos de gas           |
| [Solo Firmar](/es/api-reference/smart-contract/child-address-write-sign-only) | Firma sin transmitir           |

## Soporte

* **Email**: [partner@yiksi.com](mailto:partner@yiksi.com)
* **Documentación**: [Referencia de API](/es/api-reference/smart-contract/master-wallet-read)

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