> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Yield metadata

> Read the model behind a YieldDto: identity, tokens, rates, risk, mechanics, fees, KYC requirements, argument schemas, live state and fund schedules.

Every yield opportunity is one `YieldDto`, returned by `GET /v1/yields/{yieldId}` (or in the list from `GET /v1/yields`). Every yield uses the same format, whatever the protocol. It carries what you need to render the opportunity (the reward rate and its breakdown, TVL, entry limits, cooldowns, and fees), validate input, and drive an action, grouped below by what each group is for. For the exact schema, see the [API reference](/api-reference/YieldsController_getYield.md).

## Identity

| Field | What it tells you |
| - | - |
| `id` | Canonical identifier, used in every action, balance, and history call |
| `network` / `chainId` | The chain the yield runs on; `chainId` is present only for EVM networks |
| `providerId` | The protocol or operator behind the yield, e.g. `lido`, `morpho` |
| `metadata.name` / `description` / `logoURI` / `documentation` | Display name, a short description, a logo, and a link to the protocol's own docs |
| `curator` | Curator name, description, and logo, when the yield is curator-managed |
| `tags` | Free-form categorization tags |
| `metadata.supportedStandards` | Token standards the yield supports: `ERC20`, `ERC4626`, `ERC721`, `ERC1155` |
| `metadata.supportsCampaigns` | Whether you can run an [incentive campaign](/documentation/earn/incentive-campaigns.md) on this yield |
| `prime` | Whether the yield currently meets Yield.xyz's Prime quality bar (TVL, provider risk grade, and a rate-outlier check). Evaluated globally on a schedule, so the value is the same for every caller. Filter to Prime-only with `?prime=true` on `GET /v1/yields` |

## Tokens

| Field | What it tells you |
| - | - |
| `inputTokens` | Tokens you can enter with; Yield.xyz converts them as needed |
| `token` / `tokens` | The yield's canonical deposit token(s), used for balances (`token` is singular, `tokens` the array form) |
| `outputToken` | The token you receive back, when the yield issues one, e.g. `stETH` or a vault share. Absent for yields that don't mint a receipt token |

## Reward rate

`rewardRate` is the yield's current estimated return, not its history. It has:

* `total`: the estimated rate across all sources, which can include a campaign component when one applies to your project (see [Incentive Campaigns](/documentation/earn/incentive-campaigns.md))
* `rateType`: `APR` or `APY`. APR is the simple annualized rate; APY compounds it. For most yields the type follows the mechanics: vault, lending, and real-world-asset yields report `APY`; other types report `APY` when rewards compound automatically and `APR` when they need a manual claim. Read `rateType` rather than assuming it
* `components[]`: the breakdown behind `total`, each with its own `rate`, `rateType`, `token`, `yieldSource`, and an optional `description`

`yieldSource` is one of: `staking`, `liquid_staking`, `restaking`, `protocol_incentive`, `campaign_incentive`, `points`, `lending`, `mev`, `real_world_asset_yield`, `vault`.

For historical APY and TVL, see [Rewards and history](/documentation/earn/core-concepts/rewards-history.md).

## Statistics and risk

`statistics` is a current snapshot, not a time series: `tvlUsd`, `tvl` (in the underlying token), `tvlRaw`, `uniqueUsers`, `averagePositionSizeUsd`, and `averagePositionSize`. Some fields are `null` when the yield isn't ERC-4626 or indexing hasn't run yet.

`risk.ratings[]` aggregates the grades published by third-party raters (`credora`, `stakingRewards`) and is returned only for the yields those raters cover. It is a summary; the full report comes from [`GET /v1/yields/{yieldId}/risk`](/api-reference/YieldsController_getYieldRisk), with an `updatedAt` timestamp and one object per source:

| Source | Fields |
| - | - |
| `credora` | `rating`, `score`, `psl` (annualized probability of significant loss), `publishDate`, and `curator` where the rating is for a curated vault |
| `stakingRewards` | `rating` and `score`, `potentialRating` and `potentialScore`, `ratedAt`, `ratedSince`, `profileUrl`, `reportUrl`, `providerName`, `version`, `type`, `chain`, `contractAddress`, and `riskMetrics` |

Independent ratings that agree are a stronger signal than one score on its own. Fields are `null` when a source has not rated the yield.

## Mechanics

`mechanics` is the operational contract: what the yield requires and how it behaves.

| Field | What it tells you |
| - | - |
| `type` | The yield type, such as `staking`, `lending`, `vault` or `real_world_asset`. Exact values are listed under [Yield types](/api-reference/earn-objects.md#yield-types) |
| `requiresValidatorSelection` | Whether entering requires picking a validator |
| `rewardSchedule` | How often rewards are distributed: `block`, `hour`, `day`, `week`, `month`, `era`, `epoch`, or `campaign` |
| `rewardClaiming` | `auto` (rewards compound automatically) or `manual` (a claim action is required) |
| `lockupPeriod` / `cooldownPeriod` / `warmupPeriod` | Each a duration in seconds: minimum hold before exit can start, delay after exit before funds are free, and delay before a new position starts earning |
| `entryLimits.minimum` / `maximum` | Amount bounds in token units; `null` means no limit |
| `entryLimits.subsequentMinimum` | Minimum for deposits after the user already holds the asset; `null` falls back to `minimum` |
| `requirements.kycRequired` | Whether off-chain KYC gates entering this yield. When it does, `requirements.kyc` describes the requirement; see [KYC requirements](#kyc-requirements) |
| `fee` | What the protocol itself charges, as percentage strings: `deposit`, `withdrawal`, `management` (annual) and `performance`, for example `"20.00"` for 20% |
| `possibleFeeTakingMechanisms` | Which fee types you can configure to earn on this yield: `depositFee`, `managementFee`, `performanceFee`, `validatorRebates`. See [Monetization](/documentation/earn/monetization.md) |
| `gasFeeToken` | The token gas is paid in, usually the network's native token |
| `supportsLedgerWalletApi` | Whether the yield can be used through the Ledger Wallet API, from Ledger Live |
| `extraTransactionFormatsSupported` | Transaction formats available beyond the default, such as `raw` |

## Fee configurations

`feeConfigurations[]` lists the fee setups live for your project on this yield, when it supports fees. Each entry has:

| Field | What it tells you |
| - | - |
| `id` | Pass it as `feeConfigurationId` on an action to use a configuration other than the default |
| `default` | Whether this is the configuration applied when you don't pass one |
| `depositFeeBps` / `managementFeeBps` / `performanceFeeBps` | Your fees in basis points, `null` when not set |
| `allocatorVaultContractAddress` | The [OAV](/documentation/earn/oavs/single-strategy.md) that carries these fees, when the configuration is vault-based |
| `statistics` | TVL and user statistics for that configuration's vault |

Only live configurations appear. See [Monetization](/documentation/earn/monetization.md) for how they are created.

## KYC requirements

When `mechanics.requirements.kycRequired` is `true`, `mechanics.requirements.kyc` carries the public criteria you need to render a verification step before the user tries to enter:

| Field | What it tells you |
| - | - |
| `kycMode` | How the issuer delivers KYC: `oauth_redirect`, `external_redirect`, `iframe`, `deeplink`, `native_sdk` or `none` |
| `iframeAllowed` | Whether the issuer's KYC page may be embedded in an iframe |
| `authorizeUrl` | The issuer-hosted KYC page, when there is one |
| `notes` | Human-readable notes about the requirement |
| `mandatoryDisclosureUrl` | A regulator-mandated disclosure document the user should see |
| `selfAttestation` | Documents the user must accept before entering (`documents[].url`), with `notes` |
| `eligibility` | Who may enter, below |

`eligibility` describes jurisdictions and investor types:

* `defaultPolicy`: `deny` (only listed `countries` may enter) or `allow` (anyone except blocked jurisdictions)
* `countries`, `blockedCountries` (ISO 3166-1 alpha-2) and `blockedSubdivisions` (ISO 3166-2, for example `UA-43`)
* `usPersonAllowed`, and `geoBlockingEnforced` when the issuer enforces geo-blocking itself
* `subjectTypes`: `KYC` for individuals, `KYB` for businesses, or both
* `investorEligibility[]`: per jurisdiction (a country code, `EEA`, `GCC` or `*`), the investor `tier` required, such as `us_accredited`, `us_qualified_purchaser`, `eu_professional` or `sg_ai`, how it must be verified (`verificationLevel`: `self_attested`, `verified_documentation`, `letter` or `third_party_attestation`) and, if needed, `expiresAfterDays` for re-verification

A wallet's own status comes from `GET /v1/yields/{yieldId}/kyc/status`. See [RWA KYC](/documentation/earn/rwas/kyc.md).

## Argument schemas

`mechanics.arguments` defines what each action on this yield needs, before you call it: `enter` and `exit` are each one `ArgumentSchemaDto`; `manage` is a map of one `ArgumentSchemaDto` per supported action type (`CLAIM_REWARDS`, `CLAIM_UNSTAKED`, and others); `balance` covers extra fields the balances call needs, such as alternative addresses.

Each `ArgumentSchemaDto` is a list of fields:

```json theme={null}
{
  "fields": [
    {
      "name": "amount",
      "type": "number",
      "label": "Amount to enter",
      "required": true,
      "minimum": "0.01",
      "maximum": null
    },
    {
      "name": "validatorAddress",
      "type": "string",
      "label": "Validator",
      "required": true,
      "optionsRef": "v1/yields/{yieldId}/validators"
    }
  ]
}
```

`name` is one of a fixed set of argument names (`amount`, `validatorAddress`, `duration`, and others); `type` is `string`, `number`, `address`, `enum`, or `boolean`; `optionsRef` points to the endpoint that lists the valid choices, such as a yield's validators (`GET /v1/yields/{yieldId}/validators`). Read this schema before calling [actions](/documentation/earn/core-concepts/actions.md) instead of hardcoding fields per protocol.

## Status and lifecycle

| Field | What it tells you |
| - | - |
| `status.enter` | Whether entering is currently available |
| `status.exit` | Whether exiting is currently available |
| `metadata.underMaintenance` | Whether the yield is temporarily under maintenance |
| `metadata.deprecated` | Whether the yield is deprecated and will be discontinued |

## Live state

`state` carries dynamic, protocol-level values, present only where they apply to the yield's type:

| Field | What it tells you |
| - | - |
| `pricePerShareState` | Current share price (e.g. a vault share), with the share token and the quote token it's denominated in |
| `concentratedLiquidityPoolState` | Pool state for concentrated liquidity pool yields: `price` (token1 per token0), `baseApr` (full-range trading APR), `tickSpacing`, `minTick` and `maxTick` so a UI can snap ranges, `feeTier` as a decimal, `volume24hUsd`, `fee24hUsd`, `tvlUsd`, and the `baseToken` and `quoteToken` |
| `capacityState` | Current usage against capacity: `current`, `max`, and `remaining`, when the yield has a cap |
| `liquidityState` | Available liquidity and utilization rate, for lending or liquidity-bounded yields |
| `allocations` | Per-strategy breakdown for vault yields that allocate across several underlying strategies, such as a [Meta Vault](/documentation/earn/oavs/meta-vaults/index.md): each strategy's `address`, `network`, `name`, `yieldId` and `providerId` where it is also a yield, `allocation` and `allocationUsd`, current `weight` and `targetWeight` (0 to 100), `rewardRate`, `tvl` and `tvlUsd`, and `maxCapacity` and `remainingCapacity` |

## Fund schedules and execution contracts

Two fields apply mainly to RWA and custody-constrained integrations:

* `executionContracts`: the on-chain contract addresses transactions for this yield may target (`tx.to`), used by custody providers that whitelist execution destinations.
* `investmentSchedule`: present on fund-style RWA yields. It layers subscription and redemption timing on top of `cooldownPeriod` and `status`.

`investmentSchedule` has a `timezone`, optional `notes`, and a `subscription` and a `redemption` side. Each side lists `paths[]`, the ways to act on it, with `paths[0]` as the default. A fund can offer an `instant` path, for example an on-demand redemption pool, next to a `standard` one. Each path has:

| Field | What it tells you |
| - | - |
| `kind` | `instant` or `standard` |
| `cadence` | `continuous`, `daily_cutoff`, `periodic` or `scheduled` |
| `status` | `open`, `closed` or `settling`, kept current |
| `businessDaysOnly` | `true` when the path runs on market days only |
| `cutoffTime` | For `daily_cutoff`, the local time orders must be in by, such as `"16:00"` |
| `currentWindow` / `nextWindow` | `opensAt` and `closesAt` of the window the user is acting into, and the next one to count down to |
| `settlement` | `type` (`atomic`, `next_business_day`, `cohort` or `cooldown`), `marketDays` for T+N, `estimatedDuration` or `estimatedSettlementAt`, `claimRequired` when the user must claim settled funds on-chain, and `instantPortion` with `deferredDeliveryAt` for split delivery |
| `accrual` | When earning starts: `startsAt` (`immediate`, `next_business_day`, `on_cycle_start` or `on_settlement`), `startsAtDate`, and `minimumHold` before redemption |
| `limits` | Caps on an instant path or liquidity pool: per-user and global 24-hour limits, `globalRemainingPer24h`, `maxFractionOfNav`, `liquidityBounded` with `availableLiquidity`, and a path-specific `minimumAmount` |
| `fee` | A fee the path charges on the amount, such as an instant redemption fee |

Use the schedule to show users when a subscription or redemption will execute and settle before they confirm.

## Next steps

> **[Discover yields](/documentation/earn/core-concepts/discover.md)**
>
> Filter and page through the yields enabled for your project.

> **[Actions](/documentation/earn/core-concepts/actions.md)**
>
> Use the argument schemas to build enter, exit, and manage flows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.