Yield.xyz’s most significant API upgrade is now live.
API 2.0 is a complete overhaul of the Yield.xyz integration experience. It standardizes how you discover, construct, and execute yield strategies; replacing fragmented workflows with a single, coherent model. Whether you're embedding staking, stablecoin, or Defi yields into your app , API 2.0 simplifies the stack, reduces integration time, and removes guesswork.
These backend improvements translate directly to better product experiences. With cleaner data and full transaction context available in a single call, your team can build faster, ship quicker, and deliver smoother UX to end users.
While it’s still in public beta: we’re polishing edge cases, tightening validation, and releasing tweaks to ensure the migration can be accomplished smoothly and the functionalities perform as expected.
What’s Changed
API 2.0 introduces upgrades across every layer of the developer experience. Here’s what’s new:
Unified Transaction Flow
API 1.0: Developers had to construct and fetch each transaction individually.
API 2.0: A single POST/actions/enter call returns all required transactions in sequence, fully populated and annotated. Just sign and submit; no per-tx construction required.
Schema-driven arguments
API 1.0: Payloads used custom, nested structures with inconsistent field names.
API 2.0: Every yield now exposes a schema under mechanics.arguments, detailing the fields, types, labels, and dropdown references you need to build dynamic forms and validate inputs. No more hardcoded args.
Unified action model
API 1.0: Enter, exit, and claim flows used different action patterns and required special handling.
API 2.0: One consistent pattern across all yield interactions: enter, exit, and manage. Whether you’re staking, depositing, claiming rewards, withdrawing, or restaking, the flow is the same and returns all ready-to-sign transactions in a single call.
Improved yield discovery
API 1.0: Filtering yields by network or token was limited.
API 2.0: Use advanced filters like inputToken, provider, and network. New /tokens, /networks and /providers endpoints give better visibility into what’s supported before you build.
Standardized Dto structure
API 1.0: Data objects used inconsistent naming conventions across modules.
API 2.0: All core objects follow a consistent, typed structure (YieldDto, ActionDto, YieldBalanceDto, ValidatorDto, etc.). Enums like ActionType and BalanceType are unified and reused across endpoints.
This reduces cognitive overhead and simplifies integration logic.
Clear separation of metadata and logic
API 1.0: UI-related fields and operational logic were mixed within the same payload.
API 2.0: details are split into clearly defined sections:
- metadata: name, description, logo, documentation
- mechanics: argument schemas, cooldowns, claim logic, and execution behavior
- rewardRate: a top-level field showing APR/APY with full breakdowns
This makes it easier to render UIs, power agents, and keep logic modular.
Transparent reward breakdowns
API 1.0: Yields showed a flat APY value with no context.
API 2.0: Each strategy includes a rewardRate.total and an array of components[] to show how the yield is composed (e.g., base, bonus, MEV, validator incentives). This provides better UX and more insight into performance.
Lifecycle-based balance tracking
API 1.0: Balance payloads were fragmented.
API 2.0: The new YieldBalanceDto format introduces:
- A standard lifecycle (entering, active, exiting, withdrawable, claimable, locked)
- A boolean isEarning field to check if the position is currently accruing rewards
- A usdAmount field for fiat-denominated balance views
- A pendingActions[] array to guide what the user can do next
- A validator field including metadata (e.g., name, status, commission, reward rate), reducing the need for additional joins or lookups when displaying validator-specific data.
This makes it easier to build rich, stateful UX without hardcoding state logic per strategy.
Performance and DX improvements
Beyond data modeling and endpoints, API 2.0 delivers under-the-hood improvements for smoother development:
- Paginated endpoints for large lists
- Leaner payloads and lower latency
- Cleaner validation errors with field-level detail
- Elimination of construct-tx calls — everything returned in one action response
Developer Update Checklist
If you’re already integrated with Yield.xyz, here’s what to update:
- Replace tx construct logic with POST /actions/{intent} → All transactions are returned in one response, ready to sign.
- Use mechanics.arguments to drive input forms → Arguments are schema-defined per yield — no hardcoding required.
- Structure your UI with metadata, mechanics, and rewardRate → Display and logic are cleanly separated.
- Fetch validators via /validators → Validator options are no longer inlined.
- Use BalanceDto.type, isEarning, validator, and pendingActions[] → Lifecycle-aware, validator-scoped, and fully actionable.
- Use amountUsd for fiat views → Every balance includes an approximate USD value.
- Migrate off legacy endpoints → v1 remains available but is no longer recommended.
Already integrated with us and want to know in more detail what the key differences are? We got you covered, click here and let us know if you have any feedback, we’re looking forward to it!
Start Building with API 2.0
API 2.0 is currently live beta and runs in parallel with v1 under the same API key. You can migrate and test individual flows gradually without disrupting your current integration.
Explore the updated documentation → https://docs.yield.xyz/
Have a question? Send us a message → hello@yield.xyz