> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.
# De 0 a Integración
> Ve de cero a una integración en vivo de stablecoin en menos de 2 horas.
Esta guía te lleva por todo lo que necesitas para aceptar depósitos de stablecoin usando Blockradar, desde la configuración de la cuenta hasta el manejo de tu primer evento de webhook. Puedes integrar y lanzar en vivo con un solo desarrollador en menos de 2 horas.
Sigue la guía y construye mientras lees. Al final tendrás un flujo de pago en stablecoin funcionando.
## Qué vas a construir
Al final de esta guía tendrás:
* Una cuenta de Blockradar y una billetera principal en testnet
* Direcciones secundarias generadas y vinculadas a tus usuarios
* Un manejador de webhooks recibiendo eventos de depósito en tiempo real
* Un patrón para actualizar saldos de usuarios después de un depósito
***
## Paso 1: Crea tu cuenta
Visita [dashboard.blockradar.co/signup](https://dashboard.blockradar.co/signup) y completa el proceso de incorporación. Toma menos de 60 segundos.
En la esquina superior derecha del dashboard verás un interruptor de **Modo Live**. Está desactivado por defecto, lo que significa que cada acción se ejecuta en **testnet**, un entorno seguro donde no hay fondos reales. Déjalo desactivado mientras sigues esta guía.
***
## Paso 2: Crea una billetera principal
### ¿Qué es una billetera principal?
La billetera principal es la base de tu infraestructura de stablecoin. Piensa en ella como tu tesorería — controla todas las direcciones secundarias que creas para tus usuarios. Cada billetera principal está vinculada a una blockchain específica, así que si quieres soportar depósitos en Ethereum, Base y BNB Chain, crearás una billetera principal separada para cada una.
### Crea tu primera billetera
Desde el dashboard, haz clic en **Crear Billetera Principal**.
Elige **Base Sepolia (Testnet)** para seguir esta guía. Puedes crear billeteras en otras cadenas después.
Dale un nombre como `base-testnet` y haz clic en **Crear**.
Ahora tienes una billetera principal. Aquí es donde se generarán todas las direcciones secundarias de tus usuarios.
***
## Paso 3: Genera direcciones para tus usuarios
### ¿Qué son las direcciones secundarias?
Cuando un usuario se incorpora a tu app y necesita recibir stablecoins, necesita una dirección de billetera — como un número de cuenta bancaria, pero en la blockchain. En Blockradar, estas se llaman **direcciones secundarias**. Se generan bajo tu billetera principal y heredan su configuración de red.
Las direcciones generadas en cualquier cadena compatible con EVM (Base, Ethereum, BNB Chain, etc.) funcionan en todas las cadenas EVM. Una dirección cubre todas tus redes EVM.
### Genera una dirección mediante API
Llama a este endpoint cuando un usuario se registre en tu plataforma:
```bash theme={null}
curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
-H "x-api-key: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Billetera Cliente",
"disableAutoSweep": false,
"enableGaslessWithdraw": true,
"metadata": {
"user_id": 1234,
"email": "usuario@ejemplo.com"
}
}'
```
```javascript theme={null}
const options = {
method: "POST",
headers: {
"x-api-key": "",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Billetera Cliente",
disableAutoSweep: false,
enableGaslessWithdraw: true,
metadata: { user_id: 1234, email: "usuario@ejemplo.com" },
}),
};
fetch("https://api.blockradar.co/v1/wallets/{walletId}/addresses", options)
.then((res) => res.json())
.then(console.log);
```
### El campo metadata
El objeto `metadata` es una de las partes más importantes de esta solicitud. Todo lo que adjuntes aquí se incluirá en cada webhook que Blockradar envíe para esa dirección. Así es como tu backend identifica a qué usuario pertenece una transacción.
**Mejor práctica:** Siempre incluye un `user_id` en metadata para poder mapear cada depósito directamente a un usuario en tu base de datos.
***
## Paso 4: Configura el barrido automático y las transacciones sin gas
### Barrido automático
Cuando el barrido automático está habilitado (`disableAutoSweep: false`), los fondos depositados en una dirección secundaria se consolidan automáticamente en tu billetera principal. Esto simplifica la gestión de tesorería.
Para que el barrido automático funcione, tu billetera principal debe tener tokens nativos para cubrir las tarifas de gas.
**Faucets de testnet para tokens de gas:**
| Red | Token | Faucet |
| ---------------- | ----- | ---------------------------------------------------------------------------------------- |
| Base Sepolia | ETH | [alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia) |
| Ethereum Sepolia | ETH | [alchemy.com/faucets/ethereum-sepolia](https://www.alchemy.com/faucets/ethereum-sepolia) |
| BNB Testnet | BNB | [bnbchain.org/en/testnet-faucet](https://www.bnbchain.org/en/testnet-faucet) |
| Polygon Testnet | MATIC | [faucet.polygon.technology](https://faucet.polygon.technology/) |
| Tron Testnet | TRX | [nileex.io](https://nileex.io/join/getJoinPage) |
| Solana Devnet | SOL | [faucet.solana.com](https://faucet.solana.com/) |
### Transacciones sin gas
Cuando `enableGaslessWithdraw: true`, tus usuarios pueden enviar stablecoins desde su dirección sin tener tokens nativos. Tu billetera principal cubre el gas en su nombre.
***
## Paso 5: Configura los webhooks
Blockradar usa webhooks para notificar a tu backend cuando ocurren eventos en la blockchain — depósitos, retiros, barridos y más.
### Registra tu endpoint de webhook
1. Ve a tu billetera principal en el dashboard
2. Haz clic en **Desarrollador → Webhook**
3. Ingresa la URL de tu endpoint backend (debe ser un endpoint `POST`)
### Maneja webhooks en tu backend
```javascript theme={null}
app.post("/webhook-handler", (req, res) => {
const event = req.body;
console.log("Webhook recibido:", event);
res.sendStatus(200);
});
```
### Eventos de webhook comunes
| Evento | Descripción |
| ----------------------- | -------------------------------------------------- |
| `deposit.success` | Se recibió un depósito en una dirección secundaria |
| `deposit.swept.success` | Los fondos fueron barridos al billetera principal |
| `withdraw.success` | Un retiro fue enviado exitosamente |
| `swap.success` | Un intercambio fue ejecutado exitosamente |
***
## Paso 6: Maneja un evento de depósito
### Payload de ejemplo
```json theme={null}
{
"event": "deposit.success",
"data": {
"amountPaid": "10.0",
"currency": "USD",
"senderAddress": "0xabc...",
"recipientAddress": "0xdef...",
"metadata": {
"user_id": 1234
}
}
}
```
### Cómo procesarlo
Extrae `metadata.user_id` del payload para mapear el depósito a un usuario en tu base de datos.
Usa `data.amountPaid` para determinar cuánto fue depositado.
Acredita el saldo del usuario en tu base de datos.
***
## Qué has construido
Ahora tienes un flujo completo de pago en stablecoin:
* Una billetera principal en testnet
* Direcciones secundarias vinculadas a usuarios mediante metadata
* Barrido automático consolidando fondos en tu tesorería
* Transacciones sin gas eliminando fricción para tus usuarios
* Un manejador de webhooks actualizando saldos en tiempo real
## A dónde ir después
Envía stablecoins a tus usuarios o socios programáticamente.
Verifica direcciones antes de enviar o recibir fondos.
Permite a los usuarios intercambiar entre stablecoins con una sola llamada API.
Activa el Modo Live en el dashboard y empieza a aceptar fondos reales.