---
title: "Get historical balance snapshots for a yield"
method: GET
path: "/v1/yields/{yieldId}/balances/history"
tags: ["Portfolio"]
---

# Get historical balance snapshots for a yield

`GET /v1/yields/{yieldId}/balances/history`

Returns a chronological time series of balance snapshots for a wallet address within a yield. Each entry reflects the position at a specific timestamp or block. Supports configurable sampling intervals and point-in-time queries. Only available for ERC4626 vaults with indexed transfer history.

## Path parameters

- `yieldId` string, required

## Query parameters

- `address` string, required
- `from` string
- `to` string
- `blockNumber` number
- `feeConfigurationId` string
- `interval` 'block' | 'hour' | 'day' | 'week'
- `sort` 'asc' | 'desc'
- `limit` number
- `offset` number

## Response `200`

Returns a paginated time series of balance snapshots

- object
  - `total` number, required — Total number of items available
  - `offset` number, required — Offset of the current page
  - `limit` number, required — Limit of the current page
  - `items` BalanceHistorySnapshotDto[]
    - `timestamp` string, required — Timestamp of this snapshot (ISO 8601)
    - `blockNumber` number, required — Block number closest to this snapshot
    - `yieldId` string, required — Unique identifier of the yield
    - `balances` BalanceDto[], required — Balance entries at this point in time
      - `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).
    - `periodDelta` BalanceHistorySnapshotPeriodDeltaDto
      - `shareAmount` string, required — Net vault share balance change from indexed transfers during this period
      - `shareAmountRaw` string, required — Net vault share balance change in base units (wei)
      - `amount` string, required — Net change in underlying position vs the previous snapshot (includes price-per-share effects)
      - `amountRaw` string, required — Net underlying position change in base units

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `404` — Yield not found with the specified ID
- `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)