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

> Earn rewards on idle stablecoin balances via regulated providers and DeFi protocols

<Note>
  In a nutshell<br />
  Blockradar Earn lets you put idle stablecoins to work and grow them over time — similar to a high-yield savings account, but **non-custodial**: funds move from your own wallet, Blockradar never pools or holds them, and you can withdraw any portion at any time.
</Note>

## How It Works

Idle stablecoins normally just sit in your wallet. Earn moves a chosen amount into an earning strategy where it accrues interest continuously, and returns it to your wallet whenever you withdraw. You keep all of your original deposit — Earn simply grows it.

<CardGroup cols={3}>
  <Card title="You stay in control" icon="lock-open">
    Funds move from your own wallet. Blockradar never takes custody or mixes your money with anyone else's.
  </Card>

  <Card title="Earns automatically" icon="clock">
    Interest accrues continuously, around the clock — there's nothing to manage.
  </Card>

  <Card title="Withdraw anytime" icon="rotate-left">
    Take out part or all whenever you like. There is no lock-up period.
  </Card>
</CardGroup>

### Three Steps

<Steps>
  <Step title="Deposit">
    Pick an asset, an amount, and an earning style (Regulated or DeFi). Your funds move into the strategy. **Depositing is free.**
  </Step>

  <Step title="Earn">
    Your balance grows on its own as interest accrues. The live value is reflected in your position.
  </Step>

  <Step title="Withdraw">
    Take out some or all, anytime. You receive **exactly the amount you ask for** — the fee is drawn from earnings, never your principal.
  </Step>
</Steps>

## The Two Earning Styles

When you deposit, you choose one of two styles. They route your funds to different trusted, interest-bearing venues. Available styles depend on the network your wallet is on.

<CardGroup cols={2}>
  <Card title="Regulated" icon="building-columns">
    Rewards through a regulated, more conservative provider (**Fija**). A good fit if you prefer the regulated route.

    **Available on:** Ethereum
  </Card>

  <Card title="DeFi" icon="cubes">
    Rewards through **Aave** — one of the largest, most established and battle-tested lending protocols in crypto.

    **Available on:** Ethereum, Base, Arbitrum, Optimism, Polygon
  </Card>
</CardGroup>

|              | Regulated                          | DeFi                                        |
| ------------ | ---------------------------------- | ------------------------------------------- |
| **Provider** | Fija                               | Aave                                        |
| **Profile**  | More conservative, regulated route | Established on-chain lending protocol       |
| **Returns**  | Variable                           | Variable (market-driven)                    |
| **Networks** | Ethereum                           | Ethereum, Base, Arbitrum, Optimism, Polygon |

<Info>
  Both styles are non-custodial and earn rewards — the choice is about which route you prefer. The dashboard only surfaces the styles that are valid for your wallet's network.
</Info>

## Prerequisites

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Master Wallet Created">
    Create a master wallet via the [Create Wallet API](/en/api-reference/wallets/create-wallet) or dashboard. Earn positions are funded from your wallet balances.
  </Step>

  <Step title="Earn Feature Enabled">
    Ensure the Earn feature is enabled on your account. Contact [support@blockradar.co](mailto:support@blockradar.co) if you need to activate it.
  </Step>

  <Step title="Sufficient Balance">
    Fund the wallet with the stablecoin you intend to deposit, plus native tokens to cover on-chain network fees.
  </Step>
</Steps>

## Withdrawals

When you withdraw, you specify the amount you want to **receive**, and that exact amount lands in your wallet. Choosing **withdraw all** closes the position and sends you everything that's left (deposit + all accrued interest).

## What You Can Track

<CardGroup cols={3}>
  <Card title="Balance" icon="wallet">
    What your position is worth right now — deposit plus interest, already net of the fee.
  </Card>

  <Card title="Interest earned" icon="seedling">
    How much you've earned — today, this week, and over the lifetime of the position.
  </Card>

  <Card title="Rate (APY)" icon="bolt">
    The yearly rate you're earning, shown as your net rate after the fee.
  </Card>
</CardGroup>

## Safety & Reliability

<CardGroup cols={3}>
  <Card title="Non-custodial" icon="lock">
    Funds move from your own wallet straight into the strategy. Blockradar never takes custody.
  </Card>

  <Card title="Established protocols" icon="building-columns">
    Funds go to trusted rewards sources — a regulated provider (Fija) or Aave, a leading DeFi protocol.
  </Card>

  <Card title="No lock-up" icon="door-open">
    No waiting period. Withdraw part or all at any time.
  </Card>
</CardGroup>

Several safeguards run in the background to keep balances and fees correct:

* **Rate fallback** — if a rate source briefly hiccups, a recent known rate is used so fees and balances are never wrong.
* **Safe retries** — interrupted transactions are retried idempotently; funds are never lost or double-spent.
* **On-chain reconciliation** — your displayed balance is reconciled against the real on-chain balance.

<Warning>
  Rewards are variable — rates can rise or fall over time — and DeFi carries the usual smart-contract risks that come with any on-chain protocol. Your **deposit** is never charged a fee, but as with any investment, returns are not guaranteed.
</Warning>

## Using the API

The feature is exposed under the `rewards` resource. All requests are authenticated with your API key via the `x-api-key` header. The strategy is selected with a `type` field:

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

Amounts are always passed as **strings**. Deposits and withdrawals are **asynchronous**: each returns a `PENDING` transaction, and completion is delivered via webhook.

<Info>
  Most endpoints accept an optional `addressId` to scope the operation to a sub-address. Omit it to act on the master wallet.
</Info>

### 1. Discover what's available

Before depositing, check which strategies a chain supports and which of a wallet's assets are reward-eligible (along with each strategy's current APY).

<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. Preview the network fee (optional)

Estimate the on-chain network fee and check the wallet's native balance before committing. This does **not** move funds.

<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>
  The same preview is available for withdrawals at `POST /v1/wallets/{walletId}/rewards/withdraw/network-fee`.
</Note>

### 3. Deposit

Move an asset into an earning strategy. Depositing is free — the fee only ever applies to interest earned.

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

#### Body Parameters

| Parameter   | Type          | Required | Description                                                  |
| ----------- | ------------- | -------- | ------------------------------------------------------------ |
| `assetId`   | string (UUID) | Yes      | The asset to deposit. Must be reward-supported (see step 1). |
| `amount`    | string        | Yes      | Amount to deposit. Must be greater than 0.                   |
| `type`      | string        | Yes      | Strategy class: `regulated` (Fija) or `defi` (Aave).         |
| `reference` | string        | No       | Client reference, validated for uniqueness.                  |
| `metadata`  | object        | No       | Custom metadata echoed back on the transaction.              |
| `addressId` | string (UUID) | No       | Scope to a sub-address. Omit to use the 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. Track positions and earnings

Positions are aggregated per strategy and include live balance, APY, deposited principal, and earnings (today / this week / lifetime) — all already net of the fee.

<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" }
        }
      }
    }
  ]
}
```

#### Position Fields

| Field              | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `type`             | Strategy class the position belongs to (`regulated` or `defi`).                           |
| `apy`              | Current net annual percentage yield, after the fee.                                       |
| `balance`          | Live position value (principal + accrued interest), net of the fee.                       |
| `totalDeposited`   | Principal deposited into the position.                                                    |
| `earnings`         | Interest accrued on the position so far.                                                  |
| `todayEarnings`    | Interest accrued today.                                                                   |
| `weeklyEarnings`   | Interest accrued this week.                                                               |
| `lifetimeEarnings` | Interest accrued over the lifetime of the position (including amounts already withdrawn). |
| `*InUSD`           | The USD-converted value of the corresponding field.                                       |
| `asset`            | The wallet asset the position is held in, with its blockchain and network.                |

<Note>
  `/v1/rewards` returns the same shape aggregated across **all** wallets in your business, while `/v1/wallets/{walletId}/rewards` scopes to a single wallet. Pass `assetId` to either wallet endpoint to return a single position object instead of an array.
</Note>

### 5. Withdraw

The `amount` is the **net** amount you receive — Blockradar grosses up the redemption so the fee is taken from realized rewards only. Pass `"max"` to fully exit and close the position.

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

#### Body Parameters

| Parameter   | Type          | Required | Description                                                                             |
| ----------- | ------------- | -------- | --------------------------------------------------------------------------------------- |
| `assetId`   | string (UUID) | Yes      | The asset to withdraw.                                                                  |
| `amount`    | string        | Yes      | Net amount to receive, or `"max"` for a full exit.                                      |
| `type`      | string        | No       | Strategy class: `regulated` or `defi`.                                                  |
| `address`   | string        | No       | External destination address. Omit to credit the signer (master wallet or sub-address). |
| `reference` | string        | No       | Client reference.                                                                       |
| `metadata`  | object        | No       | Custom metadata.                                                                        |
| `addressId` | string (UUID) | No       | Scope to a sub-address. Omit to use the master wallet.                                  |

### Transaction Lifecycle

Both deposit and withdrawal are **asynchronous**. The initiating call returns a transaction in the `PENDING` state — the on-chain settlement happens afterward, and the final result is delivered via webhook.

| Field    | Values                              | Description                                                              |
| -------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `type`   | `REWARD_DEPOSIT`, `REWARD_WITHDRAW` | The kind of Earn transaction.                                            |
| `status` | `PENDING` → settled                 | Starts as `PENDING`; transitions once the transaction confirms on-chain. |

Use **Business Reward Transactions** (`GET /v1/rewards/transactions`) to list recent deposits and withdrawals across your business, newest first.

```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" }
  }
}
```

## API Reference

| Method | Endpoint                                                                                                | Description                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `GET`  | [`/v1/rewards`](/en/api-reference/rewards/business-rewards)                                             | Business-wide positions aggregated across all wallets, grouped per strategy |
| `GET`  | [`/v1/rewards/supported-chains`](/en/api-reference/rewards/supported-chains)                            | Supported chains as a flat union and grouped by strategy type               |
| `GET`  | [`/v1/rewards/transactions`](/en/api-reference/rewards/business-transactions)                           | Most recent reward deposits and withdrawals (newest first)                  |
| `GET`  | [`/v1/wallets/{walletId}/rewards`](/en/api-reference/rewards/wallet-rewards)                            | A wallet's positions; pass `assetId` for a single asset                     |
| `GET`  | [`/v1/wallets/{walletId}/rewards/assets`](/en/api-reference/rewards/wallet-reward-assets)               | A wallet's reward-eligible assets and each strategy's APY                   |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit`](/en/api-reference/rewards/deposit)                           | Deposit an asset into an earn strategy                                      |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit/network-fee`](/en/api-reference/rewards/deposit-network-fee)   | Preview the network fee for a deposit                                       |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw`](/en/api-reference/rewards/withdraw)                         | Withdraw a net amount (or `"max"`) from a position                          |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw/network-fee`](/en/api-reference/rewards/withdraw-network-fee) | Preview the network fee for a withdrawal                                    |

## FAQ

<AccordionGroup>
  <Accordion title="Does it cost anything to deposit?">
    No. Depositing is free. The only fee is a small share of the interest you earn — never your deposit.
  </Accordion>

  <Accordion title="When do I start earning?">
    As soon as your deposit settles on-chain, it begins earning continuously, around the clock.
  </Accordion>

  <Accordion title="How fast is a withdrawal?">
    It starts immediately and settles on-chain shortly after. You're notified the moment it completes.
  </Accordion>

  <Accordion title="What's the difference between Regulated and DeFi?">
    Regulated routes your funds through a regulated, more conservative provider (Fija, on Ethereum). DeFi uses Aave, a major established lending protocol available on more networks. Both earn rewards — it's about which route you prefer.
  </Accordion>

  <Accordion title="Will I get back less than I put in?">
    Your deposit is never charged a fee, and you keep the interest minus Blockradar's small share. Rates are variable and on-chain protocols carry risk, so returns aren't guaranteed — but the platform fee never touches your principal.
  </Accordion>

  <Accordion title="What does 'withdraw all' do?">
    It takes out everything in that position — your deposit plus all earned interest — and closes it. You can start a fresh deposit anytime.
  </Accordion>

  <Accordion title="Why does a fresh $0.20 deposit sometimes show as $0.199999?">
    That's a tiny rounding quirk of the underlying protocol (a fraction of a cent), not a fee. It evens out, and your balance rises above your deposit as soon as interest accrues.
  </Accordion>
</AccordionGroup>

## Support

* **Email**: [support@blockradar.co](mailto:support@blockradar.co)