Get balances across multiple yields and networks

Retrieve balances for multiple wallet addresses across different networks and yield opportunities. Send an array of balance requests - each request can specify a yieldId (optional for chain scanning), address, network, and custom arguments. This is the same format as the single yield balance endpoint but in array form. Duplicate requests (same yieldId + address + network) are automatically deduplicated, with specific yield requests taking precedence over chain scans.

POST /v1/yields/balances

Get balances across multiple yields and networks

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/yields/balances \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "queries": [
    {
      "yieldId": "ethereum-eth-lido-staking",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "ethereum"
    }
  ]
}
'

200

{
  "items": [
    {
      "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"
        }
      ]
    }
  ],
  "errors": [
    {
      "yieldId": "ethereum-compound-usdc",
      "error": "Failed to fetch data from blockchain: RPC timeout"
    }
  ]
}

Authorizations

x-api-key · string · header · required

Body

application/json

Request containing an array of balance queries. Each query contains: yieldId (optional), address (required), network (required), and arguments (optional). When yieldId is omitted, all yields for that network will be scanned. You can mix chain scans with specific yield queries - duplicates are automatically deduplicated with specific queries taking precedence.

queries · object[] · required

Array of balance queries

Show child attributes

Example:

[
  {
    "yieldId": "ethereum-eth-lido-staking",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "ethereum"
  }
]

Response

200

application/json

Returns balances grouped by yield with detailed error information for failed yields. Only yields with non-zero balances are included in the response.

items · object[] · required

Successful yield balance results

Show child attributes

errors · object[] · required

Errors encountered while fetching balances

Show child attributes