Intercambio & Puente

En resumen
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.

Prerrequisitos

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

Clave API

Obtén tu clave API desde el Panel de Blockradar. Navega a Developers para generar una.

Wallet Creado

Crea un wallet a través de la API Crear Wallet o el panel. Necesitarás el walletId para las operaciones de swap.

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.

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.

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:

Swap

Intercambia diferentes activos en la misma blockchain.Ejemplo: USDC → USDT en Base

Bridge

Mueve activos entre diferentes blockchains.Ejemplo: USDC en BSC → USDC en Optimism

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

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

La disponibilidad de activos varía según la cadena. Siempre usa la API Obtener Activos para obtener la lista actual de activos soportados y sus valores de assetId para tus cadenas objetivo.

Consulta Integraciones para la lista completa de redes y stablecoins soportadas.

Master Wallet vs Dirección Hija

La API de Swap está disponible en dos niveles:

Master Wallet

Ejecuta swaps directamente desde tu master wallet. Ideal para operaciones de tesorería.

Dirección Hija

Ejecuta swaps desde direcciones hijas individuales. Perfecto para operaciones específicas de usuario.

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

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"
  }'

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

Respuesta de Cotización

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

Siempre muestra como mínimo: monto a recibir, tiempo estimado de llegada y comisiones antes de que el usuario confirme el swap.

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

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"
    }
  }'

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

Respuesta de Ejecución

{
  "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"
  }
}

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.

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

{
  "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:

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

Saldo Insuficiente

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

ID de Activo Inválido

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

Ruta de Swap No Disponible

{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

Monto Muy Bajo

{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

Deslizamiento Excedido

{
  "message": "Price moved beyond slippage tolerance",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

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	Obtener cotización de swap desde master wallet
Master Wallet Ejecutar	Ejecutar swap desde master wallet
Dirección Hija Obtener Cotización	Obtener cotización de swap desde dirección hija
Dirección Hija Ejecutar	Ejecutar swap desde dirección hija

Soporte

Email: [email protected]
Documentación: Referencia de API
Blog: Cómo Intercambiar o Puentear Activos con Blockradar

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.

Get Started

Wallets

Receive Payments

Send Payments

Convert & Manage

Compliance & Recovery

Integrations

Intercambio & Puente

Prerrequisitos

Cómo Funciona

Swap

Bridge

Activos y Cadenas Soportados

Master Wallet vs Dirección Hija

Master Wallet

Dirección Hija

Endpoints

Paso 1: Obtener una Cotización

Parámetros de Solicitud

Ejemplo de Cotización

Respuesta de Cotización

Entendiendo los Campos de Cotización

Paso 2: Ejecutar el Swap

Parámetros de Solicitud

Ejemplo de Ejecución

Respuesta de Ejecución

Tipos de Orden

Eventos de Webhook

Payload del Webhook

Ejemplo de Flujo Completo

Respuestas de Error

Mejores Prácticas

Experiencia de Usuario

Seguridad

Rendimiento

Referencia de API

Soporte

​Prerrequisitos

​Cómo Funciona

Swap

Bridge

​Activos y Cadenas Soportados

​Master Wallet vs Dirección Hija

Master Wallet

Dirección Hija

​Endpoints

​Paso 1: Obtener una Cotización

​Parámetros de Solicitud

​Ejemplo de Cotización

​Respuesta de Cotización

​Entendiendo los Campos de Cotización

​Paso 2: Ejecutar el Swap

​Parámetros de Solicitud

​Ejemplo de Ejecución

​Respuesta de Ejecución

​Tipos de Orden

​Eventos de Webhook

​Payload del Webhook

​Ejemplo de Flujo Completo

​Respuestas de Error

​Mejores Prácticas

​Experiencia de Usuario

​Seguridad

​Rendimiento

​Referencia de API

​Soporte

Prerrequisitos

Cómo Funciona

Activos y Cadenas Soportados

Master Wallet vs Dirección Hija

Endpoints

Paso 1: Obtener una Cotización

Parámetros de Solicitud

Ejemplo de Cotización

Respuesta de Cotización

Entendiendo los Campos de Cotización

Paso 2: Ejecutar el Swap

Parámetros de Solicitud

Ejemplo de Ejecución

Respuesta de Ejecución

Tipos de Orden

Eventos de Webhook

Payload del Webhook

Ejemplo de Flujo Completo

Respuestas de Error

Mejores Prácticas

Experiencia de Usuario

Seguridad

Rendimiento

Referencia de API

Soporte