APY Fields

APY Fields

Nest vault APY endpoints return multiple APY fields to answer different questions. For new integrations, use the explicit field names: compositionApy for current-composition yield and navApy for NAV-based vault performance.

apy is still returned for backward compatibility as a legacy alias for compositionApy.

API rates are returned as decimals. For example, 0.10 means 10% APY.

Field Summary

Field	What it measures	When to use it
navApy	NAV-based APY calculated from vault token price changes over time.	Default headline APY, recent NAV-based vault performance, and historical APY charts.
compositionApy	Value-weighted APY of the vault’s yield-bearing positions. Liquid assets and offchain value are excluded from the APY denominator.	Vault composition analysis and forward-looking yield estimates based on the current invested portfolio.
apy	Legacy alias for compositionApy on vault APY endpoints.	Existing integrations only. New integrations should use compositionApy.

Each APY field can include:

Subfield	Meaning
rolling7d	Annualized APY over the trailing 7-day window.
rolling30d	Annualized APY over the trailing 30-day window.
sec30d	Annualized APY over the applicable 30-day month-end window, where available.

A null value means that the API does not have sufficient valid data for that metric. Clients should not display it as 0%.

Recommended Display

For most partner front ends, use navApy.rolling30d as the headline APY.

Use navApy to show the performance reflected in the vault share price over a selected period. It is calculated from changes in the vault token price and reflects asset performance, allocation changes, fees, and other operational impacts incorporated into NAV during that window.

Use compositionApy to estimate the vault’s forward-looking yield based on its current invested holdings. It does not represent the performance depositors experienced over a historical period.

NAV APY

navApy is based on the vault-level NAV. It measures how the vault token price changed over the selected window and annualizes that change. As a result, navApy reflects the performance incorporated into the vault share price during that period, including allocation changes and vault-level operational effects.

navApy is useful for:

• Showing a single headline APY on a partner vault page.
• Matching Nest’s performance-oriented vault display.
• Building consistent price and APY charts.
• Showing what performance was reflected in the vault share price over a recent 7-day or 30-day window.

Composition APY

compositionApy is calculated from the value-weighted APYs of the vault’s yield-bearing positions. Liquid assets and offchain value are excluded from the APY denominator, so the calculation estimates the yield of the invested portfolio rather than the entire vault.

For example, if the yield-bearing portion of a vault is allocated 50% to Asset A earning 8% APY and 50% to Asset B earning 12% APY, its composition APY is 10%.

Because compositionApy is based on current holdings, it may differ from the yield reflected in the vault’s historical NAV, particularly if the vault was rebalanced during the selected window. It also does not capture operational effects such as idle liquidity, fee accrual, or asset rotation timing.

When includeBreakdown=true is passed to /v1/vaults/apy or /v1/vaults/{slug}/apy, the response includes a breakdown. The breakdown reports total value, liquid assets, and each yield asset’s value, share of total vault value, and APY. When calculating compositionApy, the API reweights the yield-bearing assets after excluding liquid assets and offchain value.

The default is includeBreakdown=false. Request the breakdown for portfolio explanation, attribution, or debugging; it is not required for a normal headline APY display.

compositionApy is useful for answering:

• What projected annualized yield does the vault’s current invested asset mix imply?
• Which assets are contributing to the current portfolio yield?

Avoid Window Mismatches

When charting APY history, each historical point represents the rolling window ending on that day. For example, a rolling30d point on August 22 measures the 30 days ending August 22.

That is different from a cumulative performance chart that starts on one selected date and runs to the present. A high rolling 30-day APY at one historical point can be consistent with a lower cumulative return over a much longer selected period. When comparing charts, make sure both charts use the same metric and the same time window.

Example Response

{
  "data": {
    "vaultAddress": "0x...",
    "apy": {
      "rolling7d": 0.1070,
      "rolling30d": 0.1047,
      "sec30d": 0.1029
    },
    "compositionApy": {
      "rolling7d": 0.1070,
      "rolling30d": 0.1047,
      "sec30d": 0.1029
    },
    "navApy": {
      "rolling7d": 0.0999,
      "rolling30d": 0.1024,
      "sec30d": 0.1123
    }
  }
}

In this example, apy and compositionApy are identical because apy is a legacy alias. For a new integration, use compositionApy when you need composition-based yield, and use navApy.rolling30d for the default headline vault APY.

Endpoint Notes

The dedicated vault APY endpoints return apy, compositionApy, and navApy:

• GET /v1/vaults/apy
• GET /v1/vaults/{slug}/apy
• GET /v1/vaults/apy-history
• GET /v1/vaults/{slug}/apy-history

Asset APY endpoints return asset-level apy only:

• GET /v1/assets/{slug}/apy
• GET /v1/assets/{slug}/apy-history

Use asset-level apy to understand an underlying asset’s yield. Use vault-level navApy or compositionApy to display or explain a vault’s APY.