---
title: "Get balances across multiple yields and networks"
method: POST
path: "/v1/yields/balances"
tags: ["Portfolio"]
---

# Get balances across multiple yields and networks

`POST /v1/yields/balances`

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.

## Request body

- BalancesRequestDto
  - `providerId` 'hyperliquid' | 'hyperliquid-xyz' — Single provider identifier. At least one of providerId or providerIds must be provided.
  - `providerIds` string[] — Single provider only (one CSV value, one repeated param, or a one-element JSON array). At least one of providerId or providerIds must be provided. Must not combine with a different providerId.
  - `address` string, required — User wallet address

## Response `200`

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

- BalancesResponseDto
  - `items` YieldBalancesDto[], required — Successful yield balance results
    - `yieldId` string, required — Unique identifier of the yield
    - `balances` BalanceDto[], required — List of balances for this yield
      - `providerId` string, required — Provider ID
      - `collateral` TokenDto, required
        - `address` string — Token contract address
        - `symbol` string, required — Token symbol
        - `name` string, required — Token name
        - `decimals` number, required — Token decimals
        - `logoURI` string — Token logo URI
      - `accountValue` number, required — Total account value in collateral asset
      - `usedMargin` number, required — Margin used by positions in collateral asset
      - `availableBalance` number, required — Available balance for new positions in collateral asset
      - `unrealizedPnl` number, required — Total price PnL across all positions in collateral asset (excludes funding)
      - `unifiedAccountMode` boolean — Whether the account currently has Unified Account Mode enabled (collateral unified across venues). Only present for providers that support it (Hyperliquid).
    - `outputTokenBalance` BalanceDto
      - `providerId` string, required — Provider ID
      - `collateral` TokenDto, required
        - `address` string — Token contract address
        - `symbol` string, required — Token symbol
        - `name` string, required — Token name
        - `decimals` number, required — Token decimals
        - `logoURI` string — Token logo URI
      - `accountValue` number, required — Total account value in collateral asset
      - `usedMargin` number, required — Margin used by positions in collateral asset
      - `availableBalance` number, required — Available balance for new positions in collateral asset
      - `unrealizedPnl` number, required — Total price PnL across all positions in collateral asset (excludes funding)
      - `unifiedAccountMode` boolean — Whether the account currently has Unified Account Mode enabled (collateral unified across venues). Only present for providers that support it (Hyperliquid).
    - `rewardRate` RewardRateDto
      - `total` number, required — Estimated underlying integration reward rate across all sources. May include an additional campaign component when an active campaign applies to this project.
      - `rateType` string, required — Whether this reward rate is APR or APY
      - `components` RewardDto[], required — Breakdown of reward rates by source
        - `rate` number, required — Reward rate as a decimal (e.g. 0.04 = 4%)
        - `rateType` string, required — Whether this rate is APR or APY
        - `token` TokenDto, required
          - `address` string — Token contract address
          - `symbol` string, required — Token symbol
          - `name` string, required — Token name
          - `decimals` number, required — Token decimals
          - `logoURI` string — Token logo URI
        - `yieldSource` 'staking' | 'liquid_staking' | 'restaking' | 'protocol_incentive' | 'campaign_incentive' | 'points' | 'lending' | 'mev' | 'real_world_asset_yield' | 'vault', required — Structured source of yield (e.g. staking, protocol incentive)
        - `description` string — Optional human-readable description of this reward
  - `errors` YieldErrorDto[], required — Errors encountered while fetching balances
    - `yieldId` string, required — Unique identifier of the yield that failed
    - `error` string, required — Error message describing what went wrong

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/yield/apis/yield-xyz-api.md) · [All operations](https://skmtc.net/yield/apis/yield-xyz-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yield/yield-xyz-api/versions/acfa80015ca5/schema)