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

> Interaja com qualquer contrato inteligente diretamente da sua carteira Yiksi Pay

<Note>
  Em resumo<br />
  A API de Contratos Inteligentes da Yiksi Pay permite que você interaja com qualquer contrato inteligente diretamente da sua carteira sem precisar gerenciar endpoints RPC, fluxos de assinatura ou implantações de contratos por conta própria.
</Note>

## Pré-requisitos

Antes de usar a API de Contratos Inteligentes, certifique-se de ter:

<Steps>
  <Step title="Chave API">
    Obtenha sua chave API no [Painel da Yiksi Pay](https://dashboard.yiksipay.com). Navegue até **Configurações → Chaves API** para gerar uma.
  </Step>

  <Step title="Carteira Criada">
    Crie uma carteira via [API Criar Carteira](/pt/api-reference/wallets/create-wallet) ou pelo painel. Você precisará do `walletId` para todas as operações de contrato inteligente.
  </Step>

  <Step title="Saldo em Token Nativo">
    Adicione fundos à sua carteira com moeda nativa (ETH, BNB, MATIC, etc.) para cobrir as taxas de gas. Use o [endpoint de Taxa de Rede](#estimando-taxas-de-rede) para estimar custos antes de executar.
  </Step>
</Steps>

## Blockchains Suportadas

A API de Contratos Inteligentes suporta **todas as blockchains compatíveis com EVM e Tron** disponíveis na Yiksi Pay. Consulte [Integrações](/pt/essentials/integrations) para a lista completa de redes suportadas e links de faucets.

<Warning>
  **Solana não é suportada** para interações com contratos inteligentes. A API de Contratos Inteligentes funciona apenas com cadeias compatíveis com EVM e Tron.
</Warning>

<Tip>
  Comece com testnets durante o desenvolvimento para evitar gastar fundos reais.
</Tip>

## Introdução

A API de Contratos Inteligentes transforma a Yiksi Pay de uma infraestrutura de carteira em uma camada de execução programável. Você pode ler o estado de contratos, executar funções de contratos, estimar taxas de gas e assinar transações—tudo através de uma superfície de API unificada.

<CardGroup cols={2}>
  <Card title="Operações de Leitura" icon="book-open">
    Recupere dados de qualquer contrato inteligente nas blockchains suportadas.
  </Card>

  <Card title="Operações de Escrita" icon="pen">
    Execute funções de contrato inteligente com gerenciamento completo de transações.
  </Card>

  <Card title="Estimativa de Taxas" icon="calculator">
    Calcule custos de gas antes da execução para garantir fundos suficientes.
  </Card>

  <Card title="Operações em Lote" icon="layer-group">
    Execute múltiplas chamadas de contrato em uma única requisição de API.
  </Card>
</CardGroup>

## Casos de Uso

A API de Contratos Inteligentes desbloqueia capacidades poderosas para desenvolvedores fintech:

* **Integração DeFi**: Conecte-se a protocolos como Uniswap, Aave ou Compound para gerenciamento de rendimento e liquidez
* **Operações de Tesouraria**: Automatize o gerenciamento de tesouraria dentro da sua plataforma fintech
* **Ativos Tokenizados**: Integre ativos do mundo real nos seus fluxos de produtos
* **Liquidações Programáveis**: Execute verificações de conformidade e liquidações automatizadas
* **Ativos Personalizados**: Gerencie ativos personalizados, sistemas de recompensas e programas de fidelidade

## Carteira Principal vs Endereço Filho

A API de Contratos Inteligentes está disponível em dois níveis:

<CardGroup cols={2}>
  <Card title="Carteira Principal" icon="wallet">
    Execute operações de contrato diretamente da sua carteira principal. Ideal para operações de tesouraria e gerenciamento centralizado de fundos.
  </Card>

  <Card title="Endereço Filho" icon="address-card">
    Execute operações de contrato a partir de endereços filhos individuais. Perfeito para operações específicas de usuários e gerenciamento segregado de fundos.
  </Card>
</CardGroup>

### Endpoints da Carteira Principal

| Operação       | Endpoint                                            | Descrição                                 |
| -------------- | --------------------------------------------------- | ----------------------------------------- |
| Leitura        | `POST /v1/wallets/{walletId}/contracts/read`        | Recuperar dados de contratos inteligentes |
| Escrita        | `POST /v1/wallets/{walletId}/contracts/write`       | Executar funções de contrato inteligente  |
| Taxa de Rede   | `POST /v1/wallets/{walletId}/contracts/network-fee` | Estimar custos de gas                     |
| Apenas Assinar | `POST /v1/wallets/{walletId}/contracts/write/sign`  | Assinar sem transmitir                    |

### Endpoints do Endereço Filho

| Operação       | Endpoint                                                                  | Descrição                                 |
| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
| Leitura        | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/read`        | Recuperar dados de contratos inteligentes |
| Escrita        | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write`       | Executar funções de contrato inteligente  |
| Taxa de Rede   | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/network-fee` | Estimar custos de gas                     |
| Apenas Assinar | `POST /v1/wallets/{walletId}/addresses/{addressId}/contracts/write/sign`  | Assinar sem transmitir                    |

## Estrutura da Requisição

Todas as requisições de contrato inteligente requerem estes parâmetros:

| Parâmetro    | Tipo   | Obrigatório | Descrição                                                              |
| ------------ | ------ | ----------- | ---------------------------------------------------------------------- |
| `address`    | string | Sim         | O endereço blockchain do contrato inteligente                          |
| `method`     | string | Sim         | O nome da função a ser chamada                                         |
| `parameters` | array  | Sim         | Argumentos correspondentes à ordem do ABI da função                    |
| `abi`        | array  | Sim         | A Interface Binária de Aplicação do contrato                           |
| `reference`  | string | Não         | Seu ID de rastreamento interno para a transação                        |
| `metadata`   | object | Não         | Pares chave-valor personalizados para detalhes adicionais da transação |

<Info>
  Os campos `reference` e `metadata` são aplicáveis apenas para operações de escrita. Operações de leitura não suportam esses campos.
</Info>

### Entendendo ABIs

O ABI (Application Binary Interface) define como interagir com um contrato inteligente. Você pode obter ABIs de:

* **Exploradores de blocos**: Etherscan, BscScan, PolygonScan (contratos verificados)
* **Documentação de protocolos**: Docs oficiais de protocolos DeFi
* **Código fonte do contrato**: Compilar a partir do código fonte Solidity

## Lendo Dados do Contrato

Use o endpoint de leitura para consultar o estado do contrato sem modificar a blockchain.

### Exemplo de Leitura com Carteira 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>

### Exemplo de Leitura com Endereço Filho

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

### Resposta de Leitura

```json theme={null}
{
  "message": "Contrato lido com sucesso",
  "statusCode": 200,
  "data": "10052335235393043"
}
```

### Respostas de Erro de Leitura

<AccordionGroup>
  <Accordion title="Endereço de Contrato Inválido">
    ```json theme={null}
    {
      "message": "Endereço de contrato inválido",
      "statusCode": 400,
      "error": "BAD_REQUEST"
    }
    ```
  </Accordion>

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

  <Accordion title="Execução do Contrato Revertida">
    ```json theme={null}
    {
      "message": "Execução do contrato revertida",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: consulta de saldo para endereço zero"
      }
    }
    ```
  </Accordion>

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

## Escrevendo em Contratos

Execute funções que alteram o estado em contratos inteligentes.

### Exemplo de Escrita com Carteira 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": "0xSEU_CONTRATO_DE_TOKEN",
      "method": "approve",
      "parameters": ["0xSEU_ENDERECO_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: '0xSEU_CONTRATO_DE_TOKEN',
        method: 'approve',
        parameters: ['0xSEU_ENDERECO_GASTADOR', '1000000000000000000'],
        abi: [{
          inputs: [
            { name: 'spender', type: 'address' },
            { name: 'amount', type: 'uint256' }
          ],
          name: 'approve',
          outputs: [{ name: '', type: 'bool' }],
          stateMutability: 'nonpayable',
          type: 'function'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Exemplo de Escrita com Endereço Filho

<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": "0xSEU_CONTRATO_DE_TOKEN",
      "method": "approve",
      "parameters": ["0xSEU_ENDERECO_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: '0xSEU_CONTRATO_DE_TOKEN',
        method: 'approve',
        parameters: ['0xSEU_ENDERECO_GASTADOR', '1000000000000000000'],
        abi: [{
          inputs: [
            { name: 'spender', type: 'address' },
            { name: 'amount', type: 'uint256' }
          ],
          name: 'approve',
          outputs: [{ name: '', type: 'bool' }],
          stateMutability: 'nonpayable',
          type: 'function'
        }]
      })
    }
  );
  ```
</CodeGroup>

### Resposta de Escrita

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

<Warning>
  As operações de escrita são assíncronas. A resposta inicial mostra status `PENDING`. Escute o webhook `custom-smart-contract.success` para confirmar a conclusão da transação.
</Warning>

### Respostas de Erro de Escrita

<AccordionGroup>
  <Accordion title="Gas Insuficiente">
    ```json theme={null}
    {
      "message": "Saldo insuficiente de token nativo 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="Transação Revertida">
    ```json theme={null}
    {
      "message": "A transação seria revertida",
      "statusCode": 400,
      "error": "EXECUTION_REVERTED",
      "data": {
        "reason": "ERC20: valor de transferência excede autorização"
      }
    }
    ```
  </Accordion>

  <Accordion title="ABI Inválido">
    ```json theme={null}
    {
      "message": "Formato de ABI inválido",
      "statusCode": 400,
      "error": "INVALID_ABI",
      "data": {
        "details": "Campo 'inputs' ausente na definição do ABI"
      }
    }
    ```
  </Accordion>

  <Accordion title="Carteira Não Encontrada">
    ```json theme={null}
    {
      "message": "Carteira não encontrada",
      "statusCode": 404,
      "error": "NOT_FOUND"
    }
    ```
  </Accordion>
</AccordionGroup>

## Estimando Taxas de Rede

Sempre estime as taxas antes de executar operações de escrita para garantir que sua carteira tenha moeda nativa suficiente.

### Estimativa de Taxa com Carteira 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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'
```

### Estimativa de Taxa com Endereço Filho

```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": "0xSEU_CONTRATO_DE_TOKEN",
    "method": "approve",
    "parameters": ["0xSEU_ENDERECO_GASTADOR", "1000000000000000000"],
    "abi": [{
      "inputs": [
        {"name": "spender", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "approve",
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable",
      "type": "function"
    }]
  }'
```

### Resposta de Taxa

```json theme={null}
{
  "message": "Taxa de rede obtida",
  "statusCode": 200,
  "data": {
    "networkFee": "0.00001247904",
    "networkFeeInUSD": "0.01",
    "nativeBalance": "0.5",
    "nativeBalanceInUSD": "450.00",
    "estimatedArrivalTime": 30
  }
}
```

***

## Exemplo Prático: Troca de Ativos no Uniswap

Esta seção demonstra duas abordagens para executar uma troca de ativos: **sem operações em lote** (chamadas sequenciais) e **com operações em lote** (única chamada de API).

### Exemplo 1: Troca de Ativos SEM Operações em Lote

Esta abordagem faz chamadas de API individuais para cada etapa. Use quando você precisar de controle granular sobre cada transação ou quando as operações dependem dos resultados de chamadas anteriores.

#### Etapa 1: Verificar Saldo de Ativos

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

#### Etapa 2: Aprovar Gasto de Ativos

```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 Aprovação:', approval.data.hash);
// IMPORTANTE: Aguarde a confirmação do webhook antes de prosseguir
```

<Warning>
  Sempre aguarde o webhook `custom-smart-contract.success` confirmando que a transação de aprovação foi minerada antes de executar a troca.
</Warning>

#### Etapa 3: Estimar Taxas da Troca

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

#### Etapa 4: Executar Troca

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

***

### Exemplo 2: Troca de Ativos COM Operações em Lote

Esta abordagem combina aprovar + trocar em uma única chamada de API usando o array `calls`. Use para eficiência quando quiser enfileirar múltiplas operações juntas.

<Note>
  As operações em lote são executadas sequencialmente. Cada operação é enviada como uma transação separada, mas você só precisa de uma chamada de API.
</Note>

#### Requisição em Lote: Aprovar + Trocar em Uma Chamada

```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: 'aprovação' }
        },
        {
          address: UNISWAP_ROUTER,
          method: 'swapExactTokensForTokens',
          parameters: [
            amountIn,
            amountOutMin,
            [TOKEN_A, TOKEN_B],
            walletAddress,
            deadline
          ],
          abi: [swapAbi],
          reference: 'swap-tx',
          metadata: { step: 'troca' }
        }
      ]
    })
  }
).then(r => r.json());

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

#### Resposta do Lote

```json theme={null}
{
  "message": "Escrita de contrato em lote iniciada com sucesso",
  "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": []
  }
}
```

#### Tratando Falhas Parciais em Lote

```javascript theme={null}
const result = await batchSwap.json();

// Verificar operações bem-sucedidas
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Verificar operações com falha
result.data.errors.forEach(error => {
  console.error(`✗ Operação ${error.index} (${error.method}): ${error.error}`);
});
```

### Regras de Operações em Lote

| Regra                  | Valor                                                     |
| ---------------------- | --------------------------------------------------------- |
| Tamanho máximo do lote | 20 operações                                              |
| Ordem de execução      | Sequencial                                                |
| Tratamento de erros    | Sucesso parcial (falhas não param operações subsequentes) |

### Quando Usar Cada Abordagem

| Cenário                                                | Abordagem Recomendada |
| ------------------------------------------------------ | --------------------- |
| Precisa verificar resultados entre etapas              | Sem Lote              |
| Parâmetros dinâmicos baseados em resultados anteriores | Sem Lote              |
| Padrões simples de aprovar + ação                      | Com Lote              |
| Múltiplas operações independentes                      | Com Lote              |
| Minimizar chamadas de API                              | Com Lote              |

***

## Eventos de Webhook

Operações de contrato inteligente disparam notificações de webhook:

| Evento                          | Descrição                                  |
| ------------------------------- | ------------------------------------------ |
| `custom-smart-contract.success` | Operação de contrato concluída com sucesso |
| `custom-smart-contract.failed`  | Operação de contrato falhou                |

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

## Melhores Práticas

### Segurança

* **Verifique endereços de contrato**: Sempre verifique os endereços de contrato antes de interagir
* **Use ABIs confiáveis**: Obtenha ABIs de fontes verificadas como exploradores de blocos
* **Defina limites razoáveis**: Use proteção contra slippage e limites de valor para operações DeFi

### Gerenciamento de Gas

* **Estime antes de executar**: Sempre chame o endpoint de taxa de rede primeiro
* **Monitore o saldo nativo**: Garanta ETH/BNB/MATIC suficiente para taxas de gas
* **Use operações em lote**: Reduza a sobrecarga agrupando operações relacionadas

### Tratamento de Erros

* **Implemente listeners de webhook**: Não dependa apenas das respostas da API
* **Trate falhas parciais**: Verifique ambos os arrays `success` e `errors` nas respostas de lote
* **Tente novamente com backoff**: Implemente backoff exponencial para falhas transitórias

## Referência da API

### Endpoints da Carteira Principal

| Endpoint                                                                         | Descrição                    |
| -------------------------------------------------------------------------------- | ---------------------------- |
| [Ler Contrato](/pt/api-reference/smart-contract/master-wallet-read)              | Ler estado do contrato       |
| [Escrever Contrato](/pt/api-reference/smart-contract/master-wallet-write)        | Executar funções do contrato |
| [Taxa de Rede](/pt/api-reference/smart-contract/master-wallet-network-fee)       | Estimar custos de gas        |
| [Apenas Assinar](/pt/api-reference/smart-contract/master-wallet-write-sign-only) | Assinar sem transmitir       |

### Endpoints do Endereço Filho

| Endpoint                                                                         | Descrição                    |
| -------------------------------------------------------------------------------- | ---------------------------- |
| [Ler Contrato](/pt/api-reference/smart-contract/child-address-read)              | Ler estado do contrato       |
| [Escrever Contrato](/pt/api-reference/smart-contract/child-address-write)        | Executar funções do contrato |
| [Taxa de Rede](/pt/api-reference/smart-contract/child-address-network-fee)       | Estimar custos de gas        |
| [Apenas Assinar](/pt/api-reference/smart-contract/child-address-write-sign-only) | Assinar sem transmitir       |

## Suporte

* **Email**: [partner@yiksi.com](mailto:partner@yiksi.com)
* **Documentação**: [Referência da API](/pt/api-reference/smart-contract/master-wallet-read)

<Note>
  A API de Contratos Inteligentes permite que você construa integrações blockchain sofisticadas sem gerenciar a complexidade da infraestrutura. Comece com operações de leitura simples e gradualmente incorpore operações de escrita à medida que se familiarizar com o sistema.
</Note>