SKILL

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.

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

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

Example Response:

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

# 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

curl "https://api.yield.xyz/v1/networks" -H "x-api-key: $YIELD_API_KEY"

Step 5: List Providers

Endpoint: GET /v1/providers

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