Saltar al contenido principal
En resumen
Blockradar te permite aceptar depósitos de stablecoins generando direcciones blockchain dedicadas para cada cliente. Los depósitos se detectan automáticamente, activan notificaciones por webhook y pueden ser barridos a tu billetera principal — dándote control total sobre cómo fluyen los fondos en tu plataforma.

​
Requisitos Previos

1

Clave API

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

Billetera Principal

Crea una billetera a través del panel o la API. Necesitarás el walletId para todas las operaciones de depósito.
3

Activos Habilitados

Habilita las stablecoins que deseas aceptar en tu billetera. Tu billetera solo detecta depósitos de activos que hayas agregado explícitamente — consulta Gestión de Activos.
4

URL de Webhook

Configura un endpoint de webhook en tu panel en Developers → Webhooks para recibir notificaciones de depósitos en tiempo real.

​
Cómo Funciona

El flujo de depósitos de Blockradar se basa en un principio simple: cada cliente obtiene su propia dirección, y cada depósito se rastrea automáticamente.

Generar Direcciones

Crea una dirección blockchain única para cada cliente o sesión de pago. Los depósitos a esa dirección se atribuyen al cliente automáticamente.

Detectar Depósitos

Blockradar monitorea todas las direcciones generadas y envía un webhook en el momento en que llega un depósito — sin necesidad de polling.

Auto-Barrido

Los depósitos se consolidan automáticamente en tu billetera principal, manteniendo las direcciones de clientes limpias y tu tesorería centralizada.

Consultar Saldos

Consulta saldos a nivel de billetera o dirección, para un solo activo o todos los activos a la vez, con conversión a USD incluida.

​
Control Granular por Diseño

La mayoría de la infraestructura blockchain trata las billeteras como contenedores planos y uniformes. Blockradar es diferente. Cada capa de la jerarquía de billeteras — billetera principal, dirección hija y activo individual — es configurable de forma independiente, para que las fintechs puedan adaptar la experiencia de depósito a las necesidades exactas de su producto. Esto significa que puedes:
  • Aceptar diferentes stablecoins por billetera — habilita USDC en una billetera y USDT en otra, o ambas en la misma. Tú decides qué monitorea cada billetera.
  • Configurar el comportamiento de barrido por dirección — barre automáticamente los depósitos a la billetera principal por defecto, pero desactívalo para direcciones específicas donde quieras que los fondos permanezcan.
  • Adjuntar metadatos a cada dirección — etiqueta direcciones con tus propios IDs de usuario, tokens de sesión o referencias internas para que los depósitos se mapeen directamente a tu sistema.
  • Activar o desactivar direcciones bajo demanda — pausa una dirección sin eliminarla, y reactívala cuando sea necesario.
Esta granularidad importa cuando estás construyendo productos como billeteras multi-moneda, escrow de marketplace o flujos de depósito por usuario — donde un modelo de billetera rígido forzaría soluciones alternativas que Blockradar maneja de forma nativa.

​
Paso 1: Habilitar Activos en Tu Billetera

Antes de poder aceptar depósitos, tu billetera necesita saber qué stablecoins monitorear. Obtén los activos disponibles con el endpoint Get Assets y luego agrega los que desees. 
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "global-asset-id-for-usdc"
  }'
Una vez agregado, Blockradar comienza inmediatamente a monitorear tu billetera y todas sus direcciones para depósitos de ese token.
Usa Get Wallet Assets para obtener los IDs de activos específicos de la billetera. Estos son los IDs que usarás en consultas de saldo y otras llamadas API — son diferentes de los IDs de activos globales.

​
Paso 2: Generar una Dirección de Cliente

Crea una dirección dedicada para cada cliente o sesión de depósito. Cada depósito a esta dirección se atribuye automáticamente al cliente. 
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Cliente 12345",
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    }
  }'

​
Respuesta

{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Cliente 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Parámetros de Dirección

ParámetroTipoRequeridoDescripción
namestringNoEtiqueta legible para la dirección
metadataobjectNoPares clave-valor personalizados mapeados a tu sistema interno
disableAutoSweepbooleanNoEstablece true para mantener los depósitos en la dirección en lugar de barrerlos a la billetera principal
enableGaslessWithdrawbooleanNoHabilita retiros sin gas desde esta dirección
Comparte la address generada con tu cliente. Cuando envíen stablecoins a ella, Blockradar detecta el depósito y envía un webhook.

​
Paso 3: Escuchar Depósitos

Configura tu endpoint de webhook para recibir notificaciones en tiempo real cuando lleguen depósitos.

​
Eventos de Webhook

EventoDescripción
deposit.successUn depósito ha sido confirmado on-chain en una dirección de cliente
deposit.swept.successEl depósito ha sido barrido automáticamente a la billetera principal

​
Payload del Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Los metadata que adjuntaste al generar la dirección se incluyen en cada webhook para esa dirección, para que puedas mapear depósitos a tus usuarios sin una consulta adicional.

​
Consultar Saldos

Consulta saldos en cualquier nivel de la jerarquía — billetera principal o dirección individual, un solo activo o todos los activos.

​
Saldo de Un Solo Activo (Billetera)

curl --request GET \
  --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
  --header 'x-api-key: <api-key>'

​
Todos los Saldos de Activos (Dirección)

curl --request GET \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
  --header 'x-api-key: <api-key>'

​
Endpoints de Saldo

AlcanceUn Solo ActivoTodos los Activos
Billetera PrincipalGET /v1/wallets/{walletId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/balances
Dirección HijaGET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}GET /v1/wallets/{walletId}/addresses/{addressId}/balances

​
Gestión de Direcciones

​
Listar Todas las Direcciones

Obtén todas las direcciones de una billetera, con analíticas de conteo de activas vs. inactivas. 
GET /v1/wallets/{walletId}/addresses

​
Obtener una Dirección Específica

Recupera todos los detalles de una dirección, incluyendo su configuración y metadatos. 
GET /v1/wallets/{walletId}/addresses/{addressId}

​
Actualizar una Dirección

Modifica el nombre, metadatos, estado activo o configuración de barrido de una dirección. 
curl --request PATCH \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Cliente 12345 — actualizado",
    "metadata": {
      "userId": "user_12345",
      "plan": "enterprise"
    },
    "disableAutoSweep": true
  }'

​
Desactivar una Dirección

Establece isActive en false para dejar de monitorear una dirección. La dirección y su historial se conservan — puedes reactivarla en cualquier momento. 
await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);

​
Auto-Barrido

Por defecto, los depósitos a direcciones hijas se barren automáticamente a la billetera principal. Esto mantiene las direcciones de clientes limpias y consolida fondos para gestión de tesorería o pagos. Puedes controlar esto a nivel de dirección:
ConfiguraciónComportamiento
Auto-barrido habilitado (por defecto)Los depósitos se mueven automáticamente a la billetera principal después de la confirmación
Auto-barrido deshabilitadoLos depósitos permanecen en la dirección hija hasta que se barran manualmente o se retiren

​
Barrido Manual

Si el auto-barrido está deshabilitado, puedes activar un barrido bajo demanda: 
POST /v1/wallets/{walletId}/sweep/assets

{
  "forceSweep": true
}

​
Buscador de Depósitos

Si un depósito no aparece (ej., webhook perdido), usa el buscador de depósitos para re-escanear la blockchain: 
POST /v1/wallets/{walletId}/rescan/blocks

{
  "transactionHash": "0xabc123..."
}

​
Ejemplo de Flujo Completo

Aquí tienes una implementación completa: habilitar un activo, generar una dirección de cliente y manejar el webhook de depósito. 
async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Paso 1: Generar una dirección dedicada para el cliente
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `Usuario ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Comparte esta dirección con el cliente:', depositAddress);

  return depositAddress;
}

// Manejador de webhook (ejemplo con Express.js)
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Depósito recibido: ${amount} ${symbol} del usuario ${userId}`);

    // Acreditar la cuenta del usuario en tu sistema
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Depósito barrido a billetera principal: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});

​
Mejores Prácticas

​
Gestión de Direcciones

  • Una dirección por cliente — genera una dirección única para cada usuario o sesión de pago para simplificar la atribución
  • Usa metadatos — adjunta tus IDs de usuario internos y referencias para que los payloads de webhook se mapeen directamente a tu sistema
  • Desactiva, no elimines — establece isActive: false en direcciones que ya no necesites, preservando el historial

​
Seguridad

  • Valida webhooks — verifica que las solicitudes de webhook entrantes provengan de Blockradar
  • Habilita verificación AML — Blockradar puede verificar direcciones de depósito automáticamente (consulta Verificación AML)
  • Monitorea los logs de webhook — usa GET /v1/wallets/{walletId}/webhooks para depurar entregas fallidas

​
Operaciones

  • Habilita solo los activos que necesites — una lista de activos enfocada reduce el ruido de webhooks y mantiene las consultas de saldo rápidas
  • Prueba primero en testnet — genera direcciones, simula depósitos y verifica tu manejador de webhook antes de pasar a mainnet
  • Usa el buscador de depósitos — si un cliente reporta un depósito que no has recibido, re-escanea la blockchain antes de investigar más

​
Referencia API

​
Billetera

EndpointDescripción
Get WalletObtener detalles y configuración de la billetera
Get BalanceConsultar saldo de un activo en la billetera principal
Get BalancesConsultar todos los saldos de la billetera principal
Trigger SweepBarrer depósitos manualmente a la billetera principal
Deposit FinderRe-escanear blockchain para depósitos faltantes
Webhook LogsVer historial de entrega de webhooks

​
Direcciones

EndpointDescripción
Generate AddressCrear una nueva dirección de depósito de cliente
Get AddressesListar todas las direcciones de una billetera
Get AddressObtener detalles de una dirección específica
Update AddressActualizar nombre, metadatos o configuración de dirección
Get BalanceConsultar saldo de un activo en una dirección
Get BalancesConsultar todos los saldos de una dirección
Get TransactionsVer historial de depósitos de una dirección

​
Gestión de Activos

EndpointDescripción
Get Wallet AssetsListar activos habilitados en una billetera
Add AssetHabilitar una nueva stablecoin para depósitos
Remove AssetDejar de monitorear una stablecoin
Update AssetActualizar configuración a nivel de activo