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

# Troca & Ponte

> Troque ativos entre cadeias com uma API unificada

<Note>
  Em resumo<br />
  A API de Troca da Yiksi Pay permite que você troque ativos na mesma cadeia (swap) ou mova ativos entre diferentes cadeias (bridge) usando um único endpoint unificado.
</Note>

## Pré-requisitos

Antes de usar a API de Troca, 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 operações de troca.
  </Step>

  <Step title="IDs de Ativos">
    Obtenha o `assetId` dos seus ativos de origem e destino em **Ativos** no painel ou via [API Obter Ativos](/pt/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Saldo Suficiente">
    Certifique-se de que sua carteira tenha saldo suficiente do ativo de origem para cobrir o valor da troca mais as taxas de rede.
  </Step>
</Steps>

## Como Funciona

A Yiksi Pay determina automaticamente se sua transação é uma **troca** ou uma **ponte** com base na sua seleção de ativos:

<CardGroup cols={2}>
  <Card title="Troca" icon="repeat">
    Troque diferentes ativos na **mesma blockchain**.

    *Exemplo: USDC → USDT na Base*
  </Card>

  <Card title="Ponte" icon="bridge">
    Mova ativos entre **diferentes blockchains**.

    *Exemplo: USDC na BSC → USDC na Optimism*
  </Card>
</CardGroup>

<Tip>
  Você não precisa especificar se é uma troca ou ponte—a API lida com isso automaticamente com base no `fromAssetId` e `toAssetId` que você fornece.
</Tip>

## Ativos e Cadeias Suportados

A API de Troca suporta as principais stablecoins nas cadeias suportadas pela Yiksi Pay:

| Stablecoin | Descrição             |
| ---------- | --------------------- |
| USDT       | Tether USD            |
| USDC       | USD Coin              |
| DAI        | Dai Stablecoin        |
| BUSD       | Binance USD           |
| cNGN       | Naira Stablecoin      |
| EURC       | Euro Coin             |
| IDRX       | Indonesian Stablecoin |

<Warning>
  A disponibilidade de ativos varia por cadeia. Sempre use a [API Obter Ativos](/pt/api-reference/miscellaneous/get-assets) para buscar a lista atual de ativos suportados e seus valores de `assetId` para suas cadeias alvo.
</Warning>

<Note>
  Consulte [Integrações](/pt/essentials/integrations) para a lista completa de redes e stablecoins suportadas.
</Note>

## Carteira Principal vs Endereço Filho

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

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

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

### Endpoints

| Operação      | Carteira Principal                          | Endereço Filho                                                    |
| ------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| Obter Cotação | `POST /v1/wallets/{walletId}/swaps/quote`   | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote`   |
| Executar      | `POST /v1/wallets/{walletId}/swaps/execute` | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute` |

## Passo 1: Obter uma Cotação

Sempre busque uma cotação antes de executar uma troca para mostrar aos usuários o resultado esperado.

### Parâmetros da Requisição

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                   |
| ------------------ | ------ | ----------- | --------------------------------------------------------------------------- |
| `fromAssetId`      | string | Sim         | O ID do ativo de origem                                                     |
| `toAssetId`        | string | Sim         | O ID do ativo de destino                                                    |
| `amount`           | string | Sim         | O valor a ser trocado                                                       |
| `order`            | string | Não         | Preferência de cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | Não         | Endereço de carteira externa (para envio para carteiras não-Yiksi Pay)      |

### Exemplo de Cotação

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/swaps/quote \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "fromAssetId": "asset_usdc_base_mainnet",
      "toAssetId": "asset_usdt_bsc_mainnet",
      "amount": "100",
      "order": "RECOMMENDED"
    }'
  ```

  ```javascript JavaScript theme={null}
  const quote = await fetch(
    `https://api.yiksipay.com/v1/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId: 'asset_usdc_base_mainnet',
        toAssetId: 'asset_usdt_bsc_mainnet',
        amount: '100',
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  console.log('Cotação:', quote.data);
  ```
</CodeGroup>

### Resposta da Cotação

```json theme={null}
{
  "message": "Cotação de troca obtida com sucesso",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180
  }
}
```

### Entendendo os Campos da Cotação

| Campo                  | Descrição                                           |
| ---------------------- | --------------------------------------------------- |
| `amount`               | Valor estimado que você receberá após a troca       |
| `minAmount`            | Valor mínimo garantido (considerando o slippage)    |
| `rate`                 | Taxa de câmbio efetiva (valorDestino / valorOrigem) |
| `impact`               | Porcentagem de impacto no preço                     |
| `slippage`             | Porcentagem máxima permitida de variação de preço   |
| `networkFee`           | Taxa de gas em unidades de token nativo             |
| `networkFeeInUSD`      | Taxa de gas convertida para USD                     |
| `estimatedArrivalTime` | Tempo esperado de conclusão em segundos             |

<Tip>
  Sempre exiba no mínimo: **valor a receber**, **tempo estimado de chegada** e **taxas** antes que o usuário confirme a troca.
</Tip>

## Passo 2: Executar a Troca

Depois que o usuário confirmar a cotação, execute a troca.

### Parâmetros da Requisição

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                   |
| ------------------ | ------ | ----------- | --------------------------------------------------------------------------- |
| `fromAssetId`      | string | Sim         | O ID do ativo de origem                                                     |
| `toAssetId`        | string | Sim         | O ID do ativo de destino                                                    |
| `amount`           | string | Sim         | O valor a ser trocado                                                       |
| `order`            | string | Não         | Preferência de cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | Não         | Endereço de carteira externa (para envio para carteiras não-Yiksi Pay)      |
| `reference`        | string | Não         | Seu ID de rastreamento interno                                              |
| `metadata`         | object | Não         | Dados personalizados passados através dos webhooks                          |

### Exemplo de Execução

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.yiksipay.com/v1/wallets/{walletId}/swaps/execute \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "fromAssetId": "asset_usdc_base_mainnet",
      "toAssetId": "asset_usdt_bsc_mainnet",
      "amount": "100",
      "order": "RECOMMENDED",
      "reference": "swap-order-12345",
      "metadata": {
        "userId": "user_abc123",
        "orderId": "order_xyz789"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const swap = await fetch(
    `https://api.yiksipay.com/v1/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId: 'asset_usdc_base_mainnet',
        toAssetId: 'asset_usdt_bsc_mainnet',
        amount: '100',
        order: 'RECOMMENDED',
        reference: 'swap-order-12345',
        metadata: {
          userId: 'user_abc123',
          orderId: 'order_xyz789'
        }
      })
    }
  ).then(r => r.json());

  console.log('Troca iniciada:', swap.data);
  ```
</CodeGroup>

### Resposta da Execução

```json theme={null}
{
  "message": "Transação de troca criada com sucesso",
  "statusCode": 200,
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "PENDING",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base"
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc"
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

<Warning>
  As operações de troca são assíncronas. A resposta inicial mostra status `PENDING`. Escute o webhook `swap.success` ou `swap.failed` para confirmar a conclusão.
</Warning>

## Tipos de Ordem

Escolha o tipo de ordem certo com base no seu caso de uso:

| Tipo de Ordem | Descrição                       | Melhor Para                   |
| ------------- | ------------------------------- | ----------------------------- |
| `FASTEST`     | Prioriza velocidade sobre custo | Transações sensíveis ao tempo |
| `CHEAPEST`    | Minimiza taxas                  | Operações sensíveis a custos  |
| `RECOMMENDED` | Abordagem equilibrada (padrão)  | A maioria dos casos de uso    |
| `NO_SLIPPAGE` | Valor exato ou falha            | Requisitos de valor preciso   |

## Eventos de Webhook

Monitore a conclusão da troca através de webhooks:

| Evento         | Descrição                   |
| -------------- | --------------------------- |
| `swap.success` | Troca concluída com sucesso |
| `swap.failed`  | Troca falhou                |

### Payload do Webhook

```json theme={null}
{
  "event": "swap.success",
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "SUCCESS",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base",
      "hash": "0xabc..."
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc",
      "hash": "0xdef..."
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "completedAt": "2024-01-15T10:33:00Z"
  }
}
```

## Exemplo de Fluxo Completo

Aqui está uma implementação completa mostrando o fluxo cotação → confirmação → execução:

```javascript theme={null}
async function executeSwap(walletId, fromAssetId, toAssetId, amount) {
  const apiKey = process.env.YIKSIPAY_API_KEY;
  const baseUrl = 'https://api.yiksipay.com/v1';

  // Passo 1: Obter cotação
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Passo 2: Exibir cotação para o usuário
  console.log(`Você receberá: ${quote.data.amount}`);
  console.log(`Valor mínimo: ${quote.data.minAmount}`);
  console.log(`Taxa de rede: $${quote.data.networkFeeInUSD}`);
  console.log(`Tempo estimado: ${quote.data.estimatedArrivalTime}s`);

  // Passo 3: Executar troca (após confirmação do usuário)
  const swap = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED',
        reference: `swap-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Troca iniciada:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Passo 4: Escutar webhook para confirmar conclusão
  return swap.data;
}

// Uso
executeSwap(
  'wallet-uuid',
  'asset_usdc_base_mainnet',
  'asset_usdt_bsc_mainnet',
  '100'
);
```

## Respostas de Erro

<AccordionGroup>
  <Accordion title="Saldo Insuficiente">
    ```json theme={null}
    {
      "message": "Saldo insuficiente para troca",
      "statusCode": 400,
      "error": "INSUFFICIENT_BALANCE",
      "data": {
        "required": "100",
        "available": "50.25",
        "asset": "USDC"
      }
    }
    ```
  </Accordion>

  <Accordion title="ID de Ativo Inválido">
    ```json theme={null}
    {
      "message": "Ativo não encontrado",
      "statusCode": 404,
      "error": "ASSET_NOT_FOUND",
      "data": {
        "assetId": "invalid_asset_id"
      }
    }
    ```
  </Accordion>

  <Accordion title="Rota de Troca Não Disponível">
    ```json theme={null}
    {
      "message": "Nenhuma rota de troca disponível para este par",
      "statusCode": 400,
      "error": "NO_ROUTE_AVAILABLE",
      "data": {
        "fromAsset": "USDC",
        "toAsset": "CUSTOM_TOKEN"
      }
    }
    ```
  </Accordion>

  <Accordion title="Valor Muito Baixo">
    ```json theme={null}
    {
      "message": "Valor abaixo do limite mínimo de troca",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Slippage Excedido">
    ```json theme={null}
    {
      "message": "O preço variou além da tolerância de slippage",
      "statusCode": 400,
      "error": "SLIPPAGE_EXCEEDED",
      "data": {
        "expectedAmount": "99.45",
        "actualAmount": "97.00",
        "slippageTolerance": "0.5%"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Melhores Práticas

### Experiência do Usuário

* **Sempre mostre cotações**: Exiba valor, taxas e tempo estimado antes da execução
* **Trate o slippage**: Informe os usuários sobre possíveis variações de preço
* **Mostre o progresso**: Use webhooks para atualizar os usuários sobre o status da troca

### Segurança

* **Valide os valores**: Certifique-se de que os valores de troca estão dentro de faixas aceitáveis
* **Use referências**: Rastreie trocas com IDs de referência únicos
* **Monitore webhooks**: Sempre verifique a conclusão da troca via webhooks

### Performance

* **Armazene IDs de ativos em cache**: Armazene IDs de ativos localmente para evitar consultas repetidas
* **Use tipos de ordem apropriados**: Escolha `FASTEST` para sensibilidade ao tempo, `CHEAPEST` para sensibilidade a custos
* **Implemente retentativas**: Trate falhas transitórias com backoff exponencial

## Referência da API

| Endpoint                                                                           | Descrição                                    |
| ---------------------------------------------------------------------------------- | -------------------------------------------- |
| [Obter Cotação Carteira Principal](/pt/api-reference/swap/master-wallet-get-quote) | Obter cotação de troca da carteira principal |
| [Executar Carteira Principal](/pt/api-reference/swap/master-wallet-execute)        | Executar troca da carteira principal         |
| [Obter Cotação Endereço Filho](/pt/api-reference/swap/child-address-get-quote)     | Obter cotação de troca do endereço filho     |
| [Executar Endereço Filho](/pt/api-reference/swap/child-address-execute)            | Executar troca do endereço filho             |

## Suporte

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

<Note>
  A API de Troca fornece uma interface unificada para trocas na mesma cadeia e pontes entre cadeias. Comece com pequenos valores de teste em testnets antes de ir para produção.
</Note>