Direcciones

En pocas palabras
Las direcciones dedicadas te permiten crear direcciones blockchain únicas para cada cliente. Estas direcciones pueden recibir stablecoins a través de múltiples cadenas compatibles con EVM, con depósitos barridos automáticamente a tu billetera principal.

Requisitos Previos

Antes de generar direcciones, asegúrate de tener:

Clave API

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

Billetera Principal Creada

Crea al menos una billetera principal a través de la API de Crear Billetera o el panel. Necesitarás el walletId para generar direcciones.

Billetera Financiada

Financia tu billetera principal con tokens nativos (ETH, BNB, MATIC, etc.) para cubrir las tarifas de gas de las operaciones de barrido automático.

Webhook Configurado

Configura tu URL de webhook en la billetera principal para recibir notificaciones de depósitos. Consulta Webhooks para detalles de configuración.

Cómo Funciona

Las Direcciones Dedicadas es una característica crucial en Blockradar que te permite crear direcciones únicas para tus clientes. Estas direcciones permiten a tus clientes depositar stablecoins en tu aplicación fintech sin problemas. Cuando creas una dirección dedicada para un cliente, pueden usar esa única dirección para depositar stablecoins en múltiples blockchains compatibles con EVM. Por ejemplo, si tienes billeteras principales de Ethereum, Binance Smart Chain, Polygon y Base creadas, cada dirección que generes a través de cualquiera de estas billeteras principales se puede usar para recibir stablecoins en cualquiera de las blockchains y activos compatibles. Esto garantiza que no tengas que preocuparte de que tu cliente envíe stablecoins a la blockchain incorrecta. Además, cuando se depositan stablecoins en una dirección particular, los activos se mueven automáticamente a la dirección de la billetera principal de la cadena.

Aparte de Tron y Solana, las direcciones generadas desde una billetera se pueden usar para depositar stablecoins en otras blockchains que tengan el parámetro de blockchain isEvmCompatible: true.

Parámetros de Dirección Explicados

Al crear o actualizar una dirección, puedes usar los siguientes parámetros opcionales para personalizar su comportamiento:

Parámetro	Tipo	Predeterminado	Descripción
`disableAutoSweep`	Boolean (Opcional)	`false`	Si se establece en `true`, el barrido automático de fondos desde esta dirección está deshabilitado.
`enableGaslessWithdraw`	Boolean (Opcional)	`false`	Si se establece en `true`, permite retiros sin que el usuario tenga que pagar tarifas de gas directamente.
`metadata`	Object (Opcional)	`null`	Metadatos personalizados que puedes adjuntar a la dirección para tu propia referencia o fines de seguimiento.
`name`	String (Opcional)	`null`	Un nombre legible para la dirección, útil para identificación en tu panel de control o registros.
`showPrivateKey`	Boolean (Opcional)	`false`	Si se establece en `true`, la clave privada para esta dirección se devolverá en la respuesta de la API. Usar con precaución.

Los parámetros disableAutoSweep, enableGaslessWithdraw y showPrivateKey anularán las configuraciones correspondientes en la configuración de la billetera principal para esta dirección específica. Esto permite un control granular a nivel de dirección, independientemente de la configuración predeterminada de la billetera.

Notas:

Todos estos parámetros son opcionales; solo necesitas incluir aquellos relevantes para tu caso de uso.
Habilitar showPrivateKey puede exponer información sensible. Solo usa esto en entornos seguros y confiables.
Ten cuidado con showPrivateKey, exponer claves privadas puede comprometer la seguridad.

Crear una Dirección Dedicada

Puedes generar una dirección dedicada para tu cliente usando el panel de control de Blockradar o la API, dependiendo de tu flujo de trabajo y necesidades de integración.

1. Usando el Panel de Control

El panel de control de Blockradar proporciona una interfaz simple y fácil de usar para generar nuevas direcciones.

Esta captura de pantalla demuestra el proceso de generar una nueva dirección a través del panel de control de Blockradar. Este método es ideal para la creación manual de direcciones o para equipos que prefieren una interfaz gráfica.

2. Usando la API

Para la generación de direcciones programática o automatizada, puedes usar la API de Crear Dirección Dedicada. Esto es útil para integrar la creación de direcciones en tus propias aplicaciones o sistemas backend. Para crear una dirección dedicada para un cliente, envía una solicitud POST a nuestra API de Crear Dirección Dedicada.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "disableAutoSweep": "OPTIONAL_BOOLEAN",
  "enableGaslessWithdraw": "OPTIONAL_BOOLEAN",
  "metadata": "OPTIONAL_METADATA",
  "name": "OPTIONAL_ADDRESS_NAME",
  "showPrivateKey": "OPTIONAL_BOOLEAN"
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Respuesta

{
  "data": {
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "blockchain": {
      "createdAt": "2024-05-14T11:53:33.095Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "85ffc132-3972-4c9e-99a5-5cf0ccb688bf",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800081/crypto-assets/ethereum-eth-logo_idraq2.png",
      "name": "ethereum",
      "slug": "ethereum",
      "symbol": "eth",
      "tokenStandard": "ERC20",
      "updatedAt": "2024-06-14T22:32:11.983Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      },
      "disableAutoSweep": false,
      "enableGaslessWithdraw": false,
      "showPrivateKey": false
    },
    "createdAt": "2024-10-23T11:13:40.446Z",
    "derivationPath": "m/44'/60'/0'/0/87",
    "id": "0a69c48a-6c6f-422c-bd6a-70de3306a3ac",
    "isActive": true,
    "metadata": {
      "user_id": 1
    },
    "name": "Customer 1",
    "network": "testnet",
    "type": "INTERNAL",
    "updatedAt": "2024-10-23T11:13:40.446Z"
  },
  "message": "Address generated successfully",
  "statusCode": 200
}

Emisión e Indexación de Direcciones

Blockradar separa dos cosas que antes ocurrían juntas al crear una dirección:

Emitir (issue) una dirección es económico. Deriva una nueva dirección de tu master wallet y la almacena, de modo que puedes entregársela a un cliente de inmediato.
Indexar una dirección es la parte costosa. Coloca la dirección bajo monitoreo on-chain para que los depósitos se detecten en tiempo real, y la indexación es la base de la facturación.

Esto te permite emitir una dirección por cliente con anticipación y activar la indexación solo cuando un cliente muestra intención de depositar, de modo que solo pagas por las direcciones que realmente monitoreas.

Dos interruptores independientes

Cada dirección tiene dos ajustes que controlan su estado:

Ajuste	Valores	Controla
`isActive`	`true` / `false`	El interruptor principal de encendido/apagado. `false` desactiva la dirección por completo.
`indexingStatus`	`ACTIVE` / `INACTIVE`	El interruptor de monitoreo y facturación. `INACTIVE` significa inactiva: no se monitorea ni se factura.

Una dirección se monitorea on-chain y se cuenta para la facturación solo cuando ambos están activados: isActive: true e indexingStatus: ACTIVE.

Las direcciones existentes no se ven afectadas. indexingStatus toma el valor ACTIVE por defecto, por lo que cada dirección que ya creaste, y cada dirección que crees sin optar por lo contrario, se comporta exactamente igual que antes.

Emitir una dirección inactiva

Al generar una dirección, pasa enableIndexing: false para crear una dirección inactiva que no se monitorea ni se factura. Omite el campo o pasa true para el comportamiento por defecto (indexada de inmediato). Una dirección inactiva devuelve "indexingStatus": "INACTIVE" en la respuesta.

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": "Customer 123",
  "metadata": { "customerId": "123" },
  "enableIndexing": false
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"name":"Customer 123","metadata":{"customerId":"123"},"enableIndexing":false}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\": \"Customer 123\",\n  \"metadata\": { \"customerId\": \"123\" },\n  \"enableIndexing\": false\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Activar la indexación

Activa la indexación cuando el cliente muestre intención de depositar. Esto suscribe la dirección, inicia el monitoreo en tiempo real y la incluye en la facturación. La llamada no lleva cuerpo y es idempotente (no hace nada si la indexación ya está activada). El parámetro de ruta addressId acepta tanto el UUID de la dirección como la cadena de la dirección on-chain. La respuesta muestra "indexingStatus": "ACTIVE". Devuelve 400 si la dirección ha sido desactivada (isActive: false).

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/enable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Desactivar la indexación

Desactiva la indexación para clientes inactivos o que se dieron de baja, y así dejar de facturar direcciones que ya no monitoreas. Esto detiene el monitoreo y elimina la dirección de la facturación en el siguiente ciclo. La llamada no lleva cuerpo y es idempotente. Los fondos ya recibidos permanecen seguros on-chain, y puedes volver a activar la indexación más tarde sin costo adicional más allá de la facturación normal. La respuesta muestra "indexingStatus": "INACTIVE".

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

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>'}
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/indexing/disable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["x-api-key: <api-key>"],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Facturación

La facturación de direcciones es un conteo en vivo que se toma en cada renovación, no un cargo por dirección. En cada ciclo, Blockradar cuenta las direcciones que están activas e indexadas en mainnet y cobra por el uso que supera el límite de tu plan.

Estado de la dirección	Se cuenta para facturación	Monitoreada on-chain
Inactiva (`indexingStatus: INACTIVE`)	No — gratis	No
Indexada (`indexingStatus: ACTIVE`)	Sí	Sí
Desactivada a mitad de ciclo	Sale del conteo siguiente	No

Generar direcciones inactivas no factura nada, y desactivar la indexación libera ese cupo en el siguiente ciclo.

Mejores prácticas

Emite una dirección inactiva cuando se la asignes a un cliente. No cuesta nada.
Activa la indexación cuando el cliente muestre intención de depositar (KYC aprobado, checkout abierto, pantalla de depósito vista).
Activa siempre la indexación antes de compartir una dirección para un depósito real, para que el depósito se detecte en tiempo real.
Desactiva la indexación para clientes inactivos o que se dieron de baja, y vuelve a activarla más tarde cuando sea necesario.

Los depósitos realizados a una dirección inactiva no se detectan en tiempo real. Si un cliente deposita en una dirección antes de que la indexación esté activada, los fondos están seguros on-chain pero no se registran automáticamente. Activa la indexación y ejecuta el Buscador de Depósitos para recuperarlos. Activa siempre la indexación antes de compartir una dirección para evitar esto.

Lista Blanca de Direcciones

Esta característica te permite agregar una dirección externa a la lista blanca para ser monitoreada según los requisitos de la billetera. ¿Ya tienes billeteras emitidas por otro proveedor? Aún puedes conectarlas a Blockradar y monitorear depósitos sin cambiar tu configuración existente.

Parámetros del Cuerpo

Clave	Requerido	Tipo	Descripción
`name`	false	string	El nombre de la dirección.
`address`	true	string	La dirección de la billetera.
`metadata`	false	object	Metadatos adicionales para la dirección. Esto formará parte de cualquier transacción vinculada a esto.
`showPrivateKey`	false	boolean	Si deseas que la clave privada de la dirección forme parte de la respuesta.
`disableAutoSweep`	false	boolean	Deshabilita el barrido automático de activos enviados a la dirección en tu billetera principal.
`enableGaslessWithdraw`	false	boolean	Habilita transacciones sin gas desde esta dirección.
`privateKey`	false	string	La clave privada asociada con la dirección. Requerida para ejecutar acciones de forma segura.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "name": "Whitelisted Address",
  "metadata": {"purpose": "external_monitoring", "source": "manual"},
  "showPrivateKey": false,
  "disableAutoSweep": false,
  "enableGaslessWithdraw": true,
  "privateKey": "0x1234567890abcdef..."
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: '{"address":"ADDRESS_TO_WHITELIST","metadata":"OPTIONAL_METADATA","name":"OPTIONAL_ADDRESS_NAME"}'
};

fetch('https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blockradar.co/v1/wallets/{walletId}/addresses/whitelist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"address\": \"ADDRESS_TO_WHITELIST\",\n  \"metadata\": \"OPTIONAL_METADATA\",\n  \"name\": \"OPTIONAL_ADDRESS_NAME\"\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key": <api-key>
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Respuesta

{
  "data": {
    "address": "0x3375154fa32Cb434B044E73a2582C4D2E6518AE4",
    "blockchain": {
      "createdAt": "2024-05-27T08:31:14.966Z",
      "derivationPath": "m/44'/60'/0'/0",
      "id": "74733889-4ecd-403e-9840-94e87c043f24",
      "isActive": true,
      "isEvmCompatible": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800080/crypto-assets/Base_Network_Logo_vqyh7r.png",
      "name": "base",
      "slug": "base",
      "symbol": "eth",
      "tokenStandard": null,
      "updatedAt": "2024-10-27T07:52:16.115Z"
    },
    "configurations": {
      "aml": {
        "message": "Address is not sanctioned",
        "provider": "ofac",
        "status": "success"
      }
    },
    "createdAt": "2024-11-11T16:57:19.160Z",
    "derivationPath": null,
    "id": "b87901a2-45c1-4d2d-8ee7-205ef0c4ddf1",
    "isActive": true,
    "metadata": null,
    "name": "External address",
    "network": "testnet",
    "type": "EXTERNAL",
    "updatedAt": "2024-11-11T16:57:19.160Z"
  },
  "message": "Address whitelisted successfully",
  "statusCode": 200
}

Pruebas

Las direcciones generadas a través de una billetera principal de testnet solo pueden recibir activos en la testnet.

Aquí hay una lista de lugares donde puedes obtener activos de testnet para probar:

Ethereum - Obtén USDC de prueba aquí: Circle
Binance Smart Chain - Obtén USDT de prueba aquí: Binance
Polygon - Obtén USDC de prueba aquí: Circle
Base - Obtén USDC de prueba aquí: Circle
Tron - Obtén USDT de prueba aquí: Nileex
Solana - Obtén USDC de prueba aquí: Circle
Optimism - Obtén USDC de prueba aquí: Circle
Arbitrum - Obtén USDC de prueba aquí: Circle
Celo - Obtén USDC de prueba aquí: Circle

¡Feliz programación! 💚

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Requisitos Previos

Cómo Funciona

Parámetros de Dirección Explicados

Crear una Dirección Dedicada

1. Usando el Panel de Control

2. Usando la API

Respuesta

Emisión e Indexación de Direcciones

Dos interruptores independientes

Emitir una dirección inactiva

Activar la indexación

Desactivar la indexación

Facturación

Mejores prácticas

Lista Blanca de Direcciones

Parámetros del Cuerpo

Respuesta

Pruebas

​Requisitos Previos

​Cómo Funciona

​Parámetros de Dirección Explicados

​Crear una Dirección Dedicada

​1. Usando el Panel de Control

​2. Usando la API

​Respuesta

​Emisión e Indexación de Direcciones

​Dos interruptores independientes

​Emitir una dirección inactiva

​Activar la indexación

​Desactivar la indexación

​Facturación

​Mejores prácticas

​Lista Blanca de Direcciones

​Parámetros del Cuerpo

​Respuesta

​Pruebas

Requisitos Previos

Cómo Funciona

Parámetros de Dirección Explicados

Crear una Dirección Dedicada

1. Usando el Panel de Control

2. Usando la API

Respuesta

Emisión e Indexación de Direcciones

Dos interruptores independientes

Emitir una dirección inactiva

Activar la indexación

Desactivar la indexación

Facturación

Mejores prácticas

Lista Blanca de Direcciones

Parámetros del Cuerpo

Respuesta

Pruebas