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

# Balances & Positions

> Track user positions and lifecycle states across yields

## What Balances Represent

The Balances API provides a **lifecycle-aware** view of user positions. Unlike simple token balances, Yield.xyz balances reflect where assets are in the yield lifecycle — active, entering, exiting, or claimable.

This enables accurate portfolio UX, operational reporting, and next-action prompts without protocol-specific state management.

***

## Lifecycle States

<Tabs>
  <Tab title="available">
    **Active position earning yield**

    * Currently staked or deposited
    * Actively earning rewards
    * Can initiate exit at any time
  </Tab>

  <Tab title="preparing">
    **Entering position**

    * Deposit confirmed on-chain
    * Waiting for protocol activation
    * Example: Ethereum validator activation queue
  </Tab>

  <Tab title="unstaking">
    **Exiting position**

    * Withdrawal initiated
    * In unbonding/cooldown period
    * Cannot be cancelled on most protocols
  </Tab>

  <Tab title="unlocked">
    **Ready to claim**

    * Unbonding complete
    * Requires final claim transaction
    * No longer earning yield
  </Tab>

  <Tab title="rewards">
    **Claimable rewards**

    * Earned but not yet claimed
    * May require explicit claim action
    * Some yields auto-compound instead
  </Tab>
</Tabs>

<Info>
  Not all yields use all states. Liquid staking (Lido, Rocket Pool) typically has only `available` — no cooldowns. Native staking (Cosmos, Polkadot) uses the full lifecycle.
</Info>

***

## Pending Actions

When a position has actions the user can or must take, the API includes `pendingActions`:

| Action           | When it appears                    |
| ---------------- | ---------------------------------- |
| `CLAIM_REWARDS`  | Rewards ready to claim             |
| `CLAIM_UNSTAKED` | Unbonding complete, funds ready    |
| `WITHDRAW`       | Vault withdrawal ready to finalize |
| `REDELEGATE`     | Validator change available         |

<Tip>
  Use `pendingActions` to surface CTAs in your UI — "Claim 0.5 ETH rewards" or "Complete withdrawal".
</Tip>

***

## Portfolio Endpoints

Two endpoints power position tracking:

### Single yield balances

Fetch a user's position in a specific yield:

```bash theme={null}
GET https://api.yield.xyz/v1/yields/{yieldId}/balances?address=0x...
```

Returns all balance types for that yield — available, rewards, unstaking, etc.

**Example:**

```bash theme={null}
curl "https://api.yield.xyz/v1/yields/ethereum-eth-lido-staking/balances?address=0x1234..." \
  -H "x-api-key: 9a4ed..."
```

### Aggregate balances

Fetch positions across multiple yields and networks in one request:

```bash theme={null}
POST https://api.yield.xyz/v1/yields/balances
```

**Request body:**

```json theme={null}
{
  "addresses": [
    { "address": "0x1234...", "network": "ethereum" },
    { "address": "cosmos1abc...", "network": "cosmos" }
  ]
}
```

**Example:**

```bash theme={null}
curl -X POST "https://api.yield.xyz/v1/yields/balances" \
  -H "x-api-key: 9a4ed..." \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      { "address": "0x1234...", "network": "ethereum" },
      { "address": "cosmos1abc...", "network": "cosmos" }
    ]
  }'
```

<Tip>
  Use the aggregate endpoint to power portfolio dashboards. One request covers all networks and yields.
</Tip>

***

## Position Origins

Balances may reflect positions created through Yield.xyz or positions that existed before integration.

<Tabs>
  <Tab title="Yield.xyz-originated">
    Positions created via Yield.xyz actions.

    * Full lifecycle tracking from entry
    * Reward accrual data from entry date
    * Included in baseline DataKit
  </Tab>

  <Tab title="Non-originating">
    Positions created outside Yield.xyz (imported wallets, prior activity).

    * Balance states visible
    * Historical reward data may require Premium DataKit
    * Actions still work normally
  </Tab>
</Tabs>

***

## Balance Response Structure

Each balance includes:

| Field            | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `type`           | Lifecycle state (available, rewards, unstaking, etc.) |
| `amount`         | Token amount in human-readable format                 |
| `token`          | Token metadata (symbol, decimals, address)            |
| `pricePerShare`  | For yield-bearing tokens (stETH, aUSDC)               |
| `date`           | Timestamp of the balance snapshot                     |
| `pendingActions` | Available management actions                          |

***

## Common Patterns

<AccordionGroup>
  <Accordion title="Portfolio dashboard">
    Use aggregate balances to display all positions across networks. Group by network or yield type for clean UX.
  </Accordion>

  <Accordion title="Claimable rewards">
    Filter for `type: rewards` with `amount > 0` to highlight claimable rewards.
  </Accordion>

  <Accordion title="Pending withdrawals">
    Check `type: unstaking` or `type: unlocked` to show in-progress and completed exits.
  </Accordion>

  <Accordion title="Cooldown timers">
    Use `unlockDate` (where available) to display remaining unbonding time.
  </Accordion>
</AccordionGroup>

***

## API Reference

<CardGroup cols={2}>
  <Card title="Yield Balances" icon="wallet" href="/api-reference/YieldsController_getYieldBalances">
    GET /v1/yields/{yieldId}/balances
  </Card>

  <Card title="Aggregate Balances" icon="layer-group" href="/api-reference/YieldsController_getAggregateBalances">
    POST /v1/yields/balances
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Fees" icon="percent" href="/documentation/core-concepts/fees">
    Understand fee structures and monetization
  </Card>

  <Card title="Tracking Balances Guide" icon="book" href="/guides/integration-patterns/tracking-balances">
    Detailed implementation patterns
  </Card>
</CardGroup>