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.

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

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

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:

{
  "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 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

Discover yields

Filter and page through the yields enabled for your project.

Actions

Use the argument schemas to build enter, exit, and manage flows.