Balances and positions

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

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

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.

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.

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.

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; for indexed historical data more broadly, see Platform › Data.

Next steps

Actions

Execute enter, exit, and manage actions, including a balance’s pending actions.

Tracking balances

Implementation patterns for portfolio and position UX.

Rewards and history

How rewards are represented, and current versus historical APY and TVL.

API reference

Full request and response schemas for balance endpoints.