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

# Balances and positions

> Read what an address holds in a yield through its balances, and act on the pending actions each one exposes.

The Earn API has no single object called a position. A position is the set of balances an address holds in one yield; each balance is one state of that position, such as active and earning, or exiting and cooling down. The unit you read and act on is the balance.

Each balance also lists the actions the user can take on it next, such as claiming rewards or withdrawing once a cooldown ends. Together, the balances show where a user's funds are at every step from deposit to withdrawal and what it takes to get them back.

## Balance types

Each `BalanceDto` has a `type`:

| `type` | Meaning |
| - | - |
| `active` | Deployed and earning (or ready to earn) |
| `entering` | Transaction sent or in flight, not yet active |
| `exiting` | Cooling down, or being unstaked |
| `withdrawable` | Exited and ready to claim |
| `claimable` | Rewards or profits ready to claim |
| `locked` | Protocol-constrained, for example vesting |

Not every yield produces every type. A liquid staking yield with no cooldown may only ever return `active`. Whether a given balance is currently generating yield is its own field, `isEarning`, rather than something to infer from `type`.

## What a balance contains

| Field | Description |
| - | - |
| `address` | Wallet that owns this balance |
| `type` | Lifecycle state, from the table above |
| `amount` / `amountRaw` | Value in token units / smallest denomination |
| `amountUsd` | USD estimate of `amount` (see below) |
| `token` | The asset: symbol, decimals, network, address |
| `isEarning` | Whether this balance is currently generating yield |
| `pendingActions` | Manage or exit actions available on this balance right now |
| `validator` / `validators` | Validator(s) this balance is staked with, for validator-based yields |
| `shareAmount` / `shareAmountRaw` / `shareToken` | Share-token accounting, for share-based yields (vaults) |
| `feeConfigurationId` | Fee configuration applied to this balance, if any |
| `date` | Date relevant to this state, for example when a cooldown completes |
| `priceRange` | Price bounds, for concentrated liquidity positions |
| `tokenId` | NFT token ID, for concentrated liquidity positions |

`validator(s)`, `shareAmount` and `shareToken`, and `priceRange` and `tokenId` only appear on the yield types they apply to. Not every yield returns every field.

The response for one yield, `YieldBalancesDto`, wraps this: a `yieldId`, its `balances[]`, an optional `outputTokenBalance` (the balance in the yield's output token, where one exists), and an optional `rewardRate` (the personalized reward rate for this position).

## Pending actions

A `pendingActions` entry describes one manage or exit step you can take on that balance right now, such as claiming rewards or completing a withdrawal once cooldown ends. Each entry has an `intent` (`enter`, `exit` or `manage`), a `type` such as `CLAIM_REWARDS` or `WITHDRAW`, an opaque server-generated `passthrough`, an optional `arguments` schema for any input the action needs (for example, selecting a new validator), and an `amount` when applicable. Field details are in [Pending actions](/api-reference/earn-objects.md#pending-actions).

To execute one, send its `type` as `action` and its `passthrough` unchanged to `POST /v1/actions/manage`, along with the `yieldId`, `address`, and any `arguments` its schema calls for. See [Actions](/documentation/earn/core-concepts/actions.md#manage-actions).

## Fetching balances

| Endpoint | Use it for |
| - | - |
| `POST /v1/yields/{yieldId}/balances` | Every balance an address holds in one specific yield |
| `POST /v1/yields/balances` | Balances across multiple yields and networks in one call, for portfolio views |

Both take an `address` and take network from context (from the yield, for the single-yield endpoint; per query, for the multi-yield endpoint), plus an optional `arguments` object for protocol-specific queries. The aggregate endpoint accepts up to 25 queries per request. A query's `yieldId` is optional: omit it to scan a network, which checks the yields that address has previously used through Yield.xyz (plus a small built-in set), not every yield on the network. To read a balance in a yield the address has never used through Yield.xyz, name that `yieldId` explicitly. The response separates `items` (balances grouped by yield) from `errors` (per-yield failures). Scanned yields appear only with a non-zero balance; a yield you name explicitly is always returned, even when empty.

Both endpoints are project-scoped: the single-yield endpoint returns `400` for a yield not enabled on the calling project, and the aggregate endpoint returns balances only for enabled yields. Current balances are read live from the chain on each request, not from a cache.

## Display vs accounting

`amountUsd` is a price-derived estimate, `amount` multiplied by the token's resolved USD price. Treat it as a display value, not an accounting source of truth: it depends on price data being available for that token at query time.

Because coverage varies by protocol, do not assume a balance carries every optional field. Check for `validator` / `validators`, `shareAmount` / `shareToken`, and `priceRange` / `tokenId` before reading them, rather than assuming they are always present.

Balances are current holdings, not a time series. For historical APY and TVL, see [Rewards and history](/documentation/earn/core-concepts/rewards-history.md).

## Next steps

> **[Actions](/documentation/earn/core-concepts/actions.md)**
>
> Execute enter, exit, and manage actions, including a balance's pending actions.

> **[Tracking balances](/guides/earn/tracking-balances.md)**
>
> Implementation patterns for portfolio and position UX.

> **[Rewards and history](/documentation/earn/core-concepts/rewards-history.md)**
>
> How rewards are represented, and current versus historical APY and TVL.

> **[API reference](/api-reference/YieldsController_getYieldBalances.md)**
>
> Full request and response schemas for balance endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.