Yield metadata

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.

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 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)
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[] 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, 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
`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
`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
`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 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 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.

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` (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: 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.

Get started

AI & Agents

Earn

Trade

Borrow

Security

Advanced setup

Plans & limits

FAQs

Identity

Tokens

Reward rate

Statistics and risk

Mechanics

Fee configurations

KYC requirements

Argument schemas

Status and lifecycle

Live state

Fund schedules and execution contracts

Next steps

Discover yields

Actions

​Identity

​Tokens

​Reward rate

​Statistics and risk

​Mechanics

​Fee configurations

​KYC requirements

​Argument schemas

​Status and lifecycle

​Live state

​Fund schedules and execution contracts

​Next steps

Discover yields

Actions

Identity

Tokens

Reward rate

Statistics and risk

Mechanics

Fee configurations

KYC requirements

Argument schemas

Status and lifecycle

Live state

Fund schedules and execution contracts

Next steps