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

> Intercambie activos entre cadenas con una API unificada

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

<Note>
  En resumen<br />
  La API Swap de Blockradar le permite intercambiar activos en la misma cadena (swap) o transferir activos entre cadenas distintas (bridge) mediante un único endpoint unificado.
</Note>

## Requisitos previos

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

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

  <Step title="Wallet creada">
    Cree una wallet a través de la [API Create Wallet](/en/api-reference/wallets/create-wallet) o desde el dashboard. Necesitará el `walletId` para las operaciones de swap.
  </Step>

  <Step title="IDs de activos">
    Obtenga el `assetId` de sus activos de origen y destino desde **Assets** en el dashboard o mediante la [API Get Assets](/en/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Saldo suficiente">
    Asegúrese de que su wallet tenga saldo suficiente del activo de origen para cubrir el monto del swap más las comisiones de red.
  </Step>
</Steps>

## Cómo funciona

Blockradar determina automáticamente si su transacción es un **swap** o un **bridge** según los activos seleccionados:

<CardGroup cols={2}>
  <Card title="Swap" icon="repeat">
    Intercambie distintos activos en la **misma blockchain**.

    *Ejemplo: USDC → USDT en Base*
  </Card>

  <Card title="Bridge" icon="bridge">
    Mueva activos entre **blockchains diferentes**.

    *Ejemplo: USDC en BSC → USDC en Optimism*
  </Card>
</CardGroup>

<Tip>
  No necesita especificar si se trata de un swap o un bridge: la API lo gestiona automáticamente según el `fromAssetId` y el `toAssetId` que proporcione.
</Tip>

## Activos y cadenas compatibles

La API Swap admite las principales stablecoins en las cadenas compatibles con Blockradar:

| Stablecoin | Descripción               |
| ---------- | ------------------------- |
| USDT       | Tether USD                |
| USDC       | USD Coin                  |
| DAI        | Dai Stablecoin            |
| BUSD       | Binance USD               |
| cNGN       | Stablecoin de Naira       |
| EURC       | Euro Coin                 |
| IDRX       | Stablecoin de Indonesia   |
| JPYC       | Stablecoin de Yen Japonés |

<Warning>
  La disponibilidad de activos varía según la cadena. Utilice siempre la [API Get Assets](/en/api-reference/miscellaneous/get-assets) para obtener la lista actualizada de activos compatibles y sus valores de `assetId` en las cadenas de destino.
</Warning>

<Note>
  Consulte [Integraciones](/en/essentials/integrations) para ver la lista completa de redes y stablecoins compatibles.
</Note>

## Master Wallet vs Child Address

La API Swap está disponible en dos niveles:

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Ejecute swaps directamente desde su master wallet. Ideal para operaciones de tesorería.
  </Card>

  <Card title="Child Address" icon="address-card">
    Ejecute swaps desde child addresses individuales. Perfecto para operaciones específicas de cada usuario.
  </Card>
</CardGroup>

### Endpoints

| Operación          | Master Wallet                               | Child Address                                                     |
| ------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| Obtener cotización | `POST /v1/wallets/{walletId}/swaps/quote`   | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote`   |
| Ejecutar           | `POST /v1/wallets/{walletId}/swaps/execute` | `POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute` |

## Paso 1: Obtener una cotización

Solicite siempre una cotización antes de ejecutar un swap para mostrar al usuario el resultado esperado.

### Parámetros de la solicitud

| Parámetro          | Tipo   | Requerido | Descripción                                                                    |
| ------------------ | ------ | --------- | ------------------------------------------------------------------------------ |
| `fromAssetId`      | string | Sí        | El asset ID desde el que se intercambia                                        |
| `toAssetId`        | string | Sí        | El asset ID hacia el que se intercambia                                        |
| `amount`           | string | Sí        | El monto a intercambiar                                                        |
| `order`            | string | No        | Preferencia de cotización: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | No        | Dirección de wallet externa (para enviar a wallets que no son de Blockradar)   |

### Ejemplo de cotización

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

### Respuesta de la cotización

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

### Cómo interpretar los campos de la cotización

| Campo                  | Descripción                                         |
| ---------------------- | --------------------------------------------------- |
| `amount`               | Monto estimado que recibirá tras el swap            |
| `minAmount`            | Monto mínimo garantizado (considerando el slippage) |
| `rate`                 | Tasa de cambio efectiva (toAmount / fromAmount)     |
| `impact`               | Porcentaje de impacto en el precio                  |
| `slippage`             | Porcentaje máximo de variación de precio permitida  |
| `networkFee`           | Comisión de gas en unidades del token nativo        |
| `networkFeeInUSD`      | Comisión de gas convertida a USD                    |
| `estimatedArrivalTime` | Tiempo estimado de finalización en segundos         |

<Tip>
  Muestre siempre como mínimo: **monto a recibir**, **tiempo estimado de llegada** y **comisiones** antes de que el usuario confirme el swap.
</Tip>

## Paso 2: Ejecutar el Swap

Una vez que el usuario confirme la cotización, ejecute el swap.

### Parámetros de la solicitud

| Parámetro          | Tipo   | Requerido | Descripción                                                                    |
| ------------------ | ------ | --------- | ------------------------------------------------------------------------------ |
| `fromAssetId`      | string | Sí        | El asset ID desde el que se intercambia                                        |
| `toAssetId`        | string | Sí        | El asset ID hacia el que se intercambia                                        |
| `amount`           | string | Sí        | El monto a intercambiar                                                        |
| `order`            | string | No        | Preferencia de cotización: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE` |
| `recipientAddress` | string | No        | Dirección de wallet externa (para enviar a wallets que no son de Blockradar)   |
| `reference`        | string | No        | Su ID interno de seguimiento                                                   |
| `metadata`         | object | No        | Datos personalizados que se transmiten mediante webhooks                       |

### Ejemplo de ejecución

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

### Respuesta de la ejecución

```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>
  Las operaciones de swap son asíncronas. La respuesta inicial muestra el estado `PENDING`. Escuche el webhook `swap.success` o `swap.failed` para confirmar la finalización.
</Warning>

## Tipos de orden

Elija el tipo de orden adecuado según su caso de uso:

| Tipo de orden | Descripción                          | Recomendado para                  |
| ------------- | ------------------------------------ | --------------------------------- |
| `FASTEST`     | Prioriza la velocidad sobre el costo | Transacciones sensibles al tiempo |
| `CHEAPEST`    | Minimiza las comisiones              | Operaciones sensibles al costo    |
| `RECOMMENDED` | Enfoque equilibrado (predeterminado) | La mayoría de los casos           |
| `NO_SLIPPAGE` | Monto exacto o falla                 | Requisitos de monto preciso       |

## Eventos de Webhook

Monitoree la finalización del swap mediante webhooks:

| Evento         | Descripción                   |
| -------------- | ----------------------------- |
| `swap.success` | Swap completado correctamente |
| `swap.failed`  | Swap fallido                  |

### Carga útil del 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"
  }
}
```

## Ejemplo de flujo completo

A continuación se muestra una implementación completa con el flujo cotización → confirmación → ejecución:

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

## Respuestas de error

<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="Ruta de swap no disponible">
    ```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="Monto demasiado bajo">
    ```json theme={null}
    {
      "message": "Amount below minimum swap threshold",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Slippage superado">
    ```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>

## Buenas prácticas

### Experiencia de usuario

* **Muestre siempre las cotizaciones**: presente monto, comisiones y tiempo estimado antes de ejecutar
* **Gestione el slippage**: informe a los usuarios sobre posibles variaciones de precio
* **Muestre el progreso**: utilice webhooks para mantener informados a los usuarios sobre el estado del swap

### Seguridad

* **Valide los montos**: asegúrese de que los montos del swap se encuentren dentro de rangos aceptables
* **Use referencias**: rastree los swaps con IDs de referencia únicos
* **Monitoree los webhooks**: verifique siempre la finalización del swap mediante webhooks

### Rendimiento

* **Cachee los asset IDs**: almacene los asset IDs localmente para evitar consultas repetidas
* **Use los tipos de orden adecuados**: elija `FASTEST` para transacciones sensibles al tiempo y `CHEAPEST` para las sensibles al costo
* **Implemente reintentos**: maneje fallos transitorios con retroceso exponencial

## Referencia de API

| Endpoint                                                                  | Descripción                                        |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| [Master Wallet Get Quote](/en/api-reference/swap/master-wallet-get-quote) | Obtener cotización de swap desde la master wallet  |
| [Master Wallet Execute](/en/api-reference/swap/master-wallet-execute)     | Ejecutar swap desde la master wallet               |
| [Child Address Get Quote](/en/api-reference/swap/child-address-get-quote) | Obtener cotización de swap desde una child address |
| [Child Address Execute](/en/api-reference/swap/child-address-execute)     | Ejecutar swap desde una child address              |

## Soporte

* **Email**: [support@blockradar.co](mailto:support@blockradar.co)
* **Documentación**: [Referencia de API](/en/api-reference/swap/master-wallet-get-quote)
* **Blog**: [Cómo intercambiar o hacer bridge de activos con Blockradar](https://www.blockradar.co/blog/how-to-swap-or-bridge-assets-with-blockradar-a-follow-along-guide)

<Note>
  La API Swap proporciona una interfaz unificada para swaps en la misma cadena y bridges entre cadenas. Comience con pequeños montos de prueba en testnets antes de pasar a producción.
</Note>