> ## Documentation Index > Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Yield metadata > Read the model behind a YieldDto: identity, tokens, rates, mechanics, argument schemas, and live state. Every yield opportunity is one `YieldDto`, returned by `GET /v1/yields/{yieldId}` (or in the list from `GET /v1/yields`). It carries everything you need to render the opportunity, 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). ## 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 | | `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/platform/incentive-campaigns)) * `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). ## 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[]` lists top-level provider risk grades by source (`credora`, `stakingRewards`) when available. It's a summary; the full report comes from `GET /v1/yields/{yieldId}/risk`. ## 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#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 | | `fee`, `possibleFeeTakingMechanisms` | What this yield charges, and which fee types you can configure to earn on it. See [Monetization](/documentation/earn/monetization) | ## 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) 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, tick bounds, fee tier, 24h volume and fees, and TVL | | `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 multiple underlying strategies (address, network, name, allocation, weight, target weight) | ## Fund schedules and execution contracts Two fields apply mainly to RWA and custody-constrained integrations: * `investmentSchedule`: present on fund-style RWA yields. Defines subscription and redemption windows, cadence, settlement, and accrual timing per side, layered on top of `cooldownPeriod` and `status` * `executionContracts`: the on-chain contract addresses transactions for this yield may target (`tx.to`), used by custody providers that whitelist execution destinations ## Next steps Filter and page through the yields enabled for your project. 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.