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

# Earn

> Gere rendimento sobre saldos ociosos de stablecoins por meio de provedores regulados e protocolos DeFi

<Note>
  Em resumo<br />
  O Blockradar Earn permite que você coloque stablecoins ociosas para trabalhar e as faça crescer ao longo do tempo — semelhante a uma conta poupança de alto rendimento, mas **não custodial**: os fundos saem da sua própria wallet, a Blockradar nunca os agrupa nem os retém, e você pode sacar qualquer parte a qualquer momento.
</Note>

## Como funciona

Normalmente, stablecoins ociosas apenas ficam paradas na sua wallet. O Earn move um valor escolhido para uma estratégia de rendimento onde ele acumula juros continuamente, e o devolve à sua wallet sempre que você saca. Você mantém todo o seu depósito original — o Earn simplesmente o faz crescer.

<CardGroup cols={3}>
  <Card title="Você mantém o controle" icon="lock-open">
    Os fundos saem da sua própria wallet. A Blockradar nunca assume a custódia nem mistura seu dinheiro com o de ninguém.
  </Card>

  <Card title="Rende automaticamente" icon="clock">
    Os juros se acumulam continuamente, 24 horas por dia — não há nada para gerenciar.
  </Card>

  <Card title="Saque a qualquer momento" icon="rotate-left">
    Retire parte ou tudo quando quiser. Não há período de bloqueio.
  </Card>
</CardGroup>

### Três passos

<Steps>
  <Step title="Depositar">
    Escolha um ativo, um valor e um estilo de rendimento (Regulado ou DeFi). Seus fundos vão para a estratégia. **Depositar é gratuito.**
  </Step>

  <Step title="Render">
    Seu saldo cresce por conta própria à medida que os juros se acumulam. O valor ao vivo é refletido na sua posição.
  </Step>

  <Step title="Sacar">
    Retire parte ou tudo, a qualquer momento. Você recebe **exatamente o valor que solicitar** — a taxa é descontada dos rendimentos, nunca do seu principal.
  </Step>
</Steps>

## Os dois estilos de rendimento

Ao depositar, você escolhe um de dois estilos. Eles direcionam seus fundos para diferentes venues confiáveis que geram juros. Os estilos disponíveis dependem da rede em que sua wallet está.

<CardGroup cols={2}>
  <Card title="Regulado" icon="building-columns">
    Rendimento por meio de um provedor regulado e mais conservador (**Fija**). Uma boa opção se você prefere a via regulada.

    **Disponível em:** Ethereum
  </Card>

  <Card title="DeFi" icon="cubes">
    Rendimento por meio da **Aave** — um dos maiores, mais estabelecidos e testados protocolos de empréstimo em cripto.

    **Disponível em:** Ethereum, Base, Arbitrum, Optimism, Polygon
  </Card>
</CardGroup>

|              | Regulado                         | DeFi                                          |
| ------------ | -------------------------------- | --------------------------------------------- |
| **Provedor** | Fija                             | Aave                                          |
| **Perfil**   | Via mais conservadora e regulada | Protocolo de empréstimo on-chain estabelecido |
| **Retornos** | Variáveis                        | Variáveis (orientados pelo mercado)           |
| **Redes**    | Ethereum                         | Ethereum, Base, Arbitrum, Optimism, Polygon   |

<Info>
  Ambos os estilos são não custodiais e geram rendimento — a escolha é sobre qual via você prefere. O dashboard exibe apenas os estilos válidos para a rede da sua wallet.
</Info>

## Pré-requisitos

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

  <Step title="Master Wallet criada">
    Crie uma master wallet via [Create Wallet API](/en/api-reference/wallets/create-wallet) ou pelo dashboard. As posições do Earn são financiadas a partir dos saldos da sua wallet.
  </Step>

  <Step title="Recurso Earn habilitado">
    Certifique-se de que o recurso Earn esteja habilitado na sua conta. Entre em contato com [support@blockradar.co](mailto:support@blockradar.co) se precisar ativá-lo.
  </Step>

  <Step title="Saldo suficiente">
    Financie a wallet com a stablecoin que você pretende depositar, além de tokens nativos para cobrir as taxas de rede on-chain.
  </Step>
</Steps>

## Saques

Ao sacar, você especifica o valor que deseja **receber**, e exatamente esse valor chega à sua wallet. Escolher **sacar tudo** encerra a posição e envia tudo o que resta (depósito + todos os juros acumulados).

## O que você pode acompanhar

<CardGroup cols={3}>
  <Card title="Saldo" icon="wallet">
    Quanto sua posição vale agora — depósito mais juros, já líquido da taxa.
  </Card>

  <Card title="Juros gerados" icon="seedling">
    Quanto você ganhou — hoje, nesta semana e ao longo da vida da posição.
  </Card>

  <Card title="Taxa (APY)" icon="bolt">
    A taxa anual que você está ganhando, exibida como sua taxa líquida após a taxa de serviço.
  </Card>
</CardGroup>

## Segurança e confiabilidade

<CardGroup cols={3}>
  <Card title="Não custodial" icon="lock">
    Os fundos saem da sua própria wallet direto para a estratégia. A Blockradar nunca assume a custódia.
  </Card>

  <Card title="Protocolos estabelecidos" icon="building-columns">
    Os fundos vão para fontes de rendimento confiáveis — um provedor regulado (Fija) ou a Aave, um protocolo DeFi líder.
  </Card>

  <Card title="Sem bloqueio" icon="door-open">
    Sem período de espera. Saque parte ou tudo a qualquer momento.
  </Card>
</CardGroup>

Vários mecanismos de segurança são executados em segundo plano para manter saldos e taxas corretos:

* **Fallback de taxa** — se uma fonte de taxa falhar brevemente, uma taxa recente conhecida é usada para que taxas e saldos nunca fiquem errados.
* **Tentativas seguras** — transações interrompidas são repetidas de forma idempotente; os fundos nunca são perdidos nem gastos em duplicidade.
* **Reconciliação on-chain** — o saldo exibido é reconciliado com o saldo real on-chain.

<Warning>
  Os rendimentos são variáveis — as taxas podem subir ou cair ao longo do tempo — e o DeFi carrega os riscos usuais de smart contracts inerentes a qualquer protocolo on-chain. Seu **depósito** nunca tem taxa cobrada, mas, como em qualquer investimento, os retornos não são garantidos.
</Warning>

## Usando a API

O recurso é exposto sob o recurso `rewards`. Todas as requisições são autenticadas com sua chave de API por meio do header `x-api-key`. A estratégia é selecionada com um campo `type`:

* **`regulated`** — Fija (um vault ERC-4626)
* **`defi`** — Aave

Os valores são sempre passados como **strings**. Depósitos e saques são **assíncronos**: cada um retorna uma transação `PENDING`, e a conclusão é entregue via webhook.

<Info>
  A maioria dos endpoints aceita um `addressId` opcional para restringir a operação a um sub-endereço. Omita-o para atuar na master wallet.
</Info>

### 1. Descubra o que está disponível

Antes de depositar, verifique quais estratégias uma chain suporta e quais ativos de uma wallet são elegíveis para rewards (junto com o APY atual de cada estratégia).

<CodeGroup>
  ```bash Supported chains theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/rewards/supported-chains \
    --header 'x-api-key: <api-key>'
  ```

  ```bash Wallet reward assets theme={null}
  curl --request GET \
    --url 'https://api.blockradar.co/v1/wallets/{walletId}/rewards/assets?type=defi' \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

```json Supported chains response theme={null}
{
  "message": "Supported reward chains retrieved successfully",
  "statusCode": 200,
  "data": {
    "all": ["ethereum", "base", "arbitrum", "optimism", "polygon"],
    "byType": {
      "regulated": ["ethereum"],
      "defi": ["ethereum", "base", "arbitrum", "optimism", "polygon"]
    }
  }
}
```

### 2. Pré-visualize a taxa de rede (opcional)

Estime a taxa de rede on-chain e verifique o saldo nativo da wallet antes de confirmar. Isso **não** move fundos.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/rewards/deposit/network-fee \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "b1deda8d-7609-4895-b584-e8ef1f13e354",
      "amount": "1000",
      "type": "defi"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "message": "Network fee fetched successfully",
  "statusCode": 200,
  "data": {
    "networkFee": "0.00006779052",
    "networkFeeInUSD": "0.14371725",
    "nativeBalance": "0.000929309612767174",
    "nativeBalanceInUSD": "1.97015496",
    "estimatedArrivalTime": 30,
    "transactionFee": "0"
  }
}
```

<Note>
  A mesma pré-visualização está disponível para saques em `POST /v1/wallets/{walletId}/rewards/withdraw/network-fee`.
</Note>

### 3. Depositar

Mova um ativo para uma estratégia de rendimento. Depositar é gratuito — a taxa só incide sobre os juros gerados.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/rewards/deposit \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "b1deda8d-7609-4895-b584-e8ef1f13e354",
      "amount": "1000",
      "type": "defi",
      "reference": "order_12345",
      "metadata": {}
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/rewards/deposit`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId: 'b1deda8d-7609-4895-b584-e8ef1f13e354',
        amount: '1000',
        type: 'defi',
        reference: 'order_12345'
      })
    }
  ).then(r => r.json());

  console.log('Deposit initiated:', response.data);
  ```
</CodeGroup>

#### Parâmetros do corpo

| Parâmetro   | Tipo          | Obrigatório | Descrição                                                         |
| ----------- | ------------- | ----------- | ----------------------------------------------------------------- |
| `assetId`   | string (UUID) | Sim         | O ativo a depositar. Deve ter suporte a rewards (veja o passo 1). |
| `amount`    | string        | Sim         | Valor a depositar. Deve ser maior que 0.                          |
| `type`      | string        | Sim         | Classe de estratégia: `regulated` (Fija) ou `defi` (Aave).        |
| `reference` | string        | Não         | Referência do cliente, validada quanto à unicidade.               |
| `metadata`  | object        | Não         | Metadados personalizados retornados na transação.                 |
| `addressId` | string (UUID) | Não         | Restringe a um sub-endereço. Omita para usar a master wallet.     |

```json Response theme={null}
{
  "message": "Rewards Deposit initiated successfully",
  "statusCode": 200,
  "data": {
    "id": "47ae3a92-4d36-4807-af9e-b83a4eb08d69",
    "reference": null,
    "amount": "1000",
    "amountPaid": "1000",
    "status": "PENDING",
    "type": "REWARD_DEPOSIT",
    "createdAt": "2026-06-03T13:58:33.222Z",
    "asset": {
      "symbol": "USDC",
      "decimals": 6,
      "blockchain": { "slug": "base", "name": "base" }
    }
  }
}
```

### 4. Acompanhe posições e rendimentos

As posições são agregadas por estratégia e incluem saldo ao vivo, APY, principal depositado e rendimentos (hoje / esta semana / total) — tudo já líquido da taxa.

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

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

  ```bash Business-wide positions theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/rewards \
    --header 'x-api-key: <api-key>'
  ```

  ```bash Recent transactions theme={null}
  curl --request GET \
    --url 'https://api.blockradar.co/v1/rewards/transactions?limit=10' \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

```json Position response theme={null}
{
  "message": "Wallet rewards retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "type": "defi",
      "apy": "2.41",
      "balance": "4.365017",
      "balanceInUSD": "4.365017",
      "totalDeposited": "4.360000",
      "totalDepositedInUSD": "4.360000",
      "earnings": "0.005017",
      "earningsInUSD": "0.005017",
      "todayEarnings": "0.000187",
      "weeklyEarnings": "0.001312",
      "lifetimeEarnings": "0.026492",
      "lifetimeEarningsInUSD": "0.026492",
      "asset": {
        "id": "2f6298ec-81ca-44f4-a8f2-cc045a46d28c",
        "isActive": true,
        "asset": {
          "id": "b1deda8d-7609-4895-b584-e8ef1f13e354",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "currency": "USD",
          "network": "mainnet",
          "blockchain": { "name": "base", "slug": "base", "symbol": "eth" }
        }
      }
    }
  ]
}
```

#### Campos da posição

| Campo              | Descrição                                                                    |
| ------------------ | ---------------------------------------------------------------------------- |
| `type`             | Classe de estratégia à qual a posição pertence (`regulated` ou `defi`).      |
| `apy`              | Rendimento percentual anual líquido atual, após a taxa.                      |
| `balance`          | Valor ao vivo da posição (principal + juros acumulados), líquido da taxa.    |
| `totalDeposited`   | Principal depositado na posição.                                             |
| `earnings`         | Juros acumulados na posição até o momento.                                   |
| `todayEarnings`    | Juros acumulados hoje.                                                       |
| `weeklyEarnings`   | Juros acumulados nesta semana.                                               |
| `lifetimeEarnings` | Juros acumulados ao longo da vida da posição (incluindo valores já sacados). |
| `*InUSD`           | O valor convertido em USD do campo correspondente.                           |
| `asset`            | O ativo da wallet em que a posição é mantida, com sua blockchain e rede.     |

<Note>
  `/v1/rewards` retorna o mesmo formato agregado entre **todas** as wallets do seu negócio, enquanto `/v1/wallets/{walletId}/rewards` se restringe a uma única wallet. Passe `assetId` para qualquer um dos endpoints de wallet para retornar um único objeto de posição em vez de um array.
</Note>

### 5. Sacar

O `amount` é o valor **líquido** que você recebe — a Blockradar faz o gross-up do resgate para que a taxa seja retirada apenas do rendimento realizado. Passe `"max"` para sair totalmente e encerrar a posição.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/rewards/withdraw \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "b1deda8d-7609-4895-b584-e8ef1f13e354",
      "amount": "500",
      "type": "defi"
    }'
  ```

  ```bash Full exit theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/rewards/withdraw \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "b1deda8d-7609-4895-b584-e8ef1f13e354",
      "amount": "max",
      "type": "defi"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/rewards/withdraw`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId: 'b1deda8d-7609-4895-b584-e8ef1f13e354',
        amount: '500',
        type: 'defi'
      })
    }
  ).then(r => r.json());

  console.log('Withdrawal initiated:', response.data);
  ```
</CodeGroup>

#### Parâmetros do corpo

| Parâmetro   | Tipo          | Obrigatório | Descrição                                                                                      |
| ----------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `assetId`   | string (UUID) | Sim         | O ativo a sacar.                                                                               |
| `amount`    | string        | Sim         | Valor líquido a receber, ou `"max"` para uma saída total.                                      |
| `type`      | string        | Não         | Classe de estratégia: `regulated` ou `defi`.                                                   |
| `address`   | string        | Não         | Endereço de destino externo. Omita para creditar o signatário (master wallet ou sub-endereço). |
| `reference` | string        | Não         | Referência do cliente.                                                                         |
| `metadata`  | object        | Não         | Metadados personalizados.                                                                      |
| `addressId` | string (UUID) | Não         | Restringe a um sub-endereço. Omita para usar a master wallet.                                  |

### Ciclo de vida da transação

Tanto o depósito quanto o saque são **assíncronos**. A chamada de início retorna uma transação no estado `PENDING` — a liquidação on-chain acontece em seguida, e o resultado final é entregue via webhook.

| Campo    | Valores                             | Descrição                                                                |
| -------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `type`   | `REWARD_DEPOSIT`, `REWARD_WITHDRAW` | O tipo de transação do Earn.                                             |
| `status` | `PENDING` → liquidada               | Começa como `PENDING`; muda assim que a transação é confirmada on-chain. |

Use **Business Reward Transactions** (`GET /v1/rewards/transactions`) para listar os depósitos e saques recentes em todo o seu negócio, do mais novo ao mais antigo.

```json Transaction shape theme={null}
{
  "id": "47ae3a92-4d36-4807-af9e-b83a4eb08d69",
  "reference": null,
  "amount": "0.2",
  "amountPaid": "0.2",
  "status": "PENDING",
  "type": "REWARD_WITHDRAW",
  "createdAt": "2026-06-03T13:58:33.222Z",
  "asset": {
    "symbol": "USDC",
    "decimals": 6,
    "blockchain": { "slug": "base", "name": "base" }
  }
}
```

## Referência da API

| Método | Endpoint                                                                                                | Descrição                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET`  | [`/v1/rewards`](/en/api-reference/rewards/business-rewards)                                             | Posições de todo o negócio agregadas entre todas as wallets, agrupadas por estratégia |
| `GET`  | [`/v1/rewards/supported-chains`](/en/api-reference/rewards/supported-chains)                            | Chains suportadas como união plana e agrupadas por tipo de estratégia                 |
| `GET`  | [`/v1/rewards/transactions`](/en/api-reference/rewards/business-transactions)                           | Depósitos e saques de rewards mais recentes (do mais novo ao mais antigo)             |
| `GET`  | [`/v1/wallets/{walletId}/rewards`](/en/api-reference/rewards/wallet-rewards)                            | Posições de uma wallet; passe `assetId` para um único ativo                           |
| `GET`  | [`/v1/wallets/{walletId}/rewards/assets`](/en/api-reference/rewards/wallet-reward-assets)               | Ativos elegíveis para rewards de uma wallet e o APY de cada estratégia                |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit`](/en/api-reference/rewards/deposit)                           | Deposite um ativo em uma estratégia do Earn                                           |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit/network-fee`](/en/api-reference/rewards/deposit-network-fee)   | Pré-visualize a taxa de rede de um depósito                                           |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw`](/en/api-reference/rewards/withdraw)                         | Saque um valor líquido (ou `"max"`) de uma posição                                    |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw/network-fee`](/en/api-reference/rewards/withdraw-network-fee) | Pré-visualize a taxa de rede de um saque                                              |

## FAQ

<AccordionGroup>
  <Accordion title="Depositar tem algum custo?">
    Não. Depositar é gratuito. A única taxa é uma pequena parcela dos juros que você ganha — nunca do seu depósito.
  </Accordion>

  <Accordion title="Quando começo a render?">
    Assim que seu depósito é liquidado on-chain, ele começa a render continuamente, 24 horas por dia.
  </Accordion>

  <Accordion title="Quão rápido é um saque?">
    Ele começa imediatamente e é liquidado on-chain logo em seguida. Você é notificado no momento em que ele é concluído.
  </Accordion>

  <Accordion title="Qual é a diferença entre Regulado e DeFi?">
    O Regulado direciona seus fundos por meio de um provedor regulado e mais conservador (Fija, na Ethereum). O DeFi usa a Aave, um grande protocolo de empréstimo estabelecido, disponível em mais redes. Ambos geram rendimento — a questão é qual via você prefere.
  </Accordion>

  <Accordion title="Vou receber de volta menos do que apliquei?">
    Seu depósito nunca tem taxa cobrada, e você fica com os juros menos a pequena parcela da Blockradar. As taxas são variáveis e os protocolos on-chain carregam risco, então os retornos não são garantidos — mas a taxa da plataforma nunca toca no seu principal.
  </Accordion>

  <Accordion title="O que 'sacar tudo' faz?">
    Retira tudo daquela posição — seu depósito mais todos os juros gerados — e a encerra. Você pode iniciar um novo depósito a qualquer momento.
  </Accordion>

  <Accordion title="Por que um depósito novo de $0.20 às vezes aparece como $0.199999?">
    Isso é uma pequena peculiaridade de arredondamento do protocolo subjacente (uma fração de centavo), não uma taxa. Isso se ajusta, e seu saldo sobe acima do seu depósito assim que os juros se acumulam.
  </Accordion>
</AccordionGroup>

## Suporte

* **E-mail**: [support@blockradar.co](mailto:support@blockradar.co)