Swap y Bridge

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

Requisitos previos

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

Clave de API

Obtenga su clave de API desde el Dashboard de Blockradar. Vaya a Developers para generar una.

Wallet creada

Cree una wallet a través de la API Create Wallet o desde el dashboard. Necesitará el walletId para las operaciones de swap.

IDs de activos

Obtenga el assetId de sus activos de origen y destino desde Assets en el dashboard o mediante la API Get Assets.

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.

Cómo funciona

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

Swap

Intercambie distintos activos en la misma blockchain.Ejemplo: USDC → USDT en Base

Bridge

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

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.

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

La disponibilidad de activos varía según la cadena. Utilice siempre la API Get Assets para obtener la lista actualizada de activos compatibles y sus valores de assetId en las cadenas de destino.

Consulte Integraciones para ver la lista completa de redes y stablecoins compatibles.

Master Wallet vs Child Address

La API Swap está disponible en dos niveles:

Master Wallet

Ejecute swaps directamente desde su master wallet. Ideal para operaciones de tesorería.

Child Address

Ejecute swaps desde child addresses individuales. Perfecto para operaciones específicas de cada usuario.

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

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

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

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

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 la 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. Escuche el webhook swap.success o swap.failed para confirmar la finalización.

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

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

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

Saldo insuficiente

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

Asset ID 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 demasiado bajo

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

Slippage superado

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

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	Obtener cotización de swap desde la master wallet
Master Wallet Execute	Ejecutar swap desde la master wallet
Child Address Get Quote	Obtener cotización de swap desde una child address
Child Address Execute	Ejecutar swap desde una child address

Soporte

Email: [email protected]
Documentación: Referencia de API
Blog: Cómo intercambiar o hacer bridge de activos con Blockradar

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.

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Requisitos previos

Cómo funciona

Swap

Bridge

Activos y cadenas compatibles

Master Wallet vs Child Address

Master Wallet

Child Address

Endpoints

Paso 1: Obtener una cotización

Parámetros de la solicitud

Ejemplo de cotización

Respuesta de la cotización

Cómo interpretar los campos de la cotización

Paso 2: Ejecutar el Swap

Parámetros de la solicitud

Ejemplo de ejecución

Respuesta de la ejecución

Tipos de orden

Eventos de Webhook

Carga útil del Webhook

Ejemplo de flujo completo

Respuestas de error

Buenas prácticas

Experiencia de usuario

Seguridad

Rendimiento

Referencia de API

Soporte

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Documentation Index

​Requisitos previos

​Cómo funciona

Swap

Bridge

​Activos y cadenas compatibles

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Paso 1: Obtener una cotización

​Parámetros de la solicitud

​Ejemplo de cotización

​Respuesta de la cotización

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

​Paso 2: Ejecutar el Swap

​Parámetros de la solicitud

​Ejemplo de ejecución

​Respuesta de la ejecución

​Tipos de orden

​Eventos de Webhook

​Carga útil del Webhook

​Ejemplo de flujo completo

​Respuestas de error

​Buenas prácticas

​Experiencia de usuario

​Seguridad

​Rendimiento

​Referencia de API

​Soporte

Requisitos previos

Cómo funciona

Activos y cadenas compatibles

Master Wallet vs Child Address

Endpoints

Paso 1: Obtener una cotización

Parámetros de la solicitud

Ejemplo de cotización

Respuesta de la cotización

Cómo interpretar los campos de la cotización

Paso 2: Ejecutar el Swap

Parámetros de la solicitud

Ejemplo de ejecución

Respuesta de la ejecución

Tipos de orden

Eventos de Webhook

Carga útil del Webhook

Ejemplo de flujo completo

Respuestas de error

Buenas prácticas

Experiencia de usuario

Seguridad

Rendimiento

Referencia de API

Soporte