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

> 通过受监管的提供方和 DeFi 协议，让闲置的稳定币余额产生收益

<Note>
  简而言之<br />
  Blockradar Earn 让您能够让闲置的稳定币产生效益，并随时间不断增长——类似于高收益储蓄账户，但属于**非托管**：资金从您自己的 wallet 转出，Blockradar 从不汇集或持有这些资金，您可以随时提取任意部分。
</Note>

## 工作原理

闲置的稳定币通常只是静置在您的 wallet 中。Earn 会将您选定的金额转入收益策略，使其持续产生利息，并在您提取时返还到您的 wallet。您的原始存入金额始终完整保留——Earn 只会让它增长。

<CardGroup cols={3}>
  <Card title="您始终掌控" icon="lock-open">
    资金从您自己的 wallet 转出。Blockradar 从不进行托管，也不会将您的资金与他人的混合。
  </Card>

  <Card title="自动产生收益" icon="clock">
    利息持续不断地全天候累积——无需任何管理。
  </Card>

  <Card title="随时提取" icon="rotate-left">
    您可以随时提取部分或全部资金，没有锁定期。
  </Card>
</CardGroup>

### 三个步骤

<Steps>
  <Step title="存入">
    选择一种资产、一个金额，以及一种收益方式（Regulated 或 DeFi）。您的资金将转入该策略。**存入是免费的。**
  </Step>

  <Step title="赚取收益">
    随着利息的累积，您的余额会自行增长。实时价值会反映在您的持仓中。
  </Step>

  <Step title="提取">
    随时提取部分或全部资金。您将收到**与您请求金额完全一致**的款项——手续费从收益中扣除，绝不会动用您的本金。
  </Step>
</Steps>

## 两种收益方式

存入时，您需要从两种方式中选择一种。它们会将您的资金导向不同的、受信任的、可产生利息的渠道。可用的方式取决于您 wallet 所在的网络。

<CardGroup cols={2}>
  <Card title="Regulated" icon="building-columns">
    通过受监管、更为稳健的提供方（**Fija**）产生收益。如果您更偏好受监管的路径，这是一个不错的选择。

    **可用网络：** Ethereum
  </Card>

  <Card title="DeFi" icon="cubes">
    通过 **Aave** 产生收益——它是加密领域规模最大、最成熟、经受过实战检验的借贷协议之一。

    **可用网络：** Ethereum、Base、Arbitrum、Optimism、Polygon
  </Card>
</CardGroup>

|         | Regulated   | DeFi                                    |
| ------- | ----------- | --------------------------------------- |
| **提供方** | Fija        | Aave                                    |
| **特点**  | 更为稳健、受监管的路径 | 成熟的链上借贷协议                               |
| **收益**  | 浮动          | 浮动（由市场决定）                               |
| **网络**  | Ethereum    | Ethereum、Base、Arbitrum、Optimism、Polygon |

<Info>
  两种方式都是非托管的，且都能产生收益——选择只关乎您更偏好哪条路径。Dashboard 只会显示对您 wallet 所在网络有效的方式。
</Info>

## 前置条件

<Steps>
  <Step title="API 密钥">
    从 [Blockradar Dashboard](https://dashboard.blockradar.co) 获取您的 API 密钥。前往 **Developers** 创建一个。
  </Step>

  <Step title="已创建 Master Wallet">
    通过 [Create Wallet API](/en/api-reference/wallets/create-wallet) 或 dashboard 创建一个 master wallet。Earn 持仓由您的 wallet 余额提供资金。
  </Step>

  <Step title="已启用 Earn 功能">
    请确保您的账户已启用 Earn 功能。如需开通，请联系 [support@blockradar.co](mailto:support@blockradar.co)。
  </Step>

  <Step title="充足的余额">
    为 wallet 充入您计划存入的稳定币，以及用于支付链上网络手续费的原生代币。
  </Step>
</Steps>

## 提取

提取时，您需要指定希望**收到**的金额，到账到您 wallet 的正是该金额。选择**全部提取**会关闭该持仓，并将剩余的一切（存入金额 + 全部累积利息）发送给您。

## 您可以追踪的内容

<CardGroup cols={3}>
  <Card title="余额" icon="wallet">
    您的持仓当前价值——存入金额加利息，已扣除手续费。
  </Card>

  <Card title="已赚取的利息" icon="seedling">
    您已赚取的金额——今日、本周以及持仓存续期间的累计。
  </Card>

  <Card title="费率（APY）" icon="bolt">
    您正在赚取的年化费率，以扣除手续费后的净费率显示。
  </Card>
</CardGroup>

## 安全性与可靠性

<CardGroup cols={3}>
  <Card title="非托管" icon="lock">
    资金从您自己的 wallet 直接转入策略。Blockradar 从不进行托管。
  </Card>

  <Card title="成熟的协议" icon="building-columns">
    资金会进入受信任的收益来源——受监管的提供方（Fija）或领先的 DeFi 协议 Aave。
  </Card>

  <Card title="无锁定期" icon="door-open">
    没有等待期。随时提取部分或全部资金。
  </Card>
</CardGroup>

后台运行着多项保障机制，以确保余额和手续费的准确性：

* **费率回退**——如果某个费率来源短暂出现故障，系统会使用最近的已知费率，从而确保手续费和余额绝不会出错。
* **安全重试**——被中断的交易会以幂等方式重试；资金绝不会丢失或被重复花费。
* **链上对账**——您显示的余额会与真实的链上余额进行对账。

<Warning>
  收益是浮动的——费率可能随时间上升或下降——并且 DeFi 带有任何链上协议都会有的常见智能合约风险。您的**存入金额**绝不会被收取手续费，但与任何投资一样，回报无法保证。
</Warning>

## 使用 API

该功能通过 `rewards` 资源对外提供。所有请求均通过 `x-api-key` 请求头使用您的 API 密钥进行身份验证。策略通过 `type` 字段进行选择：

* **`regulated`**——Fija（一个 ERC-4626 金库）
* **`defi`**——Aave

金额始终以**字符串**形式传入。存入和提取均为**异步**操作：每个操作都会返回一个 `PENDING` 交易，完成情况通过 webhook 推送。

<Info>
  大多数 endpoint 都接受一个可选的 `addressId`，用于将操作限定到某个 sub-address。省略它则对 master wallet 进行操作。
</Info>

### 1. 查看可用项

在存入之前，请先查看某条链支持哪些策略，以及 wallet 中哪些资产符合奖励条件（以及每种策略当前的 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. 预览网络手续费（可选）

在确认操作之前，估算链上网络手续费并检查 wallet 的原生代币余额。此操作**不会**转移资金。

<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>
  同样的预览也适用于提取，对应 `POST /v1/wallets/{walletId}/rewards/withdraw/network-fee`。
</Note>

### 3. 存入

将一种资产转入收益策略。存入是免费的——手续费只会适用于已赚取的利息。

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

#### 请求体参数

| 参数          | 类型            | 是否必填 | 说明                                     |
| ----------- | ------------- | ---- | -------------------------------------- |
| `assetId`   | string (UUID) | 是    | 要存入的资产。必须支持奖励（参见步骤 1）。                 |
| `amount`    | string        | 是    | 要存入的金额。必须大于 0。                         |
| `type`      | string        | 是    | 策略类别：`regulated`（Fija）或 `defi`（Aave）。  |
| `reference` | string        | 否    | 客户端引用，会校验唯一性。                          |
| `metadata`  | object        | 否    | 自定义元数据，会在交易中原样返回。                      |
| `addressId` | string (UUID) | 否    | 限定到某个 sub-address。省略则使用 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. 追踪持仓与收益

持仓按策略进行聚合，包含实时余额、APY、已存入本金以及收益（今日 / 本周 / 累计）——所有数据均已扣除手续费。

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

#### 持仓字段

| 字段                 | 说明                                |
| ------------------ | --------------------------------- |
| `type`             | 该持仓所属的策略类别（`regulated` 或 `defi`）。 |
| `apy`              | 当前的净年化收益率（扣除手续费后）。                |
| `balance`          | 持仓的实时价值（本金 + 累积利息），已扣除手续费。        |
| `totalDeposited`   | 已存入该持仓的本金。                        |
| `earnings`         | 该持仓迄今累积的利息。                       |
| `todayEarnings`    | 今日累积的利息。                          |
| `weeklyEarnings`   | 本周累积的利息。                          |
| `lifetimeEarnings` | 持仓存续期间累积的利息（包括已提取的部分）。            |
| `*InUSD`           | 对应字段换算为美元的价值。                     |
| `asset`            | 该持仓所持有的 wallet 资产，以及其区块链和网络。      |

<Note>
  `/v1/rewards` 返回的结构相同，但聚合了您业务中的**所有** wallet，而 `/v1/wallets/{walletId}/rewards` 仅限定于单个 wallet。向任一 wallet endpoint 传入 `assetId`，即可返回单个持仓对象而非数组。
</Note>

### 5. 提取

`amount` 是您收到的**净**金额——Blockradar 会对赎回进行总额折算，使手续费仅从已实现的收益中扣除。传入 `"max"` 可完全退出并关闭持仓。

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

#### 请求体参数

| 参数          | 类型            | 是否必填 | 说明                                            |
| ----------- | ------------- | ---- | --------------------------------------------- |
| `assetId`   | string (UUID) | 是    | 要提取的资产。                                       |
| `amount`    | string        | 是    | 要收到的净金额，或传入 `"max"` 以完全退出。                    |
| `type`      | string        | 否    | 策略类别：`regulated` 或 `defi`。                    |
| `address`   | string        | 否    | 外部目标地址。省略则记入签名方（master wallet 或 sub-address）。 |
| `reference` | string        | 否    | 客户端引用。                                        |
| `metadata`  | object        | 否    | 自定义元数据。                                       |
| `addressId` | string (UUID) | 否    | 限定到某个 sub-address。省略则使用 master wallet。        |

### 交易生命周期

存入和提取均为**异步**操作。发起调用会返回一个处于 `PENDING` 状态的交易——链上结算随后进行，最终结果通过 webhook 推送。

| 字段       | 取值                                 | 说明                         |
| -------- | ---------------------------------- | -------------------------- |
| `type`   | `REWARD_DEPOSIT`、`REWARD_WITHDRAW` | Earn 交易的类型。                |
| `status` | `PENDING` → 已结算                    | 初始为 `PENDING`；在交易于链上确认后转变。 |

使用 **Business Reward Transactions**（`GET /v1/rewards/transactions`）可列出您业务中近期的存入和提取，按时间从新到旧排序。

```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 参考

| Method | Endpoint                                                                                                | 说明                                 |
| ------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `GET`  | [`/v1/rewards`](/en/api-reference/rewards/business-rewards)                                             | 跨所有 wallet 聚合、按策略分组的业务级持仓          |
| `GET`  | [`/v1/rewards/supported-chains`](/en/api-reference/rewards/supported-chains)                            | 受支持的链，以扁平并集形式呈现并按策略类型分组            |
| `GET`  | [`/v1/rewards/transactions`](/en/api-reference/rewards/business-transactions)                           | 最近的奖励存入和提取（从新到旧）                   |
| `GET`  | [`/v1/wallets/{walletId}/rewards`](/en/api-reference/rewards/wallet-rewards)                            | 某个 wallet 的持仓；传入 `assetId` 可获取单一资产 |
| `GET`  | [`/v1/wallets/{walletId}/rewards/assets`](/en/api-reference/rewards/wallet-reward-assets)               | 某个 wallet 中符合奖励条件的资产及各策略的 APY      |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit`](/en/api-reference/rewards/deposit)                           | 将一种资产存入 earn 策略                    |
| `POST` | [`/v1/wallets/{walletId}/rewards/deposit/network-fee`](/en/api-reference/rewards/deposit-network-fee)   | 预览存入的网络手续费                         |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw`](/en/api-reference/rewards/withdraw)                         | 从持仓中提取一笔净金额（或 `"max"`）             |
| `POST` | [`/v1/wallets/{walletId}/rewards/withdraw/network-fee`](/en/api-reference/rewards/withdraw-network-fee) | 预览提取的网络手续费                         |

## FAQ

<AccordionGroup>
  <Accordion title="存入需要付费吗？">
    不需要。存入是免费的。唯一的手续费是您所赚取利息的一小部分——绝不会动用您的存入金额。
  </Accordion>

  <Accordion title="我什么时候开始赚取收益？">
    一旦您的存入在链上结算，它就会开始全天候持续产生收益。
  </Accordion>

  <Accordion title="提取有多快？">
    它会立即开始，并在不久后于链上结算。完成时您会立即收到通知。
  </Accordion>

  <Accordion title="Regulated 和 DeFi 有什么区别？">
    Regulated 会通过受监管、更为稳健的提供方（Fija，位于 Ethereum）来路由您的资金。DeFi 使用 Aave——一个成熟的大型借贷协议，可在更多网络上使用。两者都能产生收益——关键在于您更偏好哪条路径。
  </Accordion>

  <Accordion title="我拿回的会比投入的少吗？">
    您的存入金额绝不会被收取手续费，您可保留利息减去 Blockradar 一小部分份额后的金额。费率是浮动的，且链上协议存在风险，因此回报无法保证——但平台手续费绝不会触及您的本金。
  </Accordion>

  <Accordion title="“全部提取”会做什么？">
    它会取出该持仓中的全部资金——您的存入金额加全部已赚取的利息——并将其关闭。您可以随时重新开始一笔新的存入。
  </Accordion>

  <Accordion title="为什么一笔新的 $0.20 存入有时会显示为 $0.199999？">
    这是底层协议一个微小的舍入小问题（不到一美分的零头），并非手续费。它会自行抹平，并且随着利息开始累积，您的余额会很快超过您的存入金额。
  </Accordion>
</AccordionGroup>

## 支持

* **电子邮件**：[support@blockradar.co](mailto:support@blockradar.co)