> ## 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.

# Depositar Stablecoins

> Acepta depósitos de stablecoins a través de direcciones dedicadas con barrido automático y notificaciones por webhook

<Note>
  En resumen<br />
  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.
</Note>

## Requisitos Previos

<Steps>
  <Step title="Clave API">
    Obtén tu clave API desde el [Panel de Blockradar](https://dashboard.blockradar.co). Navega a **Developers** para generar una.
  </Step>

  <Step title="Billetera Principal">
    Crea una billetera a través del panel o la API. Necesitarás el `walletId` para todas las operaciones de depósito.
  </Step>

  <Step title="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](/es/use-cases/asset-management).
  </Step>

  <Step title="URL de Webhook">
    Configura un endpoint de webhook en tu panel en **Developers → Webhooks** para recibir notificaciones de depósitos en tiempo real.
  </Step>
</Steps>

## 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.

<CardGroup cols={2}>
  <Card title="Generar Direcciones" icon="address-card">
    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.
  </Card>

  <Card title="Detectar Depósitos" icon="bell">
    Blockradar monitorea todas las direcciones generadas y envía un webhook en el momento en que llega un depósito — sin necesidad de polling.
  </Card>

  <Card title="Auto-Barrido" icon="broom">
    Los depósitos se consolidan automáticamente en tu billetera principal, manteniendo las direcciones de clientes limpias y tu tesorería centralizada.
  </Card>

  <Card title="Consultar Saldos" icon="scale-balanced">
    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.
  </Card>
</CardGroup>

## 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](/en/api-reference/miscellaneous/get-assets) y luego agrega los que desees.

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const asset = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/assets`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId: 'global-asset-id-for-usdc'
      })
    }
  ).then(r => r.json());

  console.log('Activo habilitado:', asset.data.asset.symbol);
  ```
</CodeGroup>

Una vez agregado, Blockradar comienza inmediatamente a monitorear tu billetera y todas sus direcciones para depósitos de ese token.

<Tip>
  Usa [Get Wallet Assets](/en/api-reference/asset/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.
</Tip>

## 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.

<CodeGroup>
  ```bash Curl theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const address = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Cliente 12345',
        metadata: {
          userId: 'user_12345',
          plan: 'premium'
        }
      })
    }
  ).then(r => r.json());

  console.log('Dirección de depósito:', address.data.address);
  ```
</CodeGroup>

### Respuesta

```json theme={null}
{
  "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ámetro               | Tipo    | Requerido | Descripción                                                                                                 |
| ----------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `name`                  | string  | No        | Etiqueta legible para la dirección                                                                          |
| `metadata`              | object  | No        | Pares clave-valor personalizados mapeados a tu sistema interno                                              |
| `disableAutoSweep`      | boolean | No        | Establece `true` para mantener los depósitos en la dirección en lugar de barrerlos a la billetera principal |
| `enableGaslessWithdraw` | boolean | No        | Habilita 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

| Evento                  | Descripción                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `deposit.success`       | Un depósito ha sido confirmado on-chain en una dirección de cliente  |
| `deposit.swept.success` | El depósito ha sido barrido automáticamente a la billetera principal |

### Payload del Webhook

```json theme={null}
{
  "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"
  }
}
```

<Info>
  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.
</Info>

***

## 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)

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

  ```javascript JavaScript theme={null}
  const balance = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/balance?assetId=${assetId}`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  console.log(`Saldo: ${balance.data.balance} (≈$${balance.data.convertedBalance})`);
  ```
</CodeGroup>

### Todos los Saldos de Activos (Dirección)

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const balances = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/balances`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  balances.data.forEach(b => {
    console.log(`${b.asset.asset.symbol}: ${b.balance} (≈$${b.convertedBalance})`);
  });
  ```
</CodeGroup>

### Endpoints de Saldo

| Alcance             | Un Solo Activo                                                               | Todos los Activos                                           |
| ------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Billetera Principal | `GET /v1/wallets/{walletId}/balance?assetId={assetId}`                       | `GET /v1/wallets/{walletId}/balances`                       |
| Dirección Hija      | `GET /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.

```bash theme={null}
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.

```bash theme={null}
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.

<CodeGroup>
  ```bash Curl theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const updated = 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({
        name: 'Cliente 12345 — actualizado',
        metadata: {
          userId: 'user_12345',
          plan: 'enterprise'
        },
        disableAutoSweep: true
      })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### 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.

```javascript theme={null}
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ón                             | Comportamiento                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
| Auto-barrido **habilitado** (por defecto) | Los depósitos se mueven automáticamente a la billetera principal después de la confirmación |
| Auto-barrido **deshabilitado**            | Los 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:

```bash theme={null}
POST /v1/wallets/{walletId}/sweep/assets
```

```json theme={null}
{
  "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:

```bash theme={null}
POST /v1/wallets/{walletId}/rescan/blocks
```

```json theme={null}
{
  "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.

```javascript theme={null}
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](/es/use-cases/aml-screening))
* **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

| Endpoint                                                       | Descripción                                            |
| -------------------------------------------------------------- | ------------------------------------------------------ |
| [Get Wallet](/en/api-reference/wallet/get-wallet)              | Obtener detalles y configuración de la billetera       |
| [Get Balance](/en/api-reference/wallet/get-balance)            | Consultar saldo de un activo en la billetera principal |
| [Get Balances](/en/api-reference/wallet/get-balances)          | Consultar todos los saldos de la billetera principal   |
| [Trigger Sweep](/en/api-reference/wallet/trigger-sweep-assets) | Barrer depósitos manualmente a la billetera principal  |
| [Deposit Finder](/en/api-reference/wallet/deposit-finder)      | Re-escanear blockchain para depósitos faltantes        |
| [Webhook Logs](/en/api-reference/wallet/webhooks-logs)         | Ver historial de entrega de webhooks                   |

### Direcciones

| Endpoint                                                         | Descripción                                               |
| ---------------------------------------------------------------- | --------------------------------------------------------- |
| [Generate Address](/en/api-reference/addresses/generate-address) | Crear una nueva dirección de depósito de cliente          |
| [Get Addresses](/en/api-reference/addresses/get-addresses)       | Listar todas las direcciones de una billetera             |
| [Get Address](/en/api-reference/addresses/get-address)           | Obtener detalles de una dirección específica              |
| [Update Address](/en/api-reference/addresses/update-address)     | Actualizar nombre, metadatos o configuración de dirección |
| [Get Balance](/en/api-reference/addresses/get-balance)           | Consultar saldo de un activo en una dirección             |
| [Get Balances](/en/api-reference/addresses/get-balances)         | Consultar todos los saldos de una dirección               |
| [Get Transactions](/en/api-reference/addresses/get-transactions) | Ver historial de depósitos de una dirección               |

### Gestión de Activos

| Endpoint                                                         | Descripción                                   |
| ---------------------------------------------------------------- | --------------------------------------------- |
| [Get Wallet Assets](/en/api-reference/asset/get-wallet-assets)   | Listar activos habilitados en una billetera   |
| [Add Asset](/en/api-reference/asset/add-asset-to-wallet)         | Habilitar una nueva stablecoin para depósitos |
| [Remove Asset](/en/api-reference/asset/remove-asset-from-wallet) | Dejar de monitorear una stablecoin            |
| [Update Asset](/en/api-reference/asset/update-wallet-asset)      | Actualizar configuración a nivel de activo    |