Vault Discovery

Everything You Can Know About a Vault

The Vaults.fyi API surfaces more data about a DeFi vault than most applications ever need. Use it to discover opportunities, build vault detail pages, power filters, and decide which vaults are suitable for your users. This page documents what you can retrieve — what each field means, which endpoint it comes from, and what you would use it for. The primary source for static vault data is GET /v2/detailed-vaults/{network}/{vaultId}. Additional endpoints extend that with advanced analytics, time-series history, near real-time state, and per-user position data.

The auto-generated API Reference endpoint pages are the authoritative source for exact field names, types, and required/optional status — they update automatically from the OpenAPI spec on every release. This page is the narrative layer: what each field means and when to use it. If you spot a discrepancy, the endpoint page is correct.

Identity

Every vault has a stable identity and a set of descriptive fields.

Field	Description
`vaultId`	Stable identifier used in all API calls and deep links. Persists across vault upgrades.
`address`	Vault contract address (EIP-55 checksummed).
`name`	Human-readable vault name.
`description`	Free-text description of the vault strategy, if provided by the protocol.
`network.name`	Network slug: `mainnet`, `base`, `arbitrum`, `optimism`, `polygon`, and others.
`network.chainId`	EVM chain ID.
`network.networkCaip`	CAIP-2 network identifier (e.g. `eip155:1`).
`tags`	Array of category tags (e.g. `Lending`, `Liquid Staking`, `RWA`). Useful for filtering. See Vault Tags.
`isAppFeatured`	Whether the vault is featured on app.vaults.fyi.
`lastUpdateTimestamp`	Unix timestamp of the most recent onchain data index.

Vault Tags

Vault tags describe the economic mechanism, product type, or structural exposure behind a vault. They are useful for filtering vaults, building category views, and explaining why a vault belongs in a given yield segment. Tags are not mutually exclusive: a vault can have more than one tag when multiple classifications apply. Some tags are broad parent categories, while others are more precise subclasses. For example, Lending is the broad parent category for lending-driven yield, while tags like Curated Lending, Direct Protocol Lending, Isolated Market, and Shared Lending Pool provide more specific filtering. Use GET /v2/tags to retrieve the live list of supported tags.

Tag	Definition
`Basis Trading`	Products where yield is primarily generated from futures, perps, or spot/derivatives basis and funding-rate strategies.
`Bridging`	Products related to moving assets or liquidity across networks.
`CDP`	Products where yield is sourced from collateralized debt position (CDP) systems where users mint or borrow against deposited collateral.
`Credit`	Products with default/underwriting/counterparty risk, including private credit, structured credit, or other off-chain sources of yield.
`Curated Lending`	Lending exposure where a curator, risk manager, or allocator selects eligible markets, collateral, caps, or allocations.
`DEX-Integrated Lending`	Lending products where supplied capital directly shares a unified liquidity layer that simultaneously supports lending and DEX or trading activity.
`Direct Protocol Lending`	Direct supply into a protocol lending pool or market, where yield is primarily generated by borrower interest rather than a curator vault, managed strategy, credit product, or protocol savings rate.
`Isolated Market`	Lending market where risk is sandboxed and scoped to a specific market contract, vault, or collateral configuration rather than shared across a broad pooled lending system.
`Lending`	Broad parent tag for products where yield primarily comes from lending activity. Use subclass tags for more precise filtering.
`Liquid Staking`	Products that provide exposure to staking yield through a liquid receipt token or staking vault.
`Market Making`	Products where yield is generated from providing liquidity, market making, or trader flow rather than borrower interest.
`Protocol Savings Rate`	Yield-bearing product where the return is primarily determined by a policy-driven or governance-managed savings/rate mechanism rather than direct lending market utilization. Excludes assets that actively underwrite protocol deficits or act as first-loss capital.
`Risk Cover`	Products that are protected in part by cover for smart contract, protocol, slashing, custody, depeg, or other onchain risks.
`RWA`	Products with exposure to real-world assets or offchain financial instruments, such as tokenized treasuries, private credit, or other offchain yield sources.
`Safety Module`	Products where deposited assets backstop protocol risk and may be used to absorb shortfalls, underwrite liquidations, or participate in protocol protection mechanisms.
`Shared Lending Pool`	Lending products where supplied liquidity is pooled across multiple collateral types, exposing depositors to global or protocol-wide risk parameters rather than an isolated market configuration.
`Synthetic`	Products with synthetic asset construction, derivative-like backing, or engineered exposure that does not represent a simple claim on the underlying asset.
`Yield Aggregator`	Broad category for products that route, allocate, or compound deposits across one or more external yield sources or strategies.

Protocol and Curator

Vaults belong to a protocol. Some are additionally managed by a named curator (e.g. a risk manager or strategy team).

Field	Description
`protocol.name`	Protocol name (e.g. `Morpho`, `Aave`, `Compound`).
`protocol.product`	Product line within the protocol, if applicable.
`protocol.version`	Protocol version.
`protocol.protocolUrl`	Protocol website.
`protocol.description`	Short protocol description.
`protocol.protocolLogo`	URL to the protocol logo image.
`curator.name`	Name of the vault curator, if one is assigned.
`curator.description`	Description of the curator.
`curator.websiteUrl`	Curator website.
`protocolVaultUrl`	Direct URL to this vault on the protocol’s own interface.
`lendUrl`	URL to lend the vault’s asset directly.

The Asset

The underlying asset is what users deposit and withdraw. All balances and TVL figures reference this token.

Field	Description
`asset.symbol`	Token symbol (e.g. `USDC`, `WETH`).
`asset.name`	Full token name.
`asset.address`	Token contract address.
`asset.assetCaip`	CAIP-19 asset identifier.
`asset.decimals`	Token precision.
`asset.assetPriceInUsd`	Current USD price.
`asset.assetGroup`	High-level category: `USD`, `ETH`, `BTC`, `EURO`, or `OTHER`.
`asset.assetLogo`	URL to the token logo image.
`additionalAssets`	For multi-asset vaults: the same asset fields for each additional accepted asset.

The LP Token

When a user deposits into a vault, they receive LP tokens representing their share. These are the tokens held in a wallet.

Field	Description
`lpToken.symbol`	LP token symbol.
`lpToken.name`	LP token name.
`lpToken.address`	LP token contract address.
`lpToken.tokenCaip`	CAIP-19 identifier for the LP token.
`lpToken.decimals`	LP token precision.
`sharePrice`	LP token share price.

APY

APY data is normalized across all protocols using a consistent methodology. See Calculating APY for details. Each vault returns APY across four time windows, each broken into three components:

Field	Description
`apy.1hour.base`	Base yield earned from lending or strategy, annualized over the last hour.
`apy.1hour.reward`	Token reward APY (e.g. incentive programs), annualized over the last hour.
`apy.1hour.total`	Sum of base and reward.
`apy.1day`	Same breakdown averaged over 24 hours.
`apy.7day`	Same breakdown averaged over 7 days.
`apy.30day`	Same breakdown averaged over 30 days.

Use apy.7day.total or apy.30day.total for user-facing yield displays. The 1-hour and 1-day figures are noisier and better suited for dashboards or anomaly detection.

Composite APY (nested vaults)

When a vault’s underlying asset is itself another vault’s LP token (e.g. a vault that deposits into another yield vault), an additional apyComposite object is present. It compounds both layers of yield into a single figure.

Field	Description
`apyComposite.totalApy`	Compounded APY combining this vault and the underlying vault (same 1h/1d/7d/30d windows).
`apyComposite.intrinsicApy`	The underlying vault’s own APY, before compounding.
`apyComposite.vault.vaultId`	ID of the underlying vault.
`apyComposite.asset`	Asset details of the underlying vault.

TVL

Field	Description
`tvl.usd`	Total value locked, denominated in USD.
`tvl.native`	Total value locked, denominated in the vault’s native asset.

Advanced Analytics

For deeper vault discovery and diligence workflows, use the Alpha Advanced Analytics endpoints:

Endpoint	Use case
`POST /alpha/advanced-analytics`	Screen a filtered list of vaults with selected analytics fields.
`POST /alpha/advanced-analytics/{network}/{vaultId}`	Fetch selected analytics fields for one known vault.

Advanced Analytics uses a select request body so applications only request the sections they need:

{
  "select": {
    "maxDrawdown": true,
    "withdrawalPauseRatio": true,
    "composition": true,
    "detailedVault": true
  }
}

Field	Description
`maxDrawdown.mdd30days`	Maximum drawdown (MDD): the largest observed peak-to-trough drop in vault price per share over the last 30 days, reported as a decimal.
`maxDrawdown.mdd90days`	Maximum drawdown (MDD) over the last 90 days.
`maxDrawdown.mdd365days`	Maximum drawdown (MDD) over the last 365 days.
`withdrawalPauseRatio`	Ratio from `0` to `1` representing how much time withdrawals were paused over the last two years. Returns `null` when the protocol does not expose a supported pause-event source or the event history has not been backfilled.
`composition[]`	Vault allocation or investment composition where available. Useful for showing what a vault is allocated into, especially allocator-style products.
`composition[].id`	Identifier for the investment or market.
`composition[].supplyAssets`	Amount of underlying assets supplied to that investment.
`composition[].allocation`	Share of the vault allocated to that investment, as a decimal.
`composition[].name`	Human-readable name for the investment or market.
`detailedVault`	Full V2 detailed vault payload embedded alongside the selected analytics fields. Useful when building one combined discovery response.

Advanced Analytics is currently in Alpha. Field availability depends on protocol support and data coverage. Build integrations so nullable fields can be hidden or explained instead of treated as failures.

See Alpha API Reference for filters, request shape, and endpoint details.

Additional Rewards

Many vaults distribute bonus reward tokens on top of base yield. Each entry in the rewards array represents one reward token.

Field	Description
`rewards[].asset.symbol`	Reward token symbol.
`rewards[].asset.assetPriceInUsd`	Current USD price of the reward token.
`rewards[].apy.1hour`	Reward APY over 1 hour.
`rewards[].apy.1day`	Reward APY over 1 day.
`rewards[].apy.7day`	Reward APY over 7 days.
`rewards[].apy.30day`	Reward APY over 30 days.

Reward APYs are already included in the top-level apy.*.reward field. The rewards array lets you attribute yield to specific tokens and display individual reward rates.

Reputation Score

Vaults.fyi computes a composite reputation score for each vault based on several risk signals. Higher is better. See Reputation Score for methodology.

Field	Description
`score.vaultScore`	Composite Reputation Score combining all component scores, after any flag penalties are applied.
`score.vaultTvlScore`	Score component based on this vault’s TVL.
`score.protocolTvlScore`	Score component based on the protocol’s total TVL.
`score.holderScore`	Score component based on holder count and distribution.
`score.networkScore`	Score component based on which network the vault is on.
`score.assetScore`	Score component based on the underlying asset type and liquidity.
`score.totalScorePenalty`	Current point deduction applied to `score.vaultScore` because of flag penalties.
`score.penaltyComponents`	Active or decaying flag penalties applied to the composite score, with severity and resolution details for each.
`score.penaltyComponents[].type`	Penalty source. Flag penalties use `flag`.
`score.penaltyComponents[].value`	Current point deduction from this penalty component. For resolved flags, this may be partially reduced.
`score.penaltyComponents[].content`	Flag message text for flag-derived penalties.
`score.penaltyComponents[].severity`	Flag severity: `info`, `warning`, or `critical`.
`score.penaltyComponents[].endDate`	Unix timestamp when the flag expires.
`score.penaltyComponents[].resolution`	Optional resolution note explaining how the flagged issue was addressed. Omitted for unresolved flags.

Holders

Field	Description
`holdersData.totalCount`	Total number of unique vault holders.
`holdersData.totalBalance`	Combined LP token balance across all holders.
`holdersData.topHolders[].address`	Address of a top holder.
`holdersData.topHolders[].lpTokenBalance`	LP token balance of that holder.

Capacity

Field	Description
`maxCapacity`	Maximum total deposit capacity enforced by the vault, in asset units. Omitted if uncapped.
`remainingCapacity`	How much more can be deposited before the cap is reached.

Fee Structure

Field	Description
`fees.performanceFee`	Percentage of yield taken by the protocol (as a decimal, e.g. `0.10` for 10%).
`fees.managementFee`	Annual fee on AUM (as a decimal).
`fees.withdrawalFee`	Fee charged on withdrawals (as a decimal).
`fees.depositFee`	Fee charged on deposits (as a decimal).

All fee fields are optional and omitted when not applicable to a given vault.

Flags and Warnings

Field	Description
`warnings`	Array of plain-text warning strings derived from active non-`info` flags. Kept for simple integrations that only need display text.
`flags[].content`	Flag message text.
`flags[].severity`	One of `info`, `warning`, or `critical`.
`flags[].endDate`	Unix timestamp when the flag expires. Past flags are not returned.
`flags[].resolution`	Optional resolution note explaining how the flagged issue was addressed. Omitted for unresolved flags.

Use flags to surface active protocol notices in your UI, such as paused deposits, ongoing audits, migration notices, or resolved incidents that are still within their display window. Use flags[].resolution when present to show that an issue has been mitigated or otherwise addressed. warnings is a convenience text array for backward-compatible displays. Prefer flags for new integrations because it includes severity, expiry, and resolution context. Active flags can reduce the vault’s Reputation Score. Resolved flags may still appear and may still contribute a reduced penalty while the Reputation Score recovers — see Flag penalties for how severity and decay work.

Transactional Support

Field	Description
`isTransactional`	Whether this vault supports the Transactions API for deposit, redeem, and claim flows.
`transactionalProperties.depositStepsType`	`instant` (single tx) or `complex` (multi-step, e.g. requires approval).
`transactionalProperties.redeemStepsType`	`instant` or `complex`.
`transactionalProperties.rewardsSupported`	Whether reward claim transactions are supported for this vault.

See Transaction Flows for full details on building deposit and withdrawal flows.

Other Metadata

Field	Description
`additionalIncentives`	Free-text description of any non-token incentives (e.g. points, airdrop eligibility).
`childrenVaults`	For aggregator vaults: the list of sub-vaults the vault allocates to, each with their own asset and LP token info.
`userEventsIndexed`	Whether deposit and withdrawal events for this vault are indexed and queryable via the portfolio endpoints.
`isCorrupted`	Flags vaults where the indexed data is known to be unreliable. Exclude these from production displays.

Historical Time-Series

The following is available from the historical endpoints (GET /v2/historical/{network}/{vaultId}). Each data point in the time series includes:

Field	Description
`timestamp`	Unix timestamp of the snapshot.
`blockNumber`	Block number of the snapshot.
`apy.base` / `apy.reward` / `apy.total`	APY breakdown at that point in time.
`tvl.usd` / `tvl.native`	TVL at that point in time.
`sharePrice`	Share price of the vault at that block.

Separate endpoints allow fetching APY-only, TVL-only, or share price-only history for lower cost. See Historical.

Near Real-Time Metrics

For applications that need the most current vault state (deposit previews, live dashboards, liquidation monitoring), the NRT endpoints query onchain state directly rather than relying on the hourly index.

Endpoint	Returns
`/v2/nrt/vault/{network}/{vaultId}`	All four metrics in one call
`/v2/nrt/vault/{network}/{vaultId}/sharePrice`	Current share price
`/v2/nrt/vault/{network}/{vaultId}/totalAssets`	Total assets in asset-wei
`/v2/nrt/vault/{network}/{vaultId}/totalSupply`	Total LP token supply in asset-wei
`/v2/nrt/vault/{network}/{vaultId}/underlyingAssetPrice`	Current USD price of the underlying asset

User Position Data

The portfolio endpoints return per-wallet position data for any vault where userEventsIndexed is true.

Current position

GET /v2/portfolio/positions/{userAddress}/{network}/{vaultId}

Field	Description
`asset.balanceNative`	Position value in the underlying asset’s native units.
`asset.balanceUsd`	Position value in USD (omitted if asset price unavailable).
`asset.unclaimedNative`	Unclaimed reward balance in native units.
`asset.unclaimedUsd`	Unclaimed reward value in USD.
`asset.positionValueInAsset`	Position value expressed in asset precision.
`lpToken.balanceNative`	LP token balance held by the user.
`lpToken.balanceUsd`	LP token balance in USD.
`lpToken.assetPriceInUsd`	Current LP token price in USD.

Total returns

GET /v2/portfolio/total-returns/{userAddress}/{network}/{vaultId}

Field	Description
`returnsNative`	Total yield earned by this address in this vault, in native token units.
`symbol` / `name` / `assetPriceInUsd`	Asset details for display.

Transaction history

GET /v2/portfolio/events/{userAddress}/{network}/{vaultId}

Field	Description
`eventType`	Transaction type: deposit, withdrawal, or reward claim.
`timestamp`	Unix timestamp of the transaction.
`assetAmountNative`	Asset amount moved, in native units.
`sharePrice`	LP token share price at time of transaction.
`lpTokenAmount`	Number of LP tokens minted or burned.
`transactionHash`	Onchain transaction hash.
`logIndex`	Log index for disambiguation within a block.

Overview

Core Concepts

Methodology

SDK

AI & Agents

Plans & Billing

Resources

Everything You Can Know About a Vault

Identity

Vault Tags

Protocol and Curator

The Asset

The LP Token

APY

Composite APY (nested vaults)

TVL

Advanced Analytics

Additional Rewards

Reputation Score

Holders

Capacity

Fee Structure

Flags and Warnings

Transactional Support

Other Metadata

Historical Time-Series

Near Real-Time Metrics

User Position Data

Current position

Total returns

Transaction history

​Everything You Can Know About a Vault

​Identity

​Vault Tags

​Protocol and Curator

​The Asset

​The LP Token

​APY

​Composite APY (nested vaults)

​TVL

​Advanced Analytics

​Additional Rewards

​Reputation Score

​Holders

​Capacity

​Fee Structure

​Flags and Warnings

​Transactional Support

​Other Metadata

​Historical Time-Series

​Near Real-Time Metrics

​User Position Data

​Current position

​Total returns

​Transaction history

Everything You Can Know About a Vault

Identity

Vault Tags

Protocol and Curator

The Asset

The LP Token

APY

Composite APY (nested vaults)

TVL

Advanced Analytics

Additional Rewards

Reputation Score

Holders

Capacity

Fee Structure

Flags and Warnings

Transactional Support

Other Metadata

Historical Time-Series

Near Real-Time Metrics

User Position Data

Current position

Total returns

Transaction history