Swap y Bridge - Blockradar

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 desde el dashboard (consulte Crear una Billetera Principal). 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 de origen cuando `amountSide` es `source`, o el monto de destino cuando `amountSide` es `target`
`amountSide`	string	No	`source` o `target`. Por defecto es `source`. Usa `target` para cotizar o ejecutar un monto exacto de destino
`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)
`recipientRouting`	object	No	Solo para destinos Stellar: `{ type: "none" }` o `{ type: "memo_id", value: "<numeric string>" }`. Omítalo para destinos EVM, Solana y Tron.

Usa amountSide: "source" cuando el usuario ingresa cuánto quiere gastar. Usa amountSide: "target" cuando el usuario ingresa cuánto quiere recibir y necesitas que Blockradar resuelva el monto de origen requerido.

Enrutamiento de destinatarios Stellar

recipientRouting solo se admite cuando la cadena de destino es Stellar. Es un contrato de enrutamiento genérico compartido por todos los endpoints de cotización y ejecución de esta guía. Las solicitudes existentes para EVM, Solana y Tron no se ven afectadas y no cambian: no deben enviar recipientRouting; las solicitudes que lo incluyen se rechazan. recipientAddress sigue siendo una cadena opcional; no la envíe como objeto. No envíe un campo de memo de destinatario separado.

Reglas para destinos Stellar

Destinatario muxed M...: omita recipientRouting. El ID de enrutamiento está incorporado en la dirección muxed, y enviar datos de enrutamiento se rechaza.
Destinatario base G... con ID de enrutamiento: envíe { type: "memo_id", value: "123" }. value debe ser una cadena numérica no vacía entre 0 y 18446744073709551615. Blockradar normaliza la dirección a M... antes de solicitar la cotización o la ejecución.
Destinatario base G... sin ID de enrutamiento: envíe { type: "none" } y no incluya value. Un destinatario G... sin recipientRouting se rechaza. La cuenta base de destino debe tener una trustline de Stellar USDC antes de la cotización o la ejecución.
Wallet Stellar predeterminada de Blockradar: envíe explícitamente { type: "none" } en recipientRouting.

Ejemplos de solicitud

Todos los ejemplos usan la misma estructura de cuerpo en cada uno de estos endpoints:

POST /v1/wallets/{walletId}/swaps/quote
POST /v1/wallets/{walletId}/swaps/execute
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute

Non-Stellar destination — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdt_bsc_mainnet",
  "amount": "100",
  "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
}

Stellar G... without a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "none"
  }
}

Stellar G... with a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "memo_id",
    "value": "123"
  }
}

Stellar M... recipient — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "M..."
}

Default Blockradar Stellar wallet

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientRouting": {
    "type": "none"
  }
}

Migración desde campos específicos de Stellar

Campo anterior	Reemplazo
`recipientMemoId`	`recipientRouting: { type: "memo_id", value: "<numeric string>" }`
`stellarMemoNotRequired: true`	`recipientRouting: { type: "none" }`

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",
    "amountSide": "source",
    "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',
      amountSide: 'source',
      order: 'RECOMMENDED'
    })
  }
).then(r => r.json());

console.log('Quote:', quote.data);

Respuesta de la cotización

{
  "message": "Swap quote fetched successfully",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "fromAmount": "100",
    "toAmount": "99.45",
    "requestedAmount": "100",
    "amountSide": "source",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180,
    "recipientRouting": {
      "status": "none",
      "message": "No recipient routing value will be used. Confirm the destination accepts direct deposits without one."
    }
  }
}

Para un destino muxed, data.recipientRouting puede indicar en su lugar que el ID de enrutamiento está incorporado en la dirección de destino normalizada:

{
  "recipientRouting": {
    "status": "embedded",
    "message": "The recipient routing ID is embedded in the normalized destination address."
  }
}

data.recipientRouting es opcional y solo se devuelve en las respuestas de cotización. No espere encontrarlo en las respuestas de ejecución.

Cómo interpretar los campos de la cotización

Campo	Descripción
`amount`	Monto estimado de destino a recibir. En cotizaciones con monto de destino, este es el monto de destino solicitado
`fromAmount`	Monto del activo de origen requerido para la cotización
`toAmount`	Monto del activo de destino devuelto por la cotización
`requestedAmount`	Monto original enviado en la solicitud
`amountSide`	Indica si `requestedAmount` representa el monto de origen o el monto de destino
`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
`recipientRouting`	Metadatos opcionales de enrutamiento Stellar. `none` significa que no se usa ningún valor de enrutamiento; `embedded` significa que está incorporado en la dirección de destino normalizada.

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 de origen cuando `amountSide` es `source`, o el monto de destino cuando `amountSide` es `target`
`amountSide`	string	No	`source` o `target`. Por defecto es `source`. Usa `target` para cotizar o ejecutar un monto exacto de destino
`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)
`recipientRouting`	object	No	Solo para Stellar. Use el mismo valor que en la solicitud de cotización; omítalo para destinos EVM, Solana y Tron.
`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",
    "amountSide": "source",
    "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',
      amountSide: 'source',
      order: 'RECOMMENDED',
      reference: 'swap-order-12345',
      metadata: {
        userId: 'user_abc123',
        orderId: 'order_xyz789'
      }
    })
  }
).then(r => r.json());

console.log('Swap initiated:', swap.data);

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, amountSide = 'source') {
  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,
        amountSide,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.toAmount}`);
  console.log(`Required source amount: ${quote.data.fromAmount}`);
  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,
        amountSide,
        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.

​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

​Enrutamiento de destinatarios Stellar

​Reglas para destinos Stellar

​Ejemplos de solicitud

​Migración desde campos específicos de Stellar

​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

Enrutamiento de destinatarios Stellar

Reglas para destinos Stellar

Ejemplos de solicitud

Migración desde campos específicos de Stellar

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