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

> Aceite depósitos de stablecoins via endereços dedicados com varredura automática e notificações por webhook

<Note>
  Em resumo<br />
  A Blockradar permite que você aceite depósitos de stablecoins gerando endereços blockchain dedicados para cada cliente. Os depósitos são detectados automaticamente, disparam notificações por webhook e podem ser varridos para sua carteira principal — dando a você controle total sobre como os fundos fluem pela sua plataforma.
</Note>

## Pré-requisitos

<Steps>
  <Step title="Chave API">
    Obtenha sua chave API no [Painel da Blockradar](https://dashboard.blockradar.co). Navegue até **Developers** para gerar uma.
  </Step>

  <Step title="Carteira Principal">
    Crie uma carteira através do painel ou API. Você precisará do `walletId` para todas as operações de depósito.
  </Step>

  <Step title="Ativos Habilitados">
    Habilite as stablecoins que deseja aceitar na sua carteira. Sua carteira só detecta depósitos de ativos que você adicionou explicitamente — consulte [Gestão de Ativos](/pt/use-cases/asset-management).
  </Step>

  <Step title="URL de Webhook">
    Configure um endpoint de webhook no seu painel em **Developers → Webhooks** para receber notificações de depósitos em tempo real.
  </Step>
</Steps>

## Como Funciona

O fluxo de depósitos da Blockradar é construído em torno de um princípio simples: cada cliente recebe seu próprio endereço, e cada depósito é rastreado automaticamente.

<CardGroup cols={2}>
  <Card title="Gerar Endereços" icon="address-card">
    Crie um endereço blockchain único para cada cliente ou sessão de pagamento. Depósitos nesse endereço são atribuídos ao cliente automaticamente.
  </Card>

  <Card title="Detectar Depósitos" icon="bell">
    A Blockradar monitora todos os endereços gerados e dispara um webhook no momento em que um depósito chega — sem necessidade de polling.
  </Card>

  <Card title="Varredura Automática" icon="broom">
    Os depósitos são consolidados automaticamente na sua carteira principal, mantendo os endereços dos clientes limpos e sua tesouraria centralizada.
  </Card>

  <Card title="Consultar Saldos" icon="scale-balanced">
    Consulte saldos no nível da carteira ou endereço, para um único ativo ou todos os ativos de uma vez, com conversão para USD incluída.
  </Card>
</CardGroup>

## Controle Granular por Design

A maioria da infraestrutura blockchain trata carteiras como contêineres planos e uniformes. A Blockradar é diferente. Cada camada da hierarquia de carteiras — carteira principal, endereço filho e ativo individual — é configurável de forma independente, para que as fintechs possam adaptar a experiência de depósito às necessidades exatas do seu produto.

Isso significa que você pode:

* **Aceitar diferentes stablecoins por carteira** — habilite USDC em uma carteira e USDT em outra, ou ambas na mesma carteira. Você decide o que cada carteira monitora.
* **Configurar o comportamento de varredura por endereço** — varra automaticamente os depósitos para a carteira principal por padrão, mas desative para endereços específicos onde você quer que os fundos permaneçam.
* **Anexar metadados a cada endereço** — marque endereços com seus próprios IDs de usuário, tokens de sessão ou referências internas para que os depósitos se mapeiem diretamente ao seu sistema.
* **Ativar ou desativar endereços sob demanda** — pause um endereço sem excluí-lo, e reative quando necessário.

Essa granularidade importa quando você está construindo produtos como carteiras multi-moeda, escrow de marketplace ou fluxos de depósito por usuário — onde um modelo de carteira rígido forçaria soluções alternativas que a Blockradar lida nativamente.

***

## Passo 1: Habilitar Ativos na Sua Carteira

Antes de poder aceitar depósitos, sua carteira precisa saber quais stablecoins monitorar. Obtenha os ativos disponíveis com o endpoint [Get Assets](/en/api-reference/miscellaneous/get-assets) e depois adicione os que desejar.

<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('Ativo habilitado:', asset.data.asset.symbol);
  ```
</CodeGroup>

Uma vez adicionado, a Blockradar começa imediatamente a monitorar sua carteira e todos os seus endereços para depósitos desse token.

<Tip>
  Use [Get Wallet Assets](/en/api-reference/asset/get-wallet-assets) para obter os IDs de ativos específicos da carteira. Esses são os IDs que você usará em consultas de saldo e outras chamadas de API — eles são diferentes dos IDs de ativos globais.
</Tip>

## Passo 2: Gerar um Endereço de Cliente

Crie um endereço dedicado para cada cliente ou sessão de depósito. Cada depósito neste endereço é automaticamente atribuído ao 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('Endereço de depósito:', address.data.address);
  ```
</CodeGroup>

### Resposta

```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 Endereço

| Parâmetro               | Tipo    | Obrigatório | Descrição                                                                                        |
| ----------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `name`                  | string  | Não         | Rótulo legível para o endereço                                                                   |
| `metadata`              | object  | Não         | Pares chave-valor personalizados mapeados ao seu sistema interno                                 |
| `disableAutoSweep`      | boolean | Não         | Defina `true` para manter os depósitos no endereço em vez de varrê-los para a carteira principal |
| `enableGaslessWithdraw` | boolean | Não         | Habilita saques sem gas deste endereço                                                           |

Compartilhe o `address` gerado com seu cliente. Quando eles enviarem stablecoins para ele, a Blockradar detecta o depósito e dispara um webhook.

## Passo 3: Escutar Depósitos

Configure seu endpoint de webhook para receber notificações em tempo real quando depósitos chegarem.

### Eventos de Webhook

| Evento                  | Descrição                                                        |
| ----------------------- | ---------------------------------------------------------------- |
| `deposit.success`       | Um depósito foi confirmado on-chain em um endereço de cliente    |
| `deposit.swept.success` | O depósito foi varrido automaticamente para a carteira principal |

### Payload do 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>
  Os `metadata` que você anexou ao gerar o endereço são incluídos em cada webhook para esse endereço, para que você possa mapear depósitos de volta aos seus usuários sem uma consulta adicional.
</Info>

***

## Consultar Saldos

Consulte saldos em qualquer nível da hierarquia — carteira principal ou endereço individual, um único ativo ou todos os ativos.

### Saldo de Um Único Ativo (Carteira)

<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 os Saldos de Ativos (Endereço)

<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

| Escopo             | Único Ativo                                                                  | Todos os Ativos                                             |
| ------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Carteira Principal | `GET /v1/wallets/{walletId}/balance?assetId={assetId}`                       | `GET /v1/wallets/{walletId}/balances`                       |
| Endereço Filho     | `GET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}` | `GET /v1/wallets/{walletId}/addresses/{addressId}/balances` |

***

## Gestão de Endereços

### Listar Todos os Endereços

Obtenha todos os endereços de uma carteira, com analíticos de contagem de ativos vs. inativos.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses
```

### Obter um Endereço Específico

Recupere todos os detalhes de um endereço, incluindo sua configuração e metadados.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses/{addressId}
```

### Atualizar um Endereço

Modifique o nome, metadados, status ativo ou configuração de varredura de um endereço.

<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 — atualizado",
      "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 — atualizado',
        metadata: {
          userId: 'user_12345',
          plan: 'enterprise'
        },
        disableAutoSweep: true
      })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### Desativar um Endereço

Defina `isActive` como `false` para parar de monitorar um endereço. O endereço e seu histórico são preservados — você pode reativá-lo a qualquer 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 })
  }
);
```

***

## Varredura Automática

Por padrão, depósitos em endereços filhos são automaticamente varridos para a carteira principal. Isso mantém os endereços dos clientes limpos e consolida fundos para gestão de tesouraria ou pagamentos.

Você pode controlar isso no nível do endereço:

| Configuração                                 | Comportamento                                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------- |
| Varredura automática **habilitada** (padrão) | Depósitos são automaticamente movidos para a carteira principal após confirmação |
| Varredura automática **desabilitada**        | Depósitos permanecem no endereço filho até serem varridos manualmente ou sacados |

### Varredura Manual

Se a varredura automática estiver desabilitada, você pode acionar uma varredura sob demanda:

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

```json theme={null}
{
  "forceSweep": true
}
```

### Buscador de Depósitos

Se um depósito não aparecer (ex.: webhook perdido), use o buscador de depósitos para re-escanear a blockchain:

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

```json theme={null}
{
  "transactionHash": "0xabc123..."
}
```

***

## Exemplo de Fluxo Completo

Aqui está uma implementação completa: habilitar um ativo, gerar um endereço de cliente e lidar com o 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
  };

  // Passo 1: Gerar um endereço dedicado para o cliente
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `Usuário ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Compartilhe este endereço com o cliente:', depositAddress);

  return depositAddress;
}

// Handler de webhook (exemplo com 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 recebido: ${amount} ${symbol} do usuário ${userId}`);

    // Creditar a conta do usuário no seu sistema
    creditUserAccount(userId, amount, symbol);
  }

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

  res.sendStatus(200);
});
```

***

## Melhores Práticas

### Gestão de Endereços

* **Um endereço por cliente** — gere um endereço único para cada usuário ou sessão de pagamento para simplificar a atribuição
* **Use metadados** — anexe seus IDs de usuário internos e referências para que os payloads de webhook se mapeiem diretamente ao seu sistema
* **Desative, não exclua** — defina `isActive: false` em endereços que você não precisa mais, preservando o histórico

### Segurança

* **Valide webhooks** — verifique que as solicitações de webhook recebidas originam-se da Blockradar
* **Habilite verificação AML** — a Blockradar pode verificar endereços de depósito automaticamente (consulte [Verificação AML](/pt/use-cases/aml-screening))
* **Monitore os logs de webhook** — use `GET /v1/wallets/{walletId}/webhooks` para depurar entregas falhas

### Operações

* **Habilite apenas os ativos que precisa** — uma lista de ativos focada reduz o ruído de webhooks e mantém as consultas de saldo rápidas
* **Teste primeiro na testnet** — gere endereços, simule depósitos e verifique seu handler de webhook antes de ir para a mainnet
* **Use o buscador de depósitos** — se um cliente reportar um depósito que você não recebeu, re-escaneie a blockchain antes de investigar mais

***

## Referência API

### Carteira

| Endpoint                                                       | Descrição                                              |
| -------------------------------------------------------------- | ------------------------------------------------------ |
| [Get Wallet](/en/api-reference/wallet/get-wallet)              | Obter detalhes e configuração da carteira              |
| [Get Balance](/en/api-reference/wallet/get-balance)            | Consultar saldo de um ativo na carteira principal      |
| [Get Balances](/en/api-reference/wallet/get-balances)          | Consultar todos os saldos da carteira principal        |
| [Trigger Sweep](/en/api-reference/wallet/trigger-sweep-assets) | Varrer depósitos manualmente para a carteira principal |
| [Deposit Finder](/en/api-reference/wallet/deposit-finder)      | Re-escanear blockchain para depósitos ausentes         |
| [Webhook Logs](/en/api-reference/wallet/webhooks-logs)         | Ver histórico de entrega de webhooks                   |

### Endereços

| Endpoint                                                         | Descrição                                             |
| ---------------------------------------------------------------- | ----------------------------------------------------- |
| [Generate Address](/en/api-reference/addresses/generate-address) | Criar um novo endereço de depósito de cliente         |
| [Get Addresses](/en/api-reference/addresses/get-addresses)       | Listar todos os endereços de uma carteira             |
| [Get Address](/en/api-reference/addresses/get-address)           | Obter detalhes de um endereço específico              |
| [Update Address](/en/api-reference/addresses/update-address)     | Atualizar nome, metadados ou configuração de endereço |
| [Get Balance](/en/api-reference/addresses/get-balance)           | Consultar saldo de um ativo em um endereço            |
| [Get Balances](/en/api-reference/addresses/get-balances)         | Consultar todos os saldos de um endereço              |
| [Get Transactions](/en/api-reference/addresses/get-transactions) | Ver histórico de depósitos de um endereço             |

### Gestão de Ativos

| Endpoint                                                         | Descrição                                    |
| ---------------------------------------------------------------- | -------------------------------------------- |
| [Get Wallet Assets](/en/api-reference/asset/get-wallet-assets)   | Listar ativos habilitados em uma carteira    |
| [Add Asset](/en/api-reference/asset/add-asset-to-wallet)         | Habilitar uma nova stablecoin para depósitos |
| [Remove Asset](/en/api-reference/asset/remove-asset-from-wallet) | Parar de monitorar uma stablecoin            |
| [Update Asset](/en/api-reference/asset/update-wallet-asset)      | Atualizar configuração no nível do ativo     |