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

# Intercambio & Puente

> Intercambia 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="Intercambio & Puente" width="2880" height="1620" data-path="images/swap.jpg" />

<Note>
  En resumen<br />
  La API de Swap de Blockradar te permite intercambiar activos en la misma cadena (swap) o mover activos entre diferentes cadenas (bridge) usando un solo endpoint unificado.
</Note>

## Prerrequisitos

Antes de usar la API de Swap, asegúrate de tener:

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

  <Step title="Wallet Creado">
    Crea un wallet a través de la [API Crear Wallet](/es/api-reference/wallets/create-wallet) o el panel. Necesitarás el `walletId` para las operaciones de swap.
  </Step>

  <Step title="IDs de Activos">
    Obtén el `assetId` para tus activos de origen y destino desde **Activos** en el panel o a través de la [API Obtener Activos](/es/api-reference/miscellaneous/get-assets).
  </Step>

  <Step title="Saldo Suficiente">
    Asegúrate de que tu wallet tenga suficiente saldo 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 tu transacción es un **swap** o un **bridge** basándose en tu selección de activos:

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

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

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

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

<Tip>
  No necesitas especificar si es un swap o bridge—la API lo maneja automáticamente basándose en el `fromAssetId` y `toAssetId` que proporciones.
</Tip>

## Activos y Cadenas Soportados

La API de Swap soporta las principales stablecoins en las cadenas soportadas por Blockradar:

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

<Warning>
  La disponibilidad de activos varía según la cadena. Siempre usa la [API Obtener Activos](/es/api-reference/miscellaneous/get-assets) para obtener la lista actual de activos soportados y sus valores de `assetId` para tus cadenas objetivo.
</Warning>

<Note>
  Consulta [Integraciones](/es/essentials/integrations) para la lista completa de redes y stablecoins soportadas.
</Note>

## Master Wallet vs Dirección Hija

La API de Swap está disponible en dos niveles:

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

  <Card title="Dirección Hija" icon="address-card">
    Ejecuta swaps desde direcciones hijas individuales. Perfecto para operaciones específicas de usuario.
  </Card>
</CardGroup>

### Endpoints

| Operación          | Master Wallet                               | Dirección Hija                                                    |
| ------------------ | ------------------------------------------- | ----------------------------------------------------------------- |
| 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

Siempre obtén una cotización antes de ejecutar un swap para mostrar a los usuarios el resultado esperado.

### Parámetros de Solicitud

| Parámetro          | Tipo   | Requerido | Descripción                                                                    |
| ------------------ | ------ | --------- | ------------------------------------------------------------------------------ |
| `fromAssetId`      | string | Sí        | El ID del activo desde el cual intercambiar                                    |
| `toAssetId`        | string | Sí        | El ID del activo al cual intercambiar                                          |
| `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('Cotización:', quote.data);
  ```
</CodeGroup>

### Respuesta de 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
  }
}
```

### Entendiendo los Campos de Cotización

| Campo                  | Descripción                                              |
| ---------------------- | -------------------------------------------------------- |
| `amount`               | Monto estimado que recibirás después del swap            |
| `minAmount`            | Monto mínimo garantizado (considerando el deslizamiento) |
| `rate`                 | Tasa de cambio efectiva (montoDestino / montoOrigen)     |
| `impact`               | Porcentaje de impacto en el precio                       |
| `slippage`             | Porcentaje máximo permitido de movimiento de precio      |
| `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>
  Siempre muestra 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 confirma la cotización, ejecuta el swap.

### Parámetros de Solicitud

| Parámetro          | Tipo   | Requerido | Descripción                                                                    |
| ------------------ | ------ | --------- | ------------------------------------------------------------------------------ |
| `fromAssetId`      | string | Sí        | El ID del activo desde el cual intercambiar                                    |
| `toAssetId`        | string | Sí        | El ID del activo al cual intercambiar                                          |
| `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        | Tu ID de seguimiento interno                                                   |
| `metadata`         | object | No        | Datos personalizados pasados a través de 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 iniciado:', swap.data);
  ```
</CodeGroup>

### Respuesta de 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`. Escucha el webhook `swap.success` o `swap.failed` para confirmar la finalización.
</Warning>

## Tipos de Orden

Elige el tipo de orden correcto según tu caso de uso:

| Tipo de Orden | Descripción                       | Mejor Para                        |
| ------------- | --------------------------------- | --------------------------------- |
| `FASTEST`     | Prioriza velocidad sobre costo    | Transacciones sensibles al tiempo |
| `CHEAPEST`    | Minimiza comisiones               | Operaciones sensibles al costo    |
| `RECOMMENDED` | Enfoque equilibrado (por defecto) | La mayoría de casos de uso        |
| `NO_SLIPPAGE` | Monto exacto o falla              | Requisitos de monto preciso       |

## Eventos de Webhook

Monitorea la finalización del swap a través de webhooks:

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

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

Aquí hay una implementación completa mostrando el flujo cotización → confirmar → ejecutar:

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

  // Paso 1: Obtener cotización
  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());

  // Paso 2: Mostrar cotización al usuario
  console.log(`Recibirás: ${quote.data.amount}`);
  console.log(`Monto mínimo: ${quote.data.minAmount}`);
  console.log(`Comisión de red: $${quote.data.networkFeeInUSD}`);
  console.log(`Tiempo estimado: ${quote.data.estimatedArrivalTime}s`);

  // Paso 3: Ejecutar swap (después de confirmación del usuario)
  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 iniciado:', swap.data.id);
  console.log('Estado:', swap.data.status);

  // Paso 4: Escuchar webhook para confirmar finalización
  return swap.data;
}

// Uso
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="ID de Activo 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 Muy Bajo">
    ```json theme={null}
    {
      "message": "Amount below minimum swap threshold",
      "statusCode": 400,
      "error": "AMOUNT_TOO_LOW",
      "data": {
        "minimum": "10",
        "provided": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Deslizamiento 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>

## Mejores Prácticas

### Experiencia de Usuario

* **Siempre muestra cotizaciones**: Muestra monto, comisiones y tiempo estimado antes de ejecutar
* **Maneja el deslizamiento**: Informa a los usuarios sobre posibles variaciones de precio
* **Muestra el progreso**: Usa webhooks para actualizar a los usuarios sobre el estado del swap

### Seguridad

* **Valida montos**: Asegúrate de que los montos de swap estén dentro de rangos aceptables
* **Usa referencias**: Rastrea swaps con IDs de referencia únicos
* **Monitorea webhooks**: Siempre verifica la finalización del swap a través de webhooks

### Rendimiento

* **Cachea IDs de activos**: Almacena IDs de activos localmente para evitar búsquedas repetidas
* **Usa tipos de orden apropiados**: Elige `FASTEST` para tiempo sensible, `CHEAPEST` para costo sensible
* **Implementa reintentos**: Maneja fallas transitorias con retroceso exponencial

## Referencia de API

| Endpoint                                                                            | Descripción                                     |
| ----------------------------------------------------------------------------------- | ----------------------------------------------- |
| [Master Wallet Obtener Cotización](/es/api-reference/swap/master-wallet-get-quote)  | Obtener cotización de swap desde master wallet  |
| [Master Wallet Ejecutar](/es/api-reference/swap/master-wallet-execute)              | Ejecutar swap desde master wallet               |
| [Dirección Hija Obtener Cotización](/es/api-reference/swap/child-address-get-quote) | Obtener cotización de swap desde dirección hija |
| [Dirección Hija Ejecutar](/es/api-reference/swap/child-address-execute)             | Ejecutar swap desde dirección hija              |

## Soporte

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

<Note>
  La API de Swap proporciona una interfaz unificada tanto para swaps en la misma cadena como para bridges entre cadenas. Comienza con pequeñas cantidades de prueba en testnets antes de pasar a producción.
</Note>