SKILL

Check yield portfolio balances and positions across multiple networks and protocols using the Yield.xyz API. Use when the user wants to view their staking balances, DeFi positions, rewards, unstaking status, or aggregate portfolio across all yield opportunities.

Check Portfolio

Retrieve and display user yield positions, balances, and rewards across multiple networks and protocols. This skill supports both single-yield balance queries and aggregate portfolio views.

When to Use

Activate this skill when the user asks to:

• Check their staking balance or position (e.g., “What’s my ETH staking balance?”)
• View portfolio across all yields and networks (e.g., “Show my yield portfolio”)
• Check rewards earned (e.g., “How much ATOM rewards do I have?”)
• Monitor unstaking progress (e.g., “Is my DOT unstaking complete?”)
• Track position lifecycle (staked, unstaking, claimable, etc.)
• Scan all positions for a wallet address

Authentication

x-api-key: YOUR_API_KEY

Base URL

https://api.yield.xyz/v1

Step-by-Step Instructions

Step 1: Get Aggregate Balances (Multi-Yield Portfolio)

Endpoint: POST /v1/yields/balances

Use this to scan multiple yields or entire networks for a user’s positions.

Request Body (BalancesRequestDto):

{
  "queries": [
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "ethereum"
    },
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "arbitrum"
    },
    {
      "address": "cosmos1abc...",
      "network": "cosmos"
    }
  ]
}

Chain scan (omit yieldId): When yieldId is omitted, all yields for that network are scanned.

Specific yield query:

{
  "queries": [
    {
      "yieldId": "ethereum-eth-lido-staking",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "ethereum"
    }
  ]
}

cURL Example:

curl -X POST "https://api.yield.xyz/v1/yields/balances" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "network": "ethereum"
      }
    ]
  }'

Response (BalancesResponseDto):

Only yields with non-zero balances are returned:

{
  "balances": [
    {
      "yieldId": "ethereum-eth-lido-staking",
      "token": { "symbol": "stETH", "network": "ethereum" },
      "balances": [
        {
          "type": "staked",
          "amount": "2500000000000000000",
          "pricePerShare": "1.001"
        }
      ]
    },
    {
      "yieldId": "ethereum-usdc-aave-v3-lending",
      "token": { "symbol": "aUSDC", "network": "ethereum" },
      "balances": [
        {
          "type": "staked",
          "amount": "5000000000"
        }
      ]
    }
  ],
  "errors": []
}

Step 2: Get Balances for a Specific Yield

Endpoint: POST /v1/yields/{yieldId}/balances

Request Body (YieldBalancesRequestDto):

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

cURL Example:

curl -X POST "https://api.yield.xyz/v1/yields/ethereum-eth-lido-staking/balances" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

Step 3: Interpret Balance Types

Balance Type	Description
staked	Currently active/staked amount earning yield
unstaking	Amount in cooldown period (not yet claimable)
unstaked	Cooldown complete, ready to claim
rewards	Accumulated rewards available to claim or restake
locked	Locked tokens (governance locks, vesting, etc.)
unlocking	Tokens in the unlock process
available	Available for withdrawal
claimable	Ready to be claimed

Step 4: Get User Action History

Endpoint: GET /v1/actions

Query Parameters:

Parameter	Type	Description
address	string	User wallet address
yieldId	string	Filter by yield
status	string	Filter by status

curl "https://api.yield.xyz/v1/actions?address=0x742d35..." \
  -H "x-api-key: $YIELD_API_KEY"

Aggregation Patterns

Full Portfolio View

To build a complete portfolio view:

1. Determine the user’s addresses per network
2. Send a batch query with all addresses:

{
  "queries": [
    { "address": "0xEvmAddress", "network": "ethereum" },
    { "address": "0xEvmAddress", "network": "arbitrum" },
    { "address": "0xEvmAddress", "network": "base" },
    { "address": "0xEvmAddress", "network": "optimism" },
    { "address": "0xEvmAddress", "network": "polygon" },
    { "address": "cosmos1...", "network": "cosmos" },
    { "address": "solanaAddr", "network": "solana" }
  ]
}

3. Process the response to build a summary:
   • Total value across all positions
   • Breakdown by network / protocol / yield type
   • Pending actions (rewards to claim, unstaking in progress)

Monitoring Unstaking Progress

1. Query balances for the specific yield
2. Look for unstaking balance type
3. Check the completionDate field (if available) for when cooldown ends
4. When unstaked > 0 and cooldown is complete, use the manage-position skill to claim

Rewards Summary

1. Aggregate query across all networks
2. Filter response for entries with rewards balance type
3. Present each yield with its claimable reward amount
4. Suggest claiming or restaking based on amount

Presenting Portfolio Data

Format portfolio information clearly:

Portfolio Summary for 0x742d...
=================================
Staked Positions:
  - Lido ETH Staking: 2.5 stETH (staked)
  - Aave V3 USDC (Ethereum): 5,000 aUSDC (lending)
  - Cosmos ATOM Staking: 100 ATOM (staked)

Rewards:
  - Cosmos ATOM: 1.5 ATOM available to claim

Unstaking:
  - Polkadot DOT: 50 DOT (completes in 14 days)

Error Handling

Status Code	Meaning	Action
400	Invalid parameters	Check address format matches network type
401	Unauthorized	Verify API key
429	Rate limited	Wait and retry
500	Server error	Retry with backoff; some individual yields may fail

Edge Cases

• No positions found: If the response contains no balances, the user has no active positions on the queried networks/yields. The API returns only non-zero balances.
• Partial failures: The aggregate endpoint may return errors for individual yields that failed to fetch. These should be reported but don’t block the rest of the results.
• EVM address reuse: The same EVM address works across Ethereum, Arbitrum, Base, Optimism, Polygon, etc. Send one query per network.
• Non-EVM addresses: Each non-EVM network has a different address format. Don’t reuse a Cosmos address for Solana queries.
• Deduplication: The API automatically deduplicates requests with the same yieldId + address + network. Specific yield queries take precedence over chain scans.
• Balance precision: Amounts are returned in base units (smallest denomination). Divide by 10^decimals for human-readable format.
• Rate limiting with large scans: Chain scans (no yieldId) are more expensive. For many networks, consider batching or using specific yield queries when possible.