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