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.

POST /v1/yields/{yieldId}/balances

Get balances for a specific yield

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/yields/{yieldId}/balances \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "arguments": {
    "cAddressBech": "0x123...",
    "pAddressBech": "P-avax1..."
  }
}
'

200

{
  "yieldId": "ethereum-eth-lido-staking",
  "balances": [
    {
      "address": "0x1234...",
      "type": "active",
      "amount": "2.625",
      "amountRaw": "2625000000000000000",
      "pendingActions": [
        {
          "intent": "manage",
          "type": "CLAIM_REWARDS",
          "passthrough": "eyJhZGRyZXNzZXMiOnsiYWRkcmVzcyI6ImNvc21vczF5ZXk...",
          "arguments": {
            "fields": [
              {
                "name": "amount",
                "type": "string",
                "label": "Amount to Enter",
                "description": "<string>",
                "required": true,
                "options": [
                  "individual",
                  "batched"
                ],
                "optionsRef": "/api/v1/validators?integrationId=eth-lido",
                "default": {},
                "placeholder": "<string>",
                "minimum": "1.0",
                "maximum": "100.0",
                "isArray": false
              }
            ],
            "notes": "<string>"
          }
        }
      ],
      "token": {
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18,
        "network": "Ethereum",
        "address": "0x...",
        "logoURI": "https://...",
        "isPoints": true,
        "coinGeckoId": "ethereum"
      },
      "isEarning": true,
      "date": "2025-04-23T08:00:00Z",
      "feeConfigurationId": "fee-config-1",
      "validator": {
        "address": "cosmosvaloper1abc...",
        "name": "StakeKit Validator",
        "logoURI": "https://stakekit.com/logo.png",
        "website": "https://stakekit.com",
        "rewardRate": {
          "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"
            }
          ]
        },
        "provider": {
          "name": "Provider name",
          "uniqueId": "provider-1",
          "website": "https://provider.com",
          "rank": 1,
          "preferred": true,
          "revshare": {
            "standard": {
              "minRevShare": 0.3,
              "maxRevShare": 0.7
            },
            "pro": {
              "minRevShare": 0.4,
              "maxRevShare": 0.8
            }
          }
        },
        "commission": 0.05,
        "tvlUsd": "18,340,000",
        "tvl": "8250.45",
        "tvlRaw": "8250450000000000000000",
        "votingPower": 0.013,
        "preferred": true,
        "minimumStake": "1.0",
        "remainingPossibleStake": "285,714.28",
        "remainingSlots": 8,
        "nominatorCount": 321,
        "status": "active",
        "providerId": "provider-1",
        "pricePerShare": "1.0",
        "subnetId": 1,
        "subnetName": "Apex",
        "marketCap": "1000000",
        "tokenSymbol": "α"
      },
      "validators": [
        {
          "address": "cosmosvaloper1abc...",
          "name": "StakeKit Validator",
          "logoURI": "https://stakekit.com/logo.png",
          "website": "https://stakekit.com",
          "rewardRate": {
            "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"
              }
            ]
          },
          "provider": {
            "name": "Provider name",
            "uniqueId": "provider-1",
            "website": "https://provider.com",
            "rank": 1,
            "preferred": true,
            "revshare": {
              "standard": {
                "minRevShare": 0.3,
                "maxRevShare": 0.7
              },
              "pro": {
                "minRevShare": 0.4,
                "maxRevShare": 0.8
              }
            }
          },
          "commission": 0.05,
          "tvlUsd": "18,340,000",
          "tvl": "8250.45",
          "tvlRaw": "8250450000000000000000",
          "votingPower": 0.013,
          "preferred": true,
          "minimumStake": "1.0",
          "remainingPossibleStake": "285,714.28",
          "remainingSlots": 8,
          "nominatorCount": 321,
          "status": "active",
          "providerId": "provider-1",
          "pricePerShare": "1.0",
          "subnetId": 1,
          "subnetName": "Apex",
          "marketCap": "1000000",
          "tokenSymbol": "α"
        }
      ],
      "amountUsd": "2,500.00"
    }
  ]
}

Authorizations

x-api-key · string · header · required

Path Parameters

yieldId · string · required

The unique identifier of the yield opportunity

Body

application/json

Balance request with address and optional arguments for advanced balance queries

address · string · required

User wallet address to check balances for

Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

arguments · object

Optional arguments for advanced or protocol-specific balance queries

Show child attributes

Response

200

application/json

Returns balance information including different balance types (active, entering, exiting, withdrawable, claimable, locked) with amounts and available actions

yieldId · string · required

Unique identifier of the yield

Example:

"ethereum-eth-lido-staking"

balances · object[] · required

List of balances for this yield

Show child attributes