YieldGetAggregateBalances

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

POST /rpc/Trails/YieldGetAggregateBalances

YieldGetAggregateBalances returns a wallet's earn positions across chains.

cURL

curl --request POST \
  --url https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances \
  --header 'Content-Type: application/json' \
  --data '
{
  "queries": [
    {
      "address": "<string>",
      "network": "<string>"
    }
  ]
}
'

200

{
  "payload": {}
}

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

Array of 1–25 balance queries

Required array length: 1 - 25 elements

Show child attributes

Response

200

application/json

OK

payload · object · required

JSON array of yield balance records