> ## 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. # Get balances for a specific yield > Retrieve all balances associated with a yield opportunity for a specific wallet address, including active, pending, claimable, and withdrawable balances. The network is automatically determined from the yield configuration. ## OpenAPI ````yaml post /v1/yields/{yieldId}/balances openapi: 3.0.0 info: title: Yield.xyz API description: API Documentation version: '1.0' contact: {} servers: - url: https://api.yield.xyz description: Production environment - url: https://api.staging.yield.xyz description: Staging environment - url: http://localhost:3000 description: Local development security: [] tags: - name: Discovery description: Browse and discover yield opportunities, networks, and providers - name: Portfolio description: User-specific balances, activity, and rewards - name: Actions description: Generate transactions to enter, exit, and manage yields externalDocs: description: For more information url: https://docs.yield.xyz paths: /v1/yields/{yieldId}/balances: post: tags: - Portfolio summary: Get balances for a specific yield description: >- Retrieve all balances associated with a yield opportunity for a specific wallet address, including active, pending, claimable, and withdrawable balances. The network is automatically determined from the yield configuration. operationId: YieldsController_getYieldBalances parameters: - name: yieldId required: true in: path description: The unique identifier of the yield opportunity example: ethereum-eth-lido-staking schema: type: string requestBody: required: true description: >- Balance request with address and optional arguments for advanced balance queries content: application/json: schema: $ref: '#/components/schemas/YieldBalancesRequestDto' responses: '200': description: >- Returns balance information including different balance types (active, entering, exiting, withdrawable, claimable, locked) with amounts and available actions content: application/json: schema: $ref: '#/components/schemas/YieldBalancesDto' '400': description: Invalid request parameters content: application/json: schema: type: object properties: message: type: string example: Validation failed error: type: string example: Bad Request statusCode: type: number example: 400 '401': description: Invalid or missing API key content: application/json: schema: type: object properties: message: type: string example: Invalid API key error: type: string example: Unauthorized statusCode: type: number example: 401 '404': description: Yield not found with the specified ID '429': description: Rate limit exceeded headers: x-ratelimit-limit: description: Request limit per window schema: type: string x-ratelimit-remaining: description: Remaining requests (will be 0) schema: type: string x-ratelimit-reset: description: Unix timestamp when window resets schema: type: string retry-after: description: Seconds to wait before retrying schema: type: string content: application/json: schema: type: object properties: message: type: string example: Rate limit exceeded error: type: string example: Too Many Requests statusCode: type: number example: 429 retryAfter: type: number example: 30 '500': description: Internal server error content: application/json: schema: type: object properties: message: type: string example: Internal server error error: type: string example: Internal Server Error statusCode: type: number example: 500 security: - ApiKey: [] components: schemas: YieldBalancesRequestDto: type: object properties: address: type: string description: User wallet address to check balances for example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' arguments: description: Optional arguments for advanced or protocol-specific balance queries allOf: - $ref: '#/components/schemas/GetBalancesArgumentsDto' required: - address YieldBalancesDto: type: object properties: yieldId: type: string description: Unique identifier of the yield example: ethereum-eth-lido-staking balances: description: List of balances for this yield type: array items: $ref: '#/components/schemas/BalanceDto' required: - yieldId - balances GetBalancesArgumentsDto: type: object properties: cAddressBech: type: string description: Avalanche C-chain address example: 0x123... pAddressBech: type: string description: Avalanche P-chain address example: P-avax1... BalanceDto: type: object properties: address: type: string description: User wallet address that owns this balance example: 0x1234... type: $ref: '#/components/schemas/BalanceType' amount: type: string description: Balance amount in underlying token example: '2.625' amountRaw: type: string description: Raw balance amount (full precision) example: '2625000000000000000' date: format: date-time type: string description: Date relevant to this balance state nullable: true example: '2025-04-23T08:00:00Z' feeConfigurationId: type: string description: Fee configuration ID (if applicable) example: fee-config-1 pendingActions: description: Pending actions for this balance type: array items: $ref: '#/components/schemas/PendingActionDto' token: description: Token used for balance amounts allOf: - $ref: '#/components/schemas/TokenDto' validator: description: Validator information (if applicable) nullable: true allOf: - $ref: '#/components/schemas/ValidatorDto' validators: description: >- Multiple validators information (when balance is distributed across multiple validators) nullable: true type: array items: $ref: '#/components/schemas/ValidatorDto' amountUsd: type: string description: Value of the balance in USD example: 2,500.00 nullable: true isEarning: type: boolean description: Whether this balance is currently earning rewards example: true required: - address - type - amount - amountRaw - pendingActions - token - isEarning BalanceType: type: string description: Type of balance enum: - active - entering - exiting - withdrawable - claimable - locked PendingActionDto: type: object properties: intent: type: string description: High-level action intent enum: - enter - manage - exit example: manage type: type: string description: Specific action type enum: - STAKE - UNSTAKE - CLAIM_REWARDS - RESTAKE_REWARDS - WITHDRAW - WITHDRAW_ALL - RESTAKE - CLAIM_UNSTAKED - UNLOCK_LOCKED - STAKE_LOCKED - VOTE - REVOKE - VOTE_LOCKED - REVOTE - REBOND - MIGRATE - VERIFY_WITHDRAW_CREDENTIALS - DELEGATE example: CLAIM_REWARDS passthrough: type: string description: >- Server-generated passthrough that must be included when executing the action example: eyJhZGRyZXNzZXMiOnsiYWRkcmVzcyI6ImNvc21vczF5ZXk... arguments: description: Argument schema required to execute this action nullable: true allOf: - $ref: '#/components/schemas/ArgumentSchemaDto' required: - intent - type - passthrough TokenDto: type: object properties: symbol: type: string description: Token symbol example: ETH name: type: string description: Token name example: Ethereum decimals: type: number description: Token decimal places example: 18 network: type: string description: Token network enum: - ethereum - ethereum-goerli - ethereum-holesky - ethereum-sepolia - ethereum-hoodi - arbitrum - base - base-sepolia - gnosis - optimism - polygon - polygon-amoy - starknet - zksync - linea - unichain - monad-testnet - avalanche-c - avalanche-c-atomic - avalanche-p - binance - celo - fantom - harmony - moonriver - okc - viction - core - sonic - katana - hyperevm - agoric - akash - axelar - band-protocol - bitsong - canto - chihuahua - comdex - coreum - cosmos - crescent - cronos - cudos - desmos - dydx - evmos - fetch-ai - gravity-bridge - injective - irisnet - juno - kava - ki-network - mars-protocol - nym - okex-chain - onomy - osmosis - persistence - quicksilver - regen - secret - sentinel - sommelier - stafi - stargaze - stride - teritori - tgrade - umee - sei - mantra - celestia - saga - zetachain - dymension - humansai - neutron - polkadot - kusama - westend - bittensor - binancebeacon - cardano - near - solana - solana-devnet - stellar - stellar-testnet - sui - tezos - tron - ton - ton-testnet example: Ethereum address: type: string description: Token address (if applicable) example: 0x... logoURI: type: string description: Token logo URI example: https://... isPoints: type: boolean description: Token is points example: true coinGeckoId: type: string description: Token CoinGecko ID example: ethereum required: - symbol - name - decimals - network ValidatorDto: type: object properties: address: type: string description: Validator address or ID example: cosmosvaloper1abc... name: type: string description: Validator display name example: StakeKit Validator logoURI: type: string description: Validator logo URI example: https://stakekit.com/logo.png website: type: string description: Link to validator website example: https://stakekit.com rewardRate: description: >- Detailed reward rate breakdown by source (emissions, MEV, fees, etc.) example: total: 8.4 rateType: APR components: - rate: 6.8 rateType: APR token: symbol: SOL name: Solana yieldSource: staking description: Solana network inflation rewards - rate: 1.2 rateType: APR token: symbol: SOL name: Solana yieldSource: validator_commission description: Transaction fees from processed transactions - rate: 0.4 rateType: APR token: symbol: SOL name: Solana yieldSource: mev description: MEV from Jito block space auctions allOf: - $ref: '#/components/schemas/RewardRateDto' provider: description: Provider information for this validator allOf: - $ref: '#/components/schemas/ValidatorProviderDto' commission: type: number description: Commission rate charged by validator example: 0.05 tvlUsd: type: string description: Total value locked with this validator in USD example: 18,340,000 tvl: type: string description: Total value locked with this validator in native token example: '8250.45' tvlRaw: type: string description: Raw total value locked with this validator (full precision) example: '8250450000000000000000' votingPower: type: number description: Validator's voting power share (0–1) example: 0.013 preferred: type: boolean description: Whether this validator is flagged as preferred example: true minimumStake: type: string description: Minimum stake allowed in native token example: '1.0' remainingPossibleStake: type: string description: Maximum available stake before hitting cap in native token example: 285,714.28 remainingSlots: type: number description: Number of remaining nominator/delegator slots (for capped chains) example: 8 nominatorCount: type: number description: Number of current nominators example: 321 status: type: string description: Validator status description (active, jailed, unbonding, etc.) example: active providerId: type: string description: ID of the provider backing this validator example: provider-1 pricePerShare: type: string description: Price per share of the validator example: '1.0' subnetId: type: number description: Subnet ID example: 1 subnetName: type: string description: Subnet name example: Apex marketCap: type: string description: Market cap of the subnet example: '1000000' tokenSymbol: type: string description: Token symbol of the subnet example: α required: - address ArgumentSchemaDto: type: object properties: fields: description: List of argument fields type: array items: $ref: '#/components/schemas/ArgumentFieldDto' notes: type: string description: Notes or instructions for these arguments required: - fields RewardRateDto: type: object properties: total: type: number description: Estimated reward rate across all sources (e.g. staking, points) example: 6.5 rateType: type: string description: Whether this reward rate is APR or APY example: APR components: description: Breakdown of reward rates by source type: array items: $ref: '#/components/schemas/RewardDto' required: - total - rateType - components ValidatorProviderDto: type: object properties: name: type: string description: Provider display name example: Provider name uniqueId: type: string description: Unique identifier for the provider example: provider-1 website: type: string description: Provider website URL example: https://provider.com rank: type: number description: Provider ranking (lower numbers indicate higher preference) example: 1 preferred: type: boolean description: Whether this provider is marked as preferred example: true revshare: description: Revenue sharing details by tier example: standard: minRevShare: 0.3 maxRevShare: 0.7 pro: minRevShare: 0.4 maxRevShare: 0.8 allOf: - $ref: '#/components/schemas/RevShareTiersDto' required: - name - uniqueId - website - rank - preferred ArgumentFieldDto: type: object properties: name: type: string description: Field name enum: - amount - validatorAddress - validatorAddresses - receiverAddress - providerId - duration - inputToken - subnetId - tronResource - feeConfigurationId - cosmosPubKey - tezosPubKey - cAddressBech - pAddressBech - executionMode - ledgerWalletApiCompatible example: amount type: type: string description: Field type example: string enum: - string - number - address - enum - boolean label: type: string description: Field label example: Amount to Enter description: type: string description: Field description required: type: boolean description: Whether the field is required example: true options: description: Options for enum fields example: - individual - batched type: array items: type: string optionsRef: type: string description: Reference to API endpoint that provides options dynamically example: /api/v1/validators?integrationId=eth-lido default: type: object description: Default value for the field placeholder: type: string description: Placeholder text for the field minimum: type: string description: Minimum allowed value for number fields (null if no minimum) example: '1.0' nullable: true maximum: type: string description: Maximum allowed value for number fields (null if no maximum) example: '100.0' nullable: true isArray: type: boolean description: Whether the field is an array example: false required: - name - type - label RewardDto: type: object properties: rate: type: number description: Reward rate as a decimal (e.g. 0.04 = 4%) example: 0.04 rateType: type: string description: Whether this rate is APR or APY example: APR token: description: Token received as reward allOf: - $ref: '#/components/schemas/TokenDto' yieldSource: type: string description: Structured source of yield (e.g. staking, protocol incentive) enum: - staking - restaking - protocol_incentive - points - lending_interest - mev - real_world_asset_yield example: protocol_incentive description: type: string description: Optional human-readable description of this reward example: LDO distributed to incentivize stETH adoption via Lido Boost required: - rate - rateType - token - yieldSource RevShareTiersDto: type: object properties: trial: description: Trial tier revenue share details allOf: - $ref: '#/components/schemas/RevShareDetailsDto' standard: description: Standard tier revenue share details allOf: - $ref: '#/components/schemas/RevShareDetailsDto' pro: description: Pro tier revenue share details allOf: - $ref: '#/components/schemas/RevShareDetailsDto' RevShareDetailsDto: type: object properties: minRevShare: type: number description: Minimum revenue share percentage (0-1) example: 0.3 maxRevShare: type: number description: Maximum revenue share percentage (0-1) example: 0.7 required: - minRevShare - maxRevShare securitySchemes: ApiKey: type: apiKey in: header name: x-api-key ````