> ## 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 Integração

> Vá de zero a uma integração ativa de stablecoin em menos de 2 horas.

Este guia percorre tudo o que você precisa para aceitar depósitos de stablecoin usando o Blockradar, desde a configuração da conta até o tratamento do seu primeiro evento de webhook. Você pode integrar e lançar em produção com um único desenvolvedor em menos de 2 horas.

<Info>
  Siga e construa enquanto lê. Ao final você terá um fluxo de pagamento em stablecoin funcionando.
</Info>

## O que você vai construir

Ao final deste guia você terá:

* Uma conta Blockradar e uma carteira principal na testnet
* Endereços secundários gerados e vinculados aos seus usuários
* Um handler de webhooks recebendo eventos de depósito em tempo real
* Um padrão para atualizar saldos de usuários após um depósito

***

## Passo 1: Crie sua conta

<Steps>
  <Step title="Cadastre-se">
    Acesse [dashboard.blockradar.co/signup](https://dashboard.blockradar.co/signup) e complete o processo de integração. Leva menos de 60 segundos.
  </Step>

  <Step title="Verifique o Modo Live">
    No canto superior direito do dashboard você verá um botão de **Modo Live**. Está desativado por padrão, o que significa que cada ação é executada na **testnet**, um ambiente seguro sem fundos reais. Deixe desativado enquanto segue este guia.
  </Step>
</Steps>

***

## Passo 2: Crie uma carteira principal

### O que é uma carteira principal?

A carteira principal é a base da sua infraestrutura de stablecoin. Pense nela como sua tesouraria — ela controla todos os endereços secundários que você cria para seus usuários. Cada carteira principal está vinculada a uma blockchain específica, então se você quiser suportar depósitos no Ethereum, Base e BNB Chain, criará uma carteira principal separada para cada um.

### Crie sua primeira carteira

<Steps>
  <Step title="Vá para a página de Carteiras">
    No dashboard, clique em **Criar Carteira Principal**.
  </Step>

  <Step title="Selecione uma rede">
    Escolha **Base Sepolia (Testnet)** para seguir este guia.
  </Step>

  <Step title="Nomeie sua carteira">
    Dê um nome como `base-testnet` e clique em **Criar**.
  </Step>
</Steps>

***

## Passo 3: Gere endereços para seus usuários

### O que são endereços secundários?

Quando um usuário se cadastra no seu app e precisa receber stablecoins, ele precisa de um endereço de carteira. No Blockradar, esses são chamados de **endereços secundários**. São gerados sob sua carteira principal e herdam sua configuração de rede.

<Note>
  Endereços gerados em qualquer rede compatível com EVM funcionam em todas as redes EVM. Um endereço cobre todas as suas redes EVM.
</Note>

### Gere um endereço via API

```bash theme={null}
curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carteira Cliente",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": true,
    "metadata": {
      "user_id": 1234,
      "email": "usuario@exemplo.com"
    }
  }'
```

### O campo metadata

O objeto `metadata` é uma das partes mais importantes desta requisição. Tudo que você anexar aqui será incluído em cada webhook que o Blockradar enviar para aquele endereço. É assim que seu backend identifica a qual usuário uma transação pertence.

**Boa prática:** Sempre inclua um `user_id` no metadata para mapear cada depósito diretamente a um usuário no seu banco de dados.

***

## Passo 4: Configure a varredura automática e transações sem gas

### Varredura automática

Quando a varredura automática está habilitada (`disableAutoSweep: false`), os fundos depositados em um endereço secundário são automaticamente consolidados na sua carteira principal.

<Warning>
  Para que a varredura automática funcione, sua carteira principal deve ter tokens nativos para cobrir as taxas de gas.
</Warning>

**Faucets de testnet para tokens de gas:**

| Rede             | 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/)                                          |

### Transações sem gas

Quando `enableGaslessWithdraw: true`, seus usuários podem enviar stablecoins do endereço deles sem ter tokens nativos. Sua carteira principal cobre o gas em nome deles.

***

## Passo 5: Configure os webhooks

O Blockradar usa webhooks para notificar seu backend quando eventos blockchain acontecem.

### Registre seu endpoint de webhook

1. Vá para sua carteira principal no dashboard
2. Clique em **Desenvolvedor → Webhook**
3. Insira a URL do seu endpoint backend (deve ser um endpoint `POST`)

### Trate webhooks no seu backend

```javascript theme={null}
app.post("/webhook-handler", (req, res) => {
  const event = req.body;
  console.log("Webhook recebido:", event);
  res.sendStatus(200);
});
```

### Eventos de webhook comuns

| Evento                  | Descrição                                          |
| ----------------------- | -------------------------------------------------- |
| `deposit.success`       | Um depósito foi recebido em um endereço secundário |
| `deposit.swept.success` | Fundos foram varridos para a carteira principal    |
| `withdraw.success`      | Um saque foi enviado com sucesso                   |
| `swap.success`          | Uma troca foi executada com sucesso                |

***

## Passo 6: Trate um evento de depósito

### Payload de exemplo

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "amountPaid": "10.0",
    "currency": "USD",
    "senderAddress": "0xabc...",
    "recipientAddress": "0xdef...",
    "metadata": {
      "user_id": 1234
    }
  }
}
```

### Como processar

<Steps>
  <Step title="Identifique o usuário">
    Extraia `metadata.user_id` do payload para mapear o depósito a um usuário no seu banco de dados.
  </Step>

  <Step title="Leia o valor">
    Use `data.amountPaid` para determinar quanto foi depositado.
  </Step>

  <Step title="Atualize o saldo">
    Credite o saldo do usuário no seu banco de dados.
  </Step>
</Steps>

***

## O que você construiu

Agora você tem um fluxo completo de pagamento em stablecoin:

* Uma carteira principal na testnet
* Endereços secundários vinculados a usuários via metadata
* Varredura automática consolidando fundos na sua tesouraria
* Transações sem gas eliminando fricção para seus usuários
* Um handler de webhooks atualizando saldos em tempo real

## Para onde ir agora

<CardGroup cols={2}>
  <Card title="Enviar pagamentos" icon="arrow-up-from-bracket" href="/pt/use-cases/pay-outs">
    Envie stablecoins para seus usuários ou parceiros programaticamente.
  </Card>

  <Card title="Adicionar verificação AML" icon="shield-halved" href="/pt/use-cases/aml-screening">
    Verifique endereços antes de enviar ou receber fundos.
  </Card>

  <Card title="Explorar trocas" icon="arrows-rotate" href="/pt/use-cases/swap">
    Permita que usuários troquem entre stablecoins com uma única chamada de API.
  </Card>

  <Card title="Lançar em produção" icon="rocket" href="https://dashboard.blockradar.co">
    Ative o Modo Live no dashboard e comece a aceitar fundos reais.
  </Card>
</CardGroup>