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

# API 集成

> LI.FI Earn Data API 的完整参考。涵盖所有端点、查询参数、响应模式、分页以及错误处理。

本指南涵盖 Earn Data API 中的每个端点，并提供完整的参数文档和响应示例。Earn Data API 负责金库发现、分析以及投资组合追踪。若需执行存入和提取操作，请参阅 [Composer API 集成指南](/composer/guides/api-integration)。

***

## Base URL

```
https://earn.li.fi
```

所有端点均以 `/v1/` 为前缀。

<Note>
  Earn Data API 与 Composer 使用**不同的 base URL**。Earn Data API 端点使用 `https://earn.li.fi`，而 Composer 端点（例如 `GET /v1/quote`）使用 `https://li.quest`。详情请参阅[概览](/earn/overview#the-two-layers)。
</Note>

***

## API 概览

| 端点                                         | 描述            |
| ------------------------------------------ | ------------- |
| `GET /v1/vaults`                           | 列出金库，支持过滤和分页  |
| `GET /v1/vaults/:chainId/:address`         | 获取单个金库的完整详情   |
| `GET /v1/chains`                           | 列出拥有活跃金库的链    |
| `GET /v1/protocols`                        | 列出拥有活跃金库的协议   |
| `GET /v1/portfolio/:userAddress/positions` | 获取用户的 DeFi 持仓 |

***

## 身份验证

Earn Data API 使用与 LI.FI API 其余部分相同的身份验证方式。通过 `x-lifi-api-key` 请求头传递你的 API key：

```bash theme={"system"}
curl -X GET 'https://earn.li.fi/v1/vaults' \
  --header 'x-lifi-api-key: YOUR_API_KEY'
```

API key 通过 [LI.FI Partner Portal](https://li.fi/plans/) 创建。完整详情请参阅[身份验证](/api-reference/authentication)。

***

## 速率限制

Earn Data API 端点的默认速率限制为每个 API key **每分钟 50 次请求**。

如果你需要更高的限制，请通过 [LI.FI Partner Portal](https://li.fi/plans/) 联系我们的团队。

如果超出限制，你将收到 `429 Too Many Requests` 响应。有关速率限制请求头和最佳实践的详情，请参阅[速率限制](/api-reference/rate-limits)。

***

## 列出金库

```
GET /v1/vaults
```

返回金库的分页列表，支持可选的过滤和排序。

### 查询参数

| 参数                    | 类型        | 是否必需 | 默认值  | 描述                                                   |
| --------------------- | --------- | ---- | ---- | ---------------------------------------------------- |
| `chainId`             | `integer` | 否    | —    | 按 EVM chain ID 过滤（例如 Base 为 `8453`，Ethereum 为 `1`）   |
| `asset`               | `string`  | 否    | —    | 按底层代币符号过滤（例如 `"USDC"`、`"ETH"`）                       |
| `protocol`            | `string`  | 否    | —    | 按协议名称过滤（例如 `"morpho-v1"`、`"aave-v3"`）                |
| `minTvlUsd`           | `number`  | 否    | —    | 以美元计的最低 TVL（例如 `1000000` 表示 100 万美元以上）               |
| `isTransactional`     | `boolean` | 否    | —    | 传入 `"true"` 仅返回支持通过 Composer 进行程序化存入和提取的金库           |
| `isRedeemable`        | `boolean` | 否    | —    | 传入 `"true"` 仅返回当前支持提取的金库                             |
| `isComposerSupported` | `boolean` | 否    | —    | 传入 `"true"` 仅返回由 LI.FI Composer 完全支持、可进行端到端跨链存入流程的金库 |
| `sortBy`              | `string`  | 否    | —    | 排序方式：`"apy"`（从高到低）或 `"tvl"`（从高到低）                    |
| `limit`               | `integer` | 否    | `50` | 每页结果数（1–100）                                         |
| `cursor`              | `string`  | 否    | —    | 来自上一次响应 `nextCursor` 的分页游标                           |

### 示例请求

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X GET 'https://earn.li.fi/v1/vaults?chainId=8453&asset=USDC&sortBy=apy&minTvlUsd=100000&limit=10'
  ```

  ```ts TypeScript theme={"system"}
  const params = new URLSearchParams({
    chainId: '8453',
    asset: 'USDC',
    sortBy: 'apy',
    minTvlUsd: '100000',
    limit: '10',
  });

  const response = await fetch(`https://earn.li.fi/v1/vaults?${params}`);
  const { data, nextCursor, total } = await response.json();
  ```
</CodeGroup>

### 响应

```json theme={"system"}
{
  "data": [
    {
      "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
      "network": "base",
      "chainId": 8453,
      "slug": "morpho-base-usdc-0x7bfa",
      "name": "Morpho USDC Vault",
      "description": "Optimized USDC lending vault on Morpho",
      "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": [
        {
          "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
          "symbol": "mUSDC",
          "decimals": 18,
          "priceUsd": "1.02"
        }
      ],
      "rewardTokens": [],
      "tags": ["stablecoin", "lending"],
      "analytics": {
        "apy": {
          "base": 0.0534,
          "reward": null,
          "total": 0.0534
        },
        "apy1d": 0.0521,
        "apy7d": 0.0538,
        "apy30d": 0.0545,
        "tvl": {
          "usd": "12500000.00",
          "native": "12500000000000"
        },
        "updatedAt": "2026-03-31T14:30:00.000Z"
      },
      "caps": {
        "totalCap": "50000000000000",
        "maxCap": "100000000000000"
      },
      "timeLock": 0,
      "kyc": false,
      "isTransactional": true,
      "isRedeemable": true,
      "depositPacks": [
        { "name": "morpho-deposit", "stepsType": "instant" }
      ],
      "redeemPacks": [
        { "name": "morpho-redeem", "stepsType": "instant" }
      ],
      "syncedAt": "2026-03-31T14:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6MTAwfQ",
  "total": 47
}
```

<Note>
  响应中的某些字段可能为 `null`：`description`（约 70% 的金库缺失）、`apy.base`、`apy.reward`、`apy1d`、`apy7d` 以及 `caps`。请始终在你的集成中处理可为空的字段。
</Note>

### 分页

该 API 使用基于游标的分页。要获取下一页，请将响应中的 `nextCursor` 值作为 `cursor` 查询参数传入：

```ts TypeScript theme={"system"}
// Fetch all vaults across pages
let cursor: string | undefined;
const allVaults = [];

do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('cursor', cursor);

  const response = await fetch(`https://earn.li.fi/v1/vaults?${params}`);
  const { data, nextCursor } = await response.json();

  allVaults.push(...data);
  cursor = nextCursor;
} while (cursor);
```

***

## 按链和地址获取金库

```
GET /v1/vaults/:chainId/:address
```

返回单个金库的完整详情。

### 路径参数

| 参数        | 类型        | 是否必需 | 描述                          |
| --------- | --------- | ---- | --------------------------- |
| `chainId` | `integer` | 是    | EVM chain ID                |
| `address` | `string`  | 是    | 金库合约地址（以 0x 为前缀，40 个十六进制字符） |

### 示例请求

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X GET 'https://earn.li.fi/v1/vaults/8453/0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A'
  ```

  ```ts TypeScript theme={"system"}
  const chainId = 8453;
  const address = '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A';

  const response = await fetch(`https://earn.li.fi/v1/vaults/${chainId}/${address}`);
  const vault = await response.json();
  ```
</CodeGroup>

### 响应

返回单个 [NormalizedVault](/earn/how-it-works#the-normalizedvault-schema) 对象（与列表端点中的项目结构相同）。

### 错误

| 状态码   | 描述               |
| ----- | ---------------- |
| `400` | chain ID 或地址格式无效 |
| `404` | 未找到金库            |

***

## 列出 Earn 支持的链

```
GET /v1/chains
```

返回至少拥有一个 Earn 金库可用的链列表。基于当前的金库数据得出。

<Note>
  \*\*限定于 LI.FI Earn。\*\*此端点仅返回 Earn 当前已索引金库的链，它并不是 LI.FI 平台所支持的所有链的通用列表。如果你要集成 **Swaps 或 Bridges**（通过 LI.FI SDK 或主 API），请改用 [`GET https://li.quest/v1/chains`](/api-reference/get-information-about-all-currently-supported-chains)。
</Note>

### 示例请求

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X GET 'https://earn.li.fi/v1/chains'
  ```

  ```ts TypeScript theme={"system"}
  const response = await fetch('https://earn.li.fi/v1/chains');
  const chains = await response.json();
  ```
</CodeGroup>

### 响应

```json theme={"system"}
[
  {
    "name": "Ethereum",
    "chainId": 1,
    "networkCaip": "eip155:1"
  },
  {
    "name": "Base",
    "chainId": 8453,
    "networkCaip": "eip155:8453"
  },
  {
    "name": "Arbitrum One",
    "chainId": 42161,
    "networkCaip": "eip155:42161"
  }
]
```

***

## 列出支持的协议

```
GET /v1/protocols
```

返回至少拥有一个金库可用的协议列表。基于当前的金库数据得出。

### 示例请求

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X GET 'https://earn.li.fi/v1/protocols'
  ```

  ```ts TypeScript theme={"system"}
  const response = await fetch('https://earn.li.fi/v1/protocols');
  const protocols = await response.json();
  ```
</CodeGroup>

### 响应

```json theme={"system"}
[
  {
    "name": "Morpho",
    "logoUri": "https://example.com/morpho-logo.png",
    "url": "https://morpho.org"
  },
  {
    "name": "Aave V3",
    "logoUri": "https://example.com/aave-logo.png",
    "url": "https://aave.com"
  },
  {
    "name": "Euler",
    "logoUri": "https://example.com/euler-logo.png",
    "url": "https://www.euler.finance"
  }
]
```

***

## 获取用户投资组合持仓

```
GET /v1/portfolio/:userAddress/positions
```

返回用户在所有支持的协议中的 DeFi 持仓。

### 路径参数

| 参数            | 类型       | 是否必需 | 描述                           |
| ------------- | -------- | ---- | ---------------------------- |
| `userAddress` | `string` | 是    | 用户的钱包地址（以 0x 为前缀，40 个十六进制字符） |

### 示例请求

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X GET 'https://earn.li.fi/v1/portfolio/0x1234567890abcdef1234567890abcdef12345678/positions'
  ```

  ```ts TypeScript theme={"system"}
  const userAddress = '0x1234567890abcdef1234567890abcdef12345678';

  const response = await fetch(
    `https://earn.li.fi/v1/portfolio/${userAddress}/positions`
  );
  const { positions } = await response.json();
  ```
</CodeGroup>

### 响应

```json theme={"system"}
{
  "positions": [
    {
      "chainId": 1,
      "address": "0xa17581a9e3356d9a858b789d68b4d866e593ae94",
      "protocolName": "aave-v3",
      "asset": {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6
      },
      "balanceUsd": "1523.45",
      "balanceNative": "1523450000"
    },
    {
      "chainId": 8453,
      "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
      "protocolName": "morpho",
      "asset": {
        "address": "0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A",
        "name": "Morpho USDC Vault",
        "symbol": "mUSDC",
        "decimals": 18
      },
      "balanceUsd": "5000.00",
      "balanceNative": "4901960784313725490196"
    }
  ]
}
```

<Note>
  每个持仓的 `address`、`protocolName` 和 `balanceUsd` 字段可能为 `null`。当无法确定持仓的合约地址时，`address` 为 null。当无法识别协议时，`protocolName` 为 null。当资产没有可用的美元价格时，`balanceUsd` 为 null。请始终在你的集成中处理这些情况。
</Note>

### 错误

| 状态码   | 描述       |
| ----- | -------- |
| `400` | 钱包地址格式无效 |

***

## 错误处理

所有 Earn Data API 端点均返回标准的 HTTP 错误响应：

| 状态码   | 含义                      |
| ----- | ----------------------- |
| `200` | 成功                      |
| `400` | 请求错误。参数无效（请查看错误消息了解详情）。 |
| `404` | 未找到资源（金库不存在）            |
| `500` | 服务器内部错误                 |

错误响应包含一条描述问题的消息：

```json theme={"system"}
{
  "statusCode": 400,
  "message": "Invalid Ethereum address"
}
```

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="发现与存入配方" icon="book" href="/earn/recipes/discover-and-deposit">
    将 Earn 发现与 Composer 存入相结合的端到端配方
  </Card>

  <Card title="Composer API 指南" icon="code" href="/composer/guides/api-integration">
    通过 Composer API 执行存入和提取操作
  </Card>
</CardGroup>