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

# Swap e Bridge

> Troque ativos entre cadeias com uma API unificada

<img src="https://mintcdn.com/blockradar/FrE2zfJ4u32QicMn/images/swap.jpg?fit=max&auto=format&n=FrE2zfJ4u32QicMn&q=85&s=a3cb4d76aa3218dd5b8cf2c816d55b93" alt="Swap e Bridge" width="2880" height="1620" data-path="images/swap.jpg" />

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

## Pré-requisitos

Antes de usar a API Swap, garanta que você tem:

<Steps>
  <Step title="Chave de API">
    Obtenha sua chave de API no [Dashboard da Blockradar](https://dashboard.blockradar.co). Vá até **Developers** para gerar uma.
  </Step>

  <Step title="Wallet criada">
    Crie uma wallet pela [API Create Wallet](/en/api-reference/wallets/create-wallet) ou pelo dashboard. Você precisará do `walletId` para as operações de swap.
  </Step>

  <Step title="IDs de ativos">
    Obtenha o `assetId` dos seus ativos de origem e destino em **Assets** no dashboard ou pela [API Get Assets](/en/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Saldo suficiente">
    Garanta que sua wallet tenha saldo suficiente do ativo de origem para cobrir o valor do swap mais as taxas de rede.
  </Step>
</Steps>

## Como funciona

A Blockradar determina automaticamente se sua transação é um **swap** ou um **bridge** com base na seleção dos ativos:

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

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

  <Card title="Bridge" icon="bridge">
    Movimente ativos entre **blockchains diferentes**.

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

<Tip>
  Você não precisa especificar se é um swap ou um bridge — a API trata isso automaticamente com base no `fromAssetId` e no `toAssetId` que você fornecer.
</Tip>

## Ativos e cadeias suportados

A API Swap suporta as principais stablecoins nas cadeias compatíveis com a Blockradar:

| Stablecoin | Descrição                  |
| ---------- | -------------------------- |
| USDT       | Tether USD                 |
| USDC       | USD Coin                   |
| DAI        | Dai Stablecoin             |
| BUSD       | Binance USD                |
| cNGN       | Stablecoin de Naira        |
| EURC       | Euro Coin                  |
| IDRX       | Stablecoin da Indonésia    |
| JPYC       | Stablecoin de Iene Japonês |

<Warning>
  A disponibilidade dos ativos varia por cadeia. Use sempre a [API Get Assets](/en/api-reference/miscellaneous/get-assets) para obter a lista atualizada de ativos suportados e seus valores de `assetId` para as cadeias de destino.
</Warning>

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

## Master Wallet vs Child Address

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

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Execute swaps diretamente da sua master wallet. Ideal para operações de tesouraria.
  </Card>

  <Card title="Child Address" icon="address-card">
    Execute swaps a partir de child addresses individuais. Perfeito para operações específicas de cada usuário.
  </Card>
</CardGroup>

### Endpoints

| Operação      | Master Wallet                               | Child Address                                                     |
| ------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| 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 solicite uma cotação antes de executar um swap para mostrar ao usuário o resultado esperado.

### Parâmetros da requisição

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                    |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------- |
| `fromAssetId`      | string | Sim         | O asset ID de origem do swap                                                 |
| `toAssetId`        | string | Sim         | O asset ID de destino do swap                                                |
| `amount`           | string | Sim         | O valor a ser trocado                                                        |
| `order`            | string | Não         | Preferência da cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`  |
| `recipientAddress` | string | Não         | Endereço de wallet externa (para envios a wallets que não são da Blockradar) |

### Exemplo de cotação

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/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.blockradar.co/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('Quote:', quote.data);
  ```
</CodeGroup>

### Resposta da cotação

```json theme={null}
{
  "message": "Swap quote fetched successfully",
  "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 o swap     |
| `minAmount`            | Valor mínimo garantido (considerando o slippage) |
| `rate`                 | Taxa de câmbio efetiva (toAmount / fromAmount)   |
| `impact`               | Percentual de impacto no preço                   |
| `slippage`             | Percentual máximo de variação de preço permitida |
| `networkFee`           | Taxa de gás em unidades do token nativo          |
| `networkFeeInUSD`      | Taxa de gás convertida em USD                    |
| `estimatedArrivalTime` | Tempo estimado de conclusão em segundos          |

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

## Passo 2: Executar o Swap

Assim que o usuário confirmar a cotação, execute o swap.

### Parâmetros da requisição

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                    |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------- |
| `fromAssetId`      | string | Sim         | O asset ID de origem do swap                                                 |
| `toAssetId`        | string | Sim         | O asset ID de destino do swap                                                |
| `amount`           | string | Sim         | O valor a ser trocado                                                        |
| `order`            | string | Não         | Preferência da cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`  |
| `recipientAddress` | string | Não         | Endereço de wallet externa (para envios a wallets que não são da Blockradar) |
| `reference`        | string | Não         | Seu ID interno de rastreamento                                               |
| `metadata`         | object | Não         | Dados personalizados encaminhados via webhooks                               |

### Exemplo de execução

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/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.blockradar.co/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('Swap initiated:', swap.data);
  ```
</CodeGroup>

### Resposta da execução

```json theme={null}
{
  "message": "Swap transaction created successfully",
  "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 swap são assíncronas. A resposta inicial mostra o status `PENDING`. Escute o webhook `swap.success` ou `swap.failed` para confirmar a conclusão.
</Warning>

## Tipos de ordem

Escolha o tipo de ordem adequado ao seu caso de uso:

| Tipo de ordem | Descrição                               | Indicado para                     |
| ------------- | --------------------------------------- | --------------------------------- |
| `FASTEST`     | Prioriza velocidade em relação ao custo | Transações com restrição de tempo |
| `CHEAPEST`    | Minimiza as taxas                       | Operações sensíveis ao custo      |
| `RECOMMENDED` | Abordagem equilibrada (padrão)          | Maioria dos casos                 |
| `NO_SLIPPAGE` | Valor exato ou falha                    | Requisitos de valor preciso       |

## Eventos de Webhook

Monitore a conclusão do swap por meio de webhooks:

| Evento         | Descrição                  |
| -------------- | -------------------------- |
| `swap.success` | Swap concluído com sucesso |
| `swap.failed`  | Swap 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

A seguir, uma implementação completa demonstrando o fluxo cotação → confirmação → execução:

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

  // Step 1: Get quote
  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());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.amount}`);
  console.log(`Minimum amount: ${quote.data.minAmount}`);
  console.log(`Network fee: $${quote.data.networkFeeInUSD}`);
  console.log(`Estimated time: ${quote.data.estimatedArrivalTime}s`);

  // Step 3: Execute swap (after user confirmation)
  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('Swap initiated:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Step 4: Listen for webhook to confirm completion
  return swap.data;
}

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

## Respostas de erro

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

  <Accordion title="Asset ID inválido">
    ```json theme={null}
    {
      "message": "Asset not found",
      "statusCode": 404,
      "error": "ASSET_NOT_FOUND",
      "data": {
        "assetId": "invalid_asset_id"
      }
    }
    ```
  </Accordion>

  <Accordion title="Rota de swap indisponível">
    ```json theme={null}
    {
      "message": "No swap route available for this pair",
      "statusCode": 400,
      "error": "NO_ROUTE_AVAILABLE",
      "data": {
        "fromAsset": "USDC",
        "toAsset": "CUSTOM_TOKEN"
      }
    }
    ```
  </Accordion>

  <Accordion title="Valor muito baixo">
    ```json theme={null}
    {
      "message": "Amount below minimum swap threshold",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Slippage excedido">
    ```json theme={null}
    {
      "message": "Price moved beyond slippage tolerance",
      "statusCode": 400,
      "error": "SLIPPAGE_EXCEEDED",
      "data": {
        "expectedAmount": "99.45",
        "actualAmount": "97.00",
        "slippageTolerance": "0.5%"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Boas práticas

### Experiência do usuário

* **Sempre exiba cotações**: mostre 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 do swap

### Segurança

* **Valide os valores**: garanta que os valores do swap estejam dentro de faixas aceitáveis
* **Use referências**: rastreie os swaps com IDs de referência únicos
* **Monitore os webhooks**: sempre verifique a conclusão do swap por meio de webhooks

### Desempenho

* **Faça cache dos asset IDs**: armazene os asset IDs localmente para evitar consultas repetidas
* **Use os tipos de ordem adequados**: escolha `FASTEST` para casos sensíveis ao tempo e `CHEAPEST` para os sensíveis ao custo
* **Implemente retentativas**: trate falhas transitórias com backoff exponencial

## Referência da API

| Endpoint                                                                  | Descrição                                   |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| [Master Wallet Get Quote](/en/api-reference/swap/master-wallet-get-quote) | Obter cotação de swap pela master wallet    |
| [Master Wallet Execute](/en/api-reference/swap/master-wallet-execute)     | Executar swap pela master wallet            |
| [Child Address Get Quote](/en/api-reference/swap/child-address-get-quote) | Obter cotação de swap por uma child address |
| [Child Address Execute](/en/api-reference/swap/child-address-execute)     | Executar swap por uma child address         |

## Suporte

* **E-mail**: [support@blockradar.co](mailto:support@blockradar.co)
* **Documentação**: [Referência da API](/en/api-reference/swap/master-wallet-get-quote)
* **Blog**: [Como fazer swap ou bridge de ativos com a Blockradar](https://www.blockradar.co/blog/how-to-swap-or-bridge-assets-with-blockradar-a-follow-along-guide)

<Note>
  A API Swap fornece uma interface unificada para swaps na mesma cadeia e bridges entre cadeias. Comece com pequenos valores de teste em testnets antes de migrar para produção.
</Note>