> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Earn 的工作原理

> Earn Data API 如何聚合并标准化金库数据：NormalizedVault 模式、交易能力以及数据的时效性。

本页面介绍 Earn Data API 如何跨协议聚合金库数据，将其标准化为统一的模式，并保持数据的时效性。

***

## 架构概览

Earn Data API 是一个位于协议数据与你的应用之间的**数据聚合层**。它负责：

1. \*\*摄取。\*\*从支持的各个协议的多个数据源获取金库数据。
2. \*\*标准化。\*\*将协议特有的格式转换为统一的 `NormalizedVault` 模式。
3. \*\*能力解析。\*\*确定哪些金库支持通过 Composer 进行存入和提取。
4. \*\*服务。\*\*通过支持过滤、排序和分页的 REST API 暴露标准化后的数据。

***

## 数据时效性

Earn Data API 运行一个后台同步流水线，以保持金库数据的最新状态：

| 数据              | 刷新频率    |
| --------------- | ------- |
| 金库元数据、APY 和 TVL | 每 15 分钟 |
| 交易能力（存入/提取支持）   | 每 2 分钟  |

这意味着 APY 和 TVL 数据最多滞后 15 分钟，交易能力数据最多滞后 2 分钟。

***

## NormalizedVault 模式

Earn API 中的每个金库都遵循相同的模式，无论它来自哪个协议或数据提供方。这是核心的数据结构：

```json theme={"system"}
{
  "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
  "network": "base",
  "chainId": 8453,
  "slug": "morpho-base-usdc-0x7bfa",
  "name": "Morpho USDC Vault",
  "description": "Optimized USDC lending vault on Morpho",  // optional, may be absent
  "protocol": {
    "name": "Morpho",
    "logoUri": "https://example.com/morpho-logo.png",
    "url": "https://morpho.org"
  },
  "underlyingTokens": [
    {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6,
      "weight": 1.0
    }
  ],
  "lpTokens": [],                  // typically empty; use vault `address` as toToken for Composer
  "rewardTokens": [],             // optional, may be absent
  "tags": ["stablecoin", "lending"],
  "analytics": {
    "apy": {
      "base": 0.0534,             // nullable, can be null
      "reward": null,             // nullable, can be null
      "total": 0.0534
    },
    "apy1d": 0.0521,              // nullable, can be null
    "apy7d": 0.0538,              // nullable, can be null
    "apy30d": 0.0545,
    "tvl": {
      "usd": "12500000.00",
      "native": "12500000000000"  // optional, may be absent
    },
    "updatedAt": "2026-03-31T14:30:00.000Z"
  },
  "caps": {                       // optional, may be absent
    "totalCap": "50000000000000",
    "maxCap": "100000000000000"
  },
  "timeLock": 0,                  // optional, may be absent
  "kyc": false,                   // optional, may be absent
  "isTransactional": true,
  "isRedeemable": true,
  "depositPacks": [
    { "name": "morpho-deposit", "stepsType": "instant" }
  ],
  "redeemPacks": [
    { "name": "morpho-redeem", "stepsType": "instant" }
  ],
  "syncedAt": "2026-03-31T14:30:00.000Z"
}
```

### 关键字段

| 字段                                     | 类型               | 描述                                                           |
| -------------------------------------- | ---------------- | ------------------------------------------------------------ |
| `address`                              | `string`         | 金库合约地址                                                       |
| `network`                              | `string`         | 网络名称（例如 `"base"`、`"ethereum"`）                               |
| `chainId`                              | `number`         | EVM chain ID                                                 |
| `slug`                                 | `string`         | 跨提供方的唯一金库标识符                                                 |
| `protocol`                             | `object`         | 协议元数据（名称、logo、URL）                                           |
| `underlyingTokens`                     | `array`          | 金库接受存入的代币（多资产金库带有可选的 weight）                                 |
| `lpTokens`                             | `array`          | 代表金库持仓的代币。通常为空；请使用金库的 `address` 字段作为 Composer 存入的 `toToken`。 |
| `rewardTokens`                         | `array?`         | 额外的奖励代币（例如治理代币）。可选，可能缺失。                                     |
| `analytics.apy`                        | `object`         | 当前 APY 明细：`base`（可为空）、`reward`（可为空）、`total`                  |
| `analytics.apy1d` / `apy7d` / `apy30d` | `number \| null` | 1 天、7 天和 30 天的滚动平均 APY。可为空，对于新金库可能为 `null`。                  |
| `analytics.tvl`                        | `object`         | 锁仓总价值。`usd` 始终存在；`native` 为可选。                               |
| `isTransactional`                      | `boolean`        | 是否可通过 Composer 存入                                            |
| `isRedeemable`                         | `boolean`        | 是否可通过 Composer 提取                                            |
| `depositPacks` / `redeemPacks`         | `array`          | Composer zap-pack 条目，描述可用的存入/提取方法                            |
| `description`                          | `string?`        | 金库描述。可选，可能缺失。                                                |
| `caps`                                 | `object?`        | 存入上限（`totalCap`、`maxCap`）。可选，可能缺失。                           |
| `timeLock`                             | `number?`        | 锁定周期，以秒为单位（0 = 无锁定）。可选，可能缺失。                                 |
| `kyc`                                  | `boolean?`       | 金库是否需要 KYC。可选，可能缺失。                                          |

### 交易能力

`isTransactional` 和 `isRedeemable` 标志派生自 Composer 的 zap-pack 数据，而非金库本身。它告诉你 LI.FI 基础设施是否能为该金库执行存入和提取操作：

* **`isTransactional: true`** 表示你可以使用 [Composer 的报价端点](/composer/guides/api-integration)，将该金库的合约地址作为 `toToken` 进行存入。
* **`isRedeemable: true`** 表示你可以使用 Composer，将该金库的合约地址作为 `fromToken` 进行提取。

请使用这些标志来控制你的 UI。例如，对于 `isTransactional` 为 `false` 的金库，隐藏"存入"按钮。

***

## 支持的协议和链

Earn Data API 聚合了来自 20 多个协议、跨越 20 条链的金库。使用发现端点查看当前已索引的内容：

* `GET /v1/chains` — 返回至少拥有一个活跃金库的所有链
* `GET /v1/protocols` — 返回至少拥有一个活跃金库的所有协议

这些端点反映了来自同步流水线的实时数据，并将随着新协议和新链的接入而增长。

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/earn/quickstart">
    在 5 分钟内完成你的首次 Earn API 调用
  </Card>

  <Card title="API 集成指南" icon="code" href="/earn/guides/api-integration">
    包含所有参数和响应结构的完整端点参考
  </Card>
</CardGroup>