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

> Search and discover yield opportunities across 2,900+ options on 80+ blockchain networks using the Yield.xyz API. Use when the user wants to find, list, filter, compare, or browse staking, lending, vault, restaking, or DeFi yield opportunities by network, token, provider, type, or APY.

# SKILL

# Find Yields

Discover and search yield opportunities across the Yield.xyz platform. This skill enables an AI agent to query the full catalog of 2,900+ yield opportunities spanning staking, lending, vaults, restaking, liquid staking, and more across 80+ blockchain networks.

## When to Use

Activate this skill when the user asks to:

* Find or list yield opportunities (e.g., "What yields are available on Ethereum?")
* Filter yields by network, token, provider, type, or APY
* Compare yield rates across protocols or networks
* Search for a specific yield by name or ID
* Discover the best staking or DeFi opportunities for a given token
* List supported networks or providers

## Authentication

All requests require an API key in the `x-api-key` header:

```
x-api-key: YOUR_API_KEY
```

The API key is obtained from [https://dashboard.yield.xyz](https://dashboard.yield.xyz). Store it in an environment variable (e.g., `YIELD_API_KEY`).

## Base URL

```
https://api.yield.xyz/v1
```

Staging environment: `https://api.staging.yield.xyz/v1`

## Step-by-Step Instructions

### Step 1: List Yield Opportunities

**Endpoint:** `GET /v1/yields`

**Query Parameters:**

| Parameter           | Type      | Description                                                                                         |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `offset`            | number    | Pagination offset (default: 0)                                                                      |
| `limit`             | number    | Items per page (1-100, default: 20)                                                                 |
| `network`           | string    | Filter by single network (e.g., `ethereum`, `solana`, `arbitrum`)                                   |
| `networks`          | string    | Filter by multiple networks (comma-separated)                                                       |
| `type`              | string    | Filter by yield type: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset` |
| `types`             | string\[] | Filter by multiple yield types                                                                      |
| `token`             | string    | Filter by token symbol or address                                                                   |
| `inputToken`        | string    | Filter by input token symbol or address                                                             |
| `provider`          | string    | Filter by provider ID                                                                               |
| `providers`         | string\[] | Filter by multiple provider IDs                                                                     |
| `search`            | string    | Search by yield name                                                                                |
| `yieldId`           | string    | Filter by specific yield ID (e.g., `ethereum-eth-lido-staking`)                                     |
| `yieldIds`          | string\[] | Filter by multiple yield IDs (max 100)                                                              |
| `hasCooldownPeriod` | boolean   | Filter by cooldown period existence                                                                 |
| `hasWarmupPeriod`   | boolean   | Filter by warmup period existence                                                                   |
| `sort`              | string    | Sort order: `statusEnterAsc`, `statusEnterDesc`, `statusExitAsc`, `statusExitDesc`                  |

**Example Request:**

```bash theme={null}
curl "https://api.yield.xyz/v1/yields?network=ethereum&type=staking&limit=5" \
  -H "x-api-key: $YIELD_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "items": [
    {
      "id": "ethereum-eth-lido-staking",
      "token": { "symbol": "ETH", "name": "Ethereum", "network": "ethereum" },
      "rewardRate": 0.035,
      "rewardType": "APY",
      "metadata": {
        "provider": { "name": "Lido" },
        "type": "staking"
      },
      "status": { "enter": true, "exit": true }
    }
  ],
  "total": 150,
  "offset": 0,
  "limit": 5
}
```

### Step 2: Filter and Refine Results

Use combination filters to narrow results:

* **By network + type:** `?network=ethereum&type=lending`
* **By token:** `?token=USDC` or `?inputToken=ETH`
* **By provider:** `?provider=aave` or `?providers=aave,compound`
* **By multiple networks:** `?networks=ethereum,arbitrum,base`
* **Search by name:** `?search=lido`

### Step 3: Paginate Through All Results

```bash theme={null}
# Page 1
curl "https://api.yield.xyz/v1/yields?limit=100&offset=0" -H "x-api-key: $YIELD_API_KEY"

# Page 2
curl "https://api.yield.xyz/v1/yields?limit=100&offset=100" -H "x-api-key: $YIELD_API_KEY"
```

Continue until `offset + limit >= total`.

### Step 4: List Available Networks

**Endpoint:** `GET /v1/networks`

```bash theme={null}
curl "https://api.yield.xyz/v1/networks" -H "x-api-key: $YIELD_API_KEY"
```

### Step 5: List Providers

**Endpoint:** `GET /v1/providers`

```bash theme={null}
curl "https://api.yield.xyz/v1/providers?limit=50" -H "x-api-key: $YIELD_API_KEY"
```

## Aggregation Patterns

When the user asks "What are the best yields for ETH?", follow this pattern:

1. Query yields filtered by token: `GET /v1/yields?token=ETH&limit=100`
2. Sort results client-side by `rewardRate` descending
3. Present top results with yield ID, provider, type, APY/APR, and network

When asked to compare across networks:

1. Query each network: `GET /v1/yields?network=ethereum&token=USDC` then `?network=arbitrum&token=USDC`
2. Merge and sort by reward rate
3. Present a comparison table

## Error Handling

| Status Code | Meaning                 | Action                                         |
| ----------- | ----------------------- | ---------------------------------------------- |
| 400         | Invalid parameters      | Check parameter values and types               |
| 401         | Invalid/missing API key | Verify `x-api-key` header                      |
| 429         | Rate limited            | Wait for `retry-after` seconds, then retry     |
| 500         | Server error            | Retry with exponential backoff (max 3 retries) |

## Edge Cases

* **Empty results:** If no yields match filters, the API returns `{"items": [], "total": 0}`. Suggest broadening filters.
* **Deprecated yields:** Some yields may have `status.enter: false`. These cannot accept new deposits but may still allow exits.
* **Yield IDs are composite:** Format is `{network}-{token}-{provider}-{type}` (e.g., `ethereum-eth-lido-staking`).
* **APY vs APR:** Check the `rewardType` field. Staking yields with auto-compounding show APY; manual-claim yields show APR.
* **Rate limits vary by plan:** Free (10 req/s), Starter (50 req/s), Pro (200 req/s), Enterprise (custom).