YieldGetAggregateBalances

Fetch a wallet’s earn balances across chains and yield positions

POST /rpc/Trails/YieldGetAggregateBalances

YieldGetAggregateBalances returns balances across multiple yields and networks.

cURL

curl --request POST \
  --url https://api.example.com/rpc/Trails/YieldGetAggregateBalances \
  --header 'Content-Type: application/json' \
  --data '
{
  "queries": [
    {
      "address": "<string>",
      "network": "<string>",
      "yieldId": "<string>",
      "arguments": {
        "cAddressBech": "<string>",
        "pAddressBech": "<string>",
        "autoSweepDayOfMonth": 123,
        "autoSweepTimezone": "<string>"
      }
    }
  ]
}
'

200

{
  "items": [
    {
      "yieldId": "<string>",
      "balances": [
        {
          "address": "<string>",
          "type": "<string>",
          "amount": "<string>",
          "amountRaw": "<string>",
          "pendingActions": [
            {
              "intent": "<string>",
              "type": "<string>",
              "passthrough": "<string>",
              "arguments": {
                "fields": [
                  {
                    "name": "<string>",
                    "type": "<string>",
                    "label": "<string>",
                    "description": "<string>",
                    "required": true,
                    "options": [
                      "<string>"
                    ],
                    "optionsRef": "<string>",
                    "default": {},
                    "placeholder": "<string>",
                    "minimum": "<string>",
                    "maximum": "<string>",
                    "isArray": true
                  }
                ],
                "notes": "<string>"
              },
              "amount": "<string>"
            }
          ],
          "token": {
            "symbol": "<string>",
            "name": "<string>",
            "decimals": 123,
            "network": "<string>",
            "address": "<string>",
            "logoURI": "<string>",
            "isPoints": true,
            "coinGeckoId": "<string>"
          },
          "isEarning": true,
          "date": "<string>",
          "feeConfigurationId": "<string>",
          "validator": {
            "address": "<string>",
            "name": "<string>",
            "logoURI": "<string>",
            "website": "<string>",
            "rewardRate": {
              "total": 123,
              "rateType": "<string>",
              "components": [
                {
                  "rate": 123,
                  "rateType": "<string>",
                  "token": {
                    "symbol": "<string>",
                    "name": "<string>",
                    "decimals": 123,
                    "network": "<string>",
                    "address": "<string>",
                    "logoURI": "<string>",
                    "isPoints": true,
                    "coinGeckoId": "<string>"
                  },
                  "yieldSource": "<string>",
                  "description": "<string>"
                }
              ]
            },
            "provider": {
              "name": "<string>",
              "id": "<string>",
              "logoURI": "<string>",
              "description": "<string>",
              "website": "<string>",
              "tvlUsd": {},
              "type": "<string>",
              "rank": 123,
              "preferred": true,
              "references": [
                "<string>"
              ],
              "revshare": {
                "trial": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                },
                "standard": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                },
                "pro": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                }
              },
              "uniqueId": "<string>",
              "createdAt": "<string>",
              "updatedAt": "<string>"
            },
            "commission": 123,
            "tvlUsd": "<string>",
            "tvl": "<string>",
            "tvlRaw": "<string>",
            "votingPower": 123,
            "preferred": true,
            "minimumStake": "<string>",
            "remainingPossibleStake": "<string>",
            "remainingSlots": 123,
            "nominatorCount": 123,
            "status": "<string>",
            "providerId": "<string>",
            "pricePerShare": "<string>",
            "subnetId": 123,
            "subnetName": "<string>",
            "marketCap": "<string>",
            "tokenSymbol": "<string>"
          },
          "validators": [
            {
              "address": "<string>",
              "name": "<string>",
              "logoURI": "<string>",
              "website": "<string>",
              "rewardRate": {
                "total": 123,
                "rateType": "<string>",
                "components": [
                  {
                    "rate": 123,
                    "rateType": "<string>",
                    "token": {
                      "symbol": "<string>",
                      "name": "<string>",
                      "decimals": 123,
                      "network": "<string>",
                      "address": "<string>",
                      "logoURI": "<string>",
                      "isPoints": true,
                      "coinGeckoId": "<string>"
                    },
                    "yieldSource": "<string>",
                    "description": "<string>"
                  }
                ]
              },
              "provider": {
                "name": "<string>",
                "id": "<string>",
                "logoURI": "<string>",
                "description": "<string>",
                "website": "<string>",
                "tvlUsd": {},
                "type": "<string>",
                "rank": 123,
                "preferred": true,
                "references": [
                  "<string>"
                ],
                "revshare": {
                  "trial": {
                    "minRevShare": 123,
                    "maxRevShare": 123
                  },
                  "standard": {
                    "minRevShare": 123,
                    "maxRevShare": 123
                  },
                  "pro": {
                    "minRevShare": 123,
                    "maxRevShare": 123
                  }
                },
                "uniqueId": "<string>",
                "createdAt": "<string>",
                "updatedAt": "<string>"
              },
              "commission": 123,
              "tvlUsd": "<string>",
              "tvl": "<string>",
              "tvlRaw": "<string>",
              "votingPower": 123,
              "preferred": true,
              "minimumStake": "<string>",
              "remainingPossibleStake": "<string>",
              "remainingSlots": 123,
              "nominatorCount": 123,
              "status": "<string>",
              "providerId": "<string>",
              "pricePerShare": "<string>",
              "subnetId": 123,
              "subnetName": "<string>",
              "marketCap": "<string>",
              "tokenSymbol": "<string>"
            }
          ],
          "amountUsd": "<string>",
          "priceRange": {},
          "tokenId": "<string>",
          "shareAmount": "<string>",
          "shareAmountRaw": "<string>",
          "shareToken": {
            "symbol": "<string>",
            "name": "<string>",
            "decimals": 123,
            "network": "<string>",
            "address": "<string>",
            "logoURI": "<string>",
            "isPoints": true,
            "coinGeckoId": "<string>"
          }
        }
      ],
      "outputTokenBalance": {
        "address": "<string>",
        "type": "<string>",
        "amount": "<string>",
        "amountRaw": "<string>",
        "pendingActions": [
          {
            "intent": "<string>",
            "type": "<string>",
            "passthrough": "<string>",
            "arguments": {
              "fields": [
                {
                  "name": "<string>",
                  "type": "<string>",
                  "label": "<string>",
                  "description": "<string>",
                  "required": true,
                  "options": [
                    "<string>"
                  ],
                  "optionsRef": "<string>",
                  "default": {},
                  "placeholder": "<string>",
                  "minimum": "<string>",
                  "maximum": "<string>",
                  "isArray": true
                }
              ],
              "notes": "<string>"
            },
            "amount": "<string>"
          }
        ],
        "token": {
          "symbol": "<string>",
          "name": "<string>",
          "decimals": 123,
          "network": "<string>",
          "address": "<string>",
          "logoURI": "<string>",
          "isPoints": true,
          "coinGeckoId": "<string>"
        },
        "isEarning": true,
        "date": "<string>",
        "feeConfigurationId": "<string>",
        "validator": {
          "address": "<string>",
          "name": "<string>",
          "logoURI": "<string>",
          "website": "<string>",
          "rewardRate": {
            "total": 123,
            "rateType": "<string>",
            "components": [
              {
                "rate": 123,
                "rateType": "<string>",
                "token": {
                  "symbol": "<string>",
                  "name": "<string>",
                  "decimals": 123,
                  "network": "<string>",
                  "address": "<string>",
                  "logoURI": "<string>",
                  "isPoints": true,
                  "coinGeckoId": "<string>"
                },
                "yieldSource": "<string>",
                "description": "<string>"
              }
            ]
          },
          "provider": {
            "name": "<string>",
            "id": "<string>",
            "logoURI": "<string>",
            "description": "<string>",
            "website": "<string>",
            "tvlUsd": {},
            "type": "<string>",
            "rank": 123,
            "preferred": true,
            "references": [
              "<string>"
            ],
            "revshare": {
              "trial": {
                "minRevShare": 123,
                "maxRevShare": 123
              },
              "standard": {
                "minRevShare": 123,
                "maxRevShare": 123
              },
              "pro": {
                "minRevShare": 123,
                "maxRevShare": 123
              }
            },
            "uniqueId": "<string>",
            "createdAt": "<string>",
            "updatedAt": "<string>"
          },
          "commission": 123,
          "tvlUsd": "<string>",
          "tvl": "<string>",
          "tvlRaw": "<string>",
          "votingPower": 123,
          "preferred": true,
          "minimumStake": "<string>",
          "remainingPossibleStake": "<string>",
          "remainingSlots": 123,
          "nominatorCount": 123,
          "status": "<string>",
          "providerId": "<string>",
          "pricePerShare": "<string>",
          "subnetId": 123,
          "subnetName": "<string>",
          "marketCap": "<string>",
          "tokenSymbol": "<string>"
        },
        "validators": [
          {
            "address": "<string>",
            "name": "<string>",
            "logoURI": "<string>",
            "website": "<string>",
            "rewardRate": {
              "total": 123,
              "rateType": "<string>",
              "components": [
                {
                  "rate": 123,
                  "rateType": "<string>",
                  "token": {
                    "symbol": "<string>",
                    "name": "<string>",
                    "decimals": 123,
                    "network": "<string>",
                    "address": "<string>",
                    "logoURI": "<string>",
                    "isPoints": true,
                    "coinGeckoId": "<string>"
                  },
                  "yieldSource": "<string>",
                  "description": "<string>"
                }
              ]
            },
            "provider": {
              "name": "<string>",
              "id": "<string>",
              "logoURI": "<string>",
              "description": "<string>",
              "website": "<string>",
              "tvlUsd": {},
              "type": "<string>",
              "rank": 123,
              "preferred": true,
              "references": [
                "<string>"
              ],
              "revshare": {
                "trial": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                },
                "standard": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                },
                "pro": {
                  "minRevShare": 123,
                  "maxRevShare": 123
                }
              },
              "uniqueId": "<string>",
              "createdAt": "<string>",
              "updatedAt": "<string>"
            },
            "commission": 123,
            "tvlUsd": "<string>",
            "tvl": "<string>",
            "tvlRaw": "<string>",
            "votingPower": 123,
            "preferred": true,
            "minimumStake": "<string>",
            "remainingPossibleStake": "<string>",
            "remainingSlots": 123,
            "nominatorCount": 123,
            "status": "<string>",
            "providerId": "<string>",
            "pricePerShare": "<string>",
            "subnetId": 123,
            "subnetName": "<string>",
            "marketCap": "<string>",
            "tokenSymbol": "<string>"
          }
        ],
        "amountUsd": "<string>",
        "priceRange": {},
        "tokenId": "<string>",
        "shareAmount": "<string>",
        "shareAmountRaw": "<string>",
        "shareToken": {
          "symbol": "<string>",
          "name": "<string>",
          "decimals": 123,
          "network": "<string>",
          "address": "<string>",
          "logoURI": "<string>",
          "isPoints": true,
          "coinGeckoId": "<string>"
        }
      },
      "rewardRate": {
        "total": 123,
        "rateType": "<string>",
        "components": [
          {
            "rate": 123,
            "rateType": "<string>",
            "token": {
              "symbol": "<string>",
              "name": "<string>",
              "decimals": 123,
              "network": "<string>",
              "address": "<string>",
              "logoURI": "<string>",
              "isPoints": true,
              "coinGeckoId": "<string>"
            },
            "yieldSource": "<string>",
            "description": "<string>"
          }
        ]
      }
    }
  ],
  "errors": [
    {
      "yieldId": "<string>",
      "error": "<string>"
    }
  ]
}

Overview

YieldGetAggregateBalances returns a wallet’s active yield positions across one or more chains. Use this to show users their current DeFi holdings — principal, earned yield, and which markets they are in.

The SDK’s useEarnBalances hook wraps this endpoint — prefer it in React apps.

Request Parameters

Field	Type	Required	Description
queries	object[]	Yes	Array of 1–25 balance queries

Each query object:

Field	Type	Required	Description
address	string	Yes	Wallet address to look up
network	string	Yes	Network identifier (e.g. "ethereum", "base", "polygon")

You can pass up to 25 queries per request, enabling multi-chain balance lookups in a single call.

Response

Returns payload containing balance records. Each balance entry includes:

Field	Description
yieldId	Market ID — matches the id field from YieldGetMarkets
address	Wallet address
network	Network the position is on
amount	Balance amount in the market’s token
amountUsd	USD value of the position

Examples

Fetch balances on a single chain

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_ACCESS_KEY',
  },
  body: JSON.stringify({
    queries: [
      {
        address: '0xYourWalletAddress',
        network: 'base',
      },
    ],
  }),
})

const { payload } = await response.json()
const balances = JSON.parse(payload)

balances.forEach(position => {
  console.log(`${position.yieldId}: ${position.amountUsd} USD`)
})

Multi-chain balance lookup

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_ACCESS_KEY',
  },
  body: JSON.stringify({
    queries: [
      { address: '0xYourWalletAddress', network: 'base' },
      { address: '0xYourWalletAddress', network: 'ethereum' },
      { address: '0xYourWalletAddress', network: 'polygon' },
    ],
  }),
})

const { payload } = await response.json()
const balances = JSON.parse(payload)

SDK alternative

In React, use the useEarnBalances hook:

import { useEarnBalances } from '0xtrails'

// Single chain
const { data: balances } = useEarnBalances({
  walletAddress: '0xYourWalletAddress',
  chain: 'base',
})

// Multiple chains
const { data: balances } = useEarnBalances({
  walletAddress: '0xYourWalletAddress',
  chains: ['base', 'ethereum', 'polygon'],
})

See also

• YieldGetMarkets — Match yieldId against market IDs
• YieldCreateExitAction — Build withdrawal transactions for active positions
• Markets & Providers — SDK hooks reference

Body

application/json

queries · object[] · required

[]YieldBalanceQuery

Show child attributes

Response

200

application/json

OK

items · object[] · required

[]YieldBalances

Show child attributes

errors · object[] · required

[]YieldError

Show child attributes