Skip to main content
POST
/
rpc
/
Trails
/
YieldGetAggregateBalances
YieldGetAggregateBalances returns a wallet's earn positions across chains.
curl --request POST \
  --url https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances \
  --header 'Content-Type: application/json' \
  --data '
{
  "queries": [
    {
      "address": "<string>",
      "network": "<string>"
    }
  ]
}
'
{
  "payload": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.trails.build/llms.txt

Use this file to discover all available pages before exploring further.

​
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

FieldTypeRequiredDescription
queriesobject[]YesArray of 1–25 balance queries
Each query object:
FieldTypeRequiredDescription
addressstringYesWallet address to look up
networkstringYesNetwork 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:
FieldDescription
yieldIdMarket ID — matches the id field from YieldGetMarkets
addressWallet address
networkNetwork the position is on
amountBalance amount in the market’s token
amountUsdUSD 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

Body

application/json
​
queries
object[]
required

Array of 1–25 balance queries

Required array length: 1 - 25 elements

Response

OK

​
payload
object
required

JSON array of yield balance records