Saltar al contenido principal
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:
1

Clave API

Obtén tu clave API desde el Panel de Blockradar. Navega a Configuración → Claves API para generar una.
2

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

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

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:
StablecoinDescripción
USDTTether USD
USDCUSD Coin
DAIDai Stablecoin
BUSDBinance USD
cNGNStablecoin Naira
EURCEuro Coin
IDRXStablecoin Indonesio
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ónMaster WalletDirección Hija
Obtener CotizaciónPOST /v1/wallets/{walletId}/swaps/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
EjecutarPOST /v1/wallets/{walletId}/swaps/executePOST /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ámetroTipoRequeridoDescripción
fromAssetIdstringEl ID del activo desde el cual intercambiar
toAssetIdstringEl ID del activo al cual intercambiar
amountstringEl monto a intercambiar
orderstringNoPreferencia de cotización: FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
recipientAddressstringNoDirecció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"
  }'

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

CampoDescripción
amountMonto estimado que recibirás después del swap
minAmountMonto mínimo garantizado (considerando el deslizamiento)
rateTasa de cambio efectiva (montoDestino / montoOrigen)
impactPorcentaje de impacto en el precio
slippagePorcentaje máximo permitido de movimiento de precio
networkFeeComisión de gas en unidades del token nativo
networkFeeInUSDComisión de gas convertida a USD
estimatedArrivalTimeTiempo 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ámetroTipoRequeridoDescripción
fromAssetIdstringEl ID del activo desde el cual intercambiar
toAssetIdstringEl ID del activo al cual intercambiar
amountstringEl monto a intercambiar
orderstringNoPreferencia de cotización: FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
recipientAddressstringNoDirección de wallet externa (para enviar a wallets que no son de Blockradar)
referencestringNoTu ID de seguimiento interno
metadataobjectNoDatos 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"
    }
  }'

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 OrdenDescripciónMejor Para
FASTESTPrioriza velocidad sobre costoTransacciones sensibles al tiempo
CHEAPESTMinimiza comisionesOperaciones sensibles al costo
RECOMMENDEDEnfoque equilibrado (por defecto)La mayoría de casos de uso
NO_SLIPPAGEMonto exacto o fallaRequisitos de monto preciso

Eventos de Webhook

Monitorea la finalización del swap a través de webhooks:
EventoDescripción
swap.successSwap completado exitosamente
swap.failedSwap 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

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}
{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}
{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}
{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}
{
  "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

EndpointDescripción
Master Wallet Obtener CotizaciónObtener cotización de swap desde master wallet
Master Wallet EjecutarEjecutar swap desde master wallet
Dirección Hija Obtener CotizaciónObtener cotización de swap desde dirección hija
Dirección Hija EjecutarEjecutar swap desde dirección hija

Soporte

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.