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

available

Active position earning yield

• Currently staked or deposited
• Actively earning rewards
• Can initiate exit at any time

preparing

Entering position

• Deposit confirmed on-chain
• Waiting for protocol activation
• Example: Ethereum validator activation queue

unstaking

Exiting position

• Withdrawal initiated
• In unbonding/cooldown period
• Cannot be cancelled on most protocols

unlocked

Ready to claim

• Unbonding complete
• Requires final claim transaction
• No longer earning yield

rewards

Claimable rewards

• Earned but not yet claimed
• May require explicit claim action
• Some yields auto-compound instead

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.

---

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

Use pendingActions to surface CTAs in your UI — “Claim 0.5 ETH rewards” or “Complete withdrawal”.

---

Portfolio Endpoints

Two endpoints power position tracking:

Single yield balances

Fetch a user’s position in a specific yield:

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

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

Example:

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:

POST https://api.yield.xyz/v1/yields/balances

Request body:

{
  "addresses": [
    { "address": "0x1234...", "network": "ethereum" },
    { "address": "cosmos1abc...", "network": "cosmos" }
  ]
}

Example:

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" }
    ]
  }'

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

---

Position Origins

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

Yield.xyz-originated

Positions created via Yield.xyz actions.

• Full lifecycle tracking from entry
• Reward accrual data from entry date
• Included in baseline DataKit

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

---

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

Portfolio dashboard

Use aggregate balances to display all positions across networks. Group by network or yield type for clean UX.

Claimable rewards

Filter for type: rewards with amount > 0 to highlight claimable rewards.

Pending withdrawals

Check type: unstaking or type: unlocked to show in-progress and completed exits.

Cooldown timers

Use unlockDate (where available) to display remaining unbonding time.

---

API Reference

Yield Balances

GET /v1/yields//balances

Aggregate Balances

POST /v1/yields/balances

---

Next Steps

Fees

Understand fee structures and monetization

Tracking Balances Guide

Detailed implementation patterns