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

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

# SKILL

# 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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "queries": [
    {
      "yieldId": "ethereum-eth-lido-staking",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "ethereum"
    }
  ]
}
```

**cURL Example:**

```bash theme={null}
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:

```json theme={null}
{
  "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):**

```json theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
```

**cURL Example:**

```bash theme={null}
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    |

```bash theme={null}
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:

```json theme={null}
{
  "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.