> ## Documentation Index
> Fetch the complete documentation index at: https://anypay-docs-update-resources-2026-06-29.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# YieldGetAggregateBalances

> Fetch a wallet's earn balances across chains and yield positions

## 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"`) |

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

## 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

```typescript theme={null}
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

```typescript theme={null}
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:

```tsx theme={null}
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](/api-reference/endpoints/yield-get-markets) — Match `yieldId` against market IDs
* [YieldCreateExitAction](/api-reference/endpoints/yield-create-exit-action) — Build withdrawal transactions for active positions
* [Markets & Providers](/sdk/composable-actions/markets-and-providers) — SDK hooks reference


## OpenAPI

````yaml trails-api.gen.json post /rpc/Trails/YieldGetAggregateBalances
openapi: 3.0.0
info:
  title: Trails API
  version: 0.0.1
servers:
  - url: https://trails-api.sequence.app
    description: Trails API
security: []
paths:
  /rpc/Trails/YieldGetAggregateBalances:
    post:
      tags:
        - Trails
      summary: >-
        YieldGetAggregateBalances returns a wallet's earn positions across
        chains.
      description: >
        Fetches active yield positions for one or more wallet/network pairs.
        Accepts up to 25

        queries in a single request, enabling multi-chain balance lookups.
      operationId: Trails-YieldGetAggregateBalances
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetYieldAggregateBalancesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetYieldAggregateBalancesResponse'
        4XX:
          description: Client error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorWebrpcEndpoint'
                  - $ref: '#/components/schemas/ErrorWebrpcRequestFailed'
                  - $ref: '#/components/schemas/ErrorWebrpcBadRoute'
                  - $ref: '#/components/schemas/ErrorWebrpcBadMethod'
                  - $ref: '#/components/schemas/ErrorWebrpcBadRequest'
                  - $ref: '#/components/schemas/ErrorInvalidArgument'
                  - $ref: '#/components/schemas/ErrorUnavailable'
        5XX:
          description: Server error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorWebrpcBadResponse'
                  - $ref: '#/components/schemas/ErrorWebrpcServerPanic'
                  - $ref: '#/components/schemas/ErrorWebrpcInternalError'
                  - $ref: '#/components/schemas/ErrorUnexpected'
components:
  schemas:
    GetYieldAggregateBalancesRequest:
      type: object
      required:
        - queries
      properties:
        queries:
          type: array
          description: Array of 1–25 balance queries
          minItems: 1
          maxItems: 25
          items:
            $ref: '#/components/schemas/YieldBalanceQuery'
    GetYieldAggregateBalancesResponse:
      type: object
      required:
        - payload
      properties:
        payload:
          type: object
          description: JSON array of yield balance records
          additionalProperties: true
    ErrorWebrpcEndpoint:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcEndpoint
        code:
          type: number
          example: 0
        msg:
          type: string
          example: endpoint error
        cause:
          type: string
        status:
          type: number
          example: 400
    ErrorWebrpcRequestFailed:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcRequestFailed
        code:
          type: number
          example: -1
        msg:
          type: string
          example: request failed
        cause:
          type: string
        status:
          type: number
          example: 400
    ErrorWebrpcBadRoute:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcBadRoute
        code:
          type: number
          example: -2
        msg:
          type: string
          example: bad route
        cause:
          type: string
        status:
          type: number
          example: 404
    ErrorWebrpcBadMethod:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcBadMethod
        code:
          type: number
          example: -3
        msg:
          type: string
          example: bad method
        cause:
          type: string
        status:
          type: number
          example: 405
    ErrorWebrpcBadRequest:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcBadRequest
        code:
          type: number
          example: -4
        msg:
          type: string
          example: bad request
        cause:
          type: string
        status:
          type: number
          example: 400
    ErrorInvalidArgument:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: InvalidArgument
        code:
          type: number
          example: 2000
        msg:
          type: string
          example: Invalid argument
        cause:
          type: string
        status:
          type: number
          example: 400
    ErrorUnavailable:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: Unavailable
        code:
          type: number
          example: 2002
        msg:
          type: string
          example: Unavailable resource
        cause:
          type: string
        status:
          type: number
          example: 400
    ErrorWebrpcBadResponse:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcBadResponse
        code:
          type: number
          example: -5
        msg:
          type: string
          example: bad response
        cause:
          type: string
        status:
          type: number
          example: 500
    ErrorWebrpcServerPanic:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcServerPanic
        code:
          type: number
          example: -6
        msg:
          type: string
          example: server panic
        cause:
          type: string
        status:
          type: number
          example: 500
    ErrorWebrpcInternalError:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: WebrpcInternalError
        code:
          type: number
          example: -7
        msg:
          type: string
          example: internal error
        cause:
          type: string
        status:
          type: number
          example: 500
    ErrorUnexpected:
      type: object
      required:
        - error
        - code
        - msg
        - status
      properties:
        error:
          type: string
          example: Unexpected
        code:
          type: number
          example: 2001
        msg:
          type: string
          example: Unexpected server error
        cause:
          type: string
        status:
          type: number
          example: 500
    YieldBalanceQuery:
      type: object
      required:
        - address
        - network
      properties:
        address:
          type: string
          description: Wallet address to look up
        network:
          type: string
          description: Network name (e.g. "base", "ethereum", "polygon")

````