> ## 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. # API 2.0 Migration Guide > Endpoint-by-Endpoint Comparison & Key Workflow Changes ## 1. High-Level Evolution | Area | Legacy (v1) | New (v2) | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | Action model | Separate "enter", "exit", and "pending" actions; each returns transaction IDs that must be constructed one-by-one. | Unified "enter", "exit", "manage" intents. One call returns all ready-to-sign transactions in order. | | Schema | Arguments documented per yield, but often custom field names and nesting (addresses, etc.). | Schema-driven: every yield exposes a formal `mechanics.arguments` schema that tells you exactly what to send. | | Validators | Usually embedded in the main yield response; a `/validators` endpoint also existed. | Kept separate for performance. Fetch with `GET /v1/yields/{yieldId}/validators` when needed. | | Transaction tracking | Submit hash per transaction. | Submit hash per transaction. | | Discovery filters | Limited filtering. | Advanced query params (input tokens, network, provider) plus `/networks` and `/providers` endpoints for context. | | Performance | Monolithic payloads, no pagination. | Pagination on large lists, leaner responses, lower latency. | | Interfaces | — | General overhaul of DTOs and interfaces to align concepts | *** ## 2. Yield Discovery & Metadata | Purpose | Legacy Endpoint | New Endpoint | What Changed | | --------------------- | ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | List all yields | `GET /v1/yields` | `GET /v1/yields` | Now paginated; validators no longer embedded. Adds full argument schema (`mechanics.arguments`) + Improved interface | | Single-yield metadata | `GET /v1/yields/{yieldId}` | `GET /v1/yields/{yieldId}` | Same as above | | Validator list | `GET /v1/yields/{yieldId}/validators` | `GET /v1/yields/{yieldId}/validators` | Improved interface | | Networks | `GET /v1/yields/networks` | `GET /v1/networks` | Improved interface | | Providers | — | `GET /v1/providers` | Added ability to discover providers | *** ## 3. Actions & Transaction Workflow ### Entering a Yield **Legacy — POST /v1/actions/enter** * Send payload with nested addresses and custom fields. * Response: action ID + list of transaction IDs. * For each ID call `PATCH /v1/transactions/{id}` to fetch unsigned tx. * Sign, broadcast, then submit hash per transaction. **New — POST /v1/actions/enter** Payload structure: ```json theme={null} { "yieldId": "tron-trx-native-staking", "address": "", "arguments": { "amount": "1", "validatorAddresses": [""], "tronResource": "ENERGY" } } ``` Response → one `ActionDto` containing every `TransactionDto` in order, fully populated and annotated. Sign, broadcast, then `PUT /v1/transactions/{transactionId}/submit-hash` to report each hash. No extra construct calls. ### Exiting / Unstaking * **Legacy** — `POST /v1/actions/exit` followed by per-transaction construct calls. * **New** — Same endpoint path, same one-shot transaction return pattern. ### Manage Actions (claims, restakes, redelegations) | Legacy (v1) | New (v2) | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `POST /v1/actions/pending` with `"action": "CLAIM_REWARDS"`, plus the passthrough blob supplied by the balance endpoint. | `POST /v1/actions/manage` with `"action": "CLAIM_REWARDS"` in arguments, plus the passthrough blob supplied by the balance endpoint. | | Construct transactions one by one | Same one-shot transaction return pattern. | *** ## 4. Balances | Purpose | Legacy Endpoint | New Endpoint | Notes | | -------------- | -------------------------- | ------------------------------------ | ------------------------------------------- | | Batch balances | `POST /v1/yields/balances` | `POST /v1/yields/balances` | More advanced request: See docs for details | | Single balance | — (POST only) | `POST /v1/yields/{yieldId}/balances` | Dedicated endpoint for single yield | Each balance payload directly includes any passthrough strings required for future manage calls. *** ## 5. Before / After Quick Reference | Step | Legacy v1 | New v2 | | ----------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Fetch validators for Cosmos staking | `GET /v1/yields/cosmos-atom-native-staking` (validators inline) | `GET /v1/yields/cosmos-atom-native-staking/validators` | | Stake 100 ATOM | `POST /v1/actions/enter` → multiple `PATCH /transactions/{id}` | `POST /v1/actions/enter` → ready-to-sign tx list returned directly | | Claim rewards | `POST /v1/actions/pending` with `"action":"CLAIM_REWARDS"` and passthrough | `POST /v1/actions/manage` with `"action":"CLAIM_REWARDS"` in args | *** ## 6. Additional Notable Changes * **Hostname** has moved from `api.stakek.it` to `api.yield.xyz`. * **Terminology**: `integrationId` → `yieldId`; "pending actions" → manage actions. * **Pagination**: large lists (yields, validators) return `limit` and `offset`. * **Error clarity**: validation errors now cite the exact missing or malformed field. *** ## 7. Detailed Side-by-Side Comparison of Naming and DTOs ### YieldDto Comparison ```json theme={null} { "id": "ethereum-matic-native-staking", "token": { "network": "ethereum", "name": "Polygon Ecosystem Token", "decimals": 18, "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6", "symbol": "POL" }, "args": { "enter": { "addresses": { "address": { "required": true, "network": "ethereum" } }, "args": { "amount": { "required": true, "minimum": 1 }, "validatorAddress": { "required": true } } } }, "status": { "enter": true, "exit": true }, "apy": 0.03957252184265532, "rewardRate": 0.03957252184265532, "rewardType": "apr", "metadata": { "name": "Native Staking", "type": "staking", "rewardSchedule": "day", "cooldownPeriod": { "days": 2 }, "rewardClaiming": "manual" }, "validators": [ { "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951", "name": "Luganodes", "apr": 0.034445959222433965 } ], "isAvailable": true } ``` ```json theme={null} { "id": "ethereum-matic-native-staking", "network": "ethereum", "inputTokens": [ { "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6", "decimals": 18, "name": "Polygon Ecosystem Token", "symbol": "POL", "network": "ethereum" } ], "token": { "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6", "decimals": 18, "name": "Polygon Ecosystem Token", "symbol": "POL", "network": "ethereum" }, "rewardRate": { "total": 0.03957252184265532, "rateType": "APR", "components": [ { "rate": 0.03957252184265532, "rateType": "APR", "token": { "symbol": "POL" }, "yieldSource": "staking", "description": "Earn staking rewards" } ] }, "status": { "enter": true, "exit": true }, "metadata": { "name": "Native Staking", "description": "Stake your MATIC natively", "documentation": "https://docs.yield.xyz" }, "mechanics": { "type": "staking", "rewardSchedule": "day", "rewardClaiming": "manual", "requiresValidatorSelection": true, "cooldownPeriod": { "seconds": 172800 }, "arguments": { "enter": { "fields": [ { "name": "amount", "type": "string", "required": true }, { "name": "validatorAddress", "type": "address", "required": true } ] } } }, "providerId": "", "tags": ["ethereum", "POL", "staking"] } ``` **Key differences:** * **Schema-driven arguments** – v2 introduces structured `mechanics.arguments` for enter, exit, and manage actions * **Top-level token definitions** – v2 exposes `inputTokens` and `token` at the root * **Normalized reward rate format** – `rewardRate` in v2 includes detailed breakdown via `components[]` * **Separated metadata and mechanics** – v2 cleanly separates UI-facing display data from execution logic *** ### YieldBalanceDto Comparison ```json theme={null} [ { "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5", "type": "staked", "amount": "4.000000000000000000", "pricePerShare": "1.00308", "pendingActions": [], "token": { "symbol": "POL" }, "validatorAddress": "0x35B1CA0F..." }, { "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5", "type": "rewards", "amount": "0.012320444949004356", "pricePerShare": "1.00308", "pendingActions": [], "token": { "symbol": "POL" }, "validatorAddress": "0x35B1CA0F..." } ] ``` ```json theme={null} { "yieldId": "ethereum-matic-native-staking", "balances": [ { "address": "0x6877BB79f680216BbdF01704939037F22193e771", "amount": "4.012320000000000000", "amountRaw": "4012320000000000000", "type": "active", "token": { "symbol": "POL", "network": "ethereum" }, "pendingActions": [], "amountUsd": "0.753225", "isEarning": true, "validator": { "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951", "name": "Luganodes", "rewardRate": { "total": 0.034445959222433965, "rateType": "APR" } } }, { "address": "0x6877BB79f680216BbdF01704939037F22193e771", "amount": "0.012358391919447289", "amountRaw": "12358391919447289", "type": "claimable", "token": { "symbol": "POL" }, "pendingActions": [], "amountUsd": "0.002320", "isEarning": false, "validator": { "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951" } } ] } ``` **Key differences:** * **Unified Lifecycle States** – v2 replaces `"staked"`, `"rewards"` with consistent types: `active`, `claimable`, `withdrawable`, `entering`, `exiting`, `locked` * **Flattened Balance Structure** – v2 eliminates grouped balances in favor of flat positions * **Simplified Amount Handling** – v2 standardizes on `amount`, `amountRaw`, and `amountUsd` * **Embedded Validator Metadata** – v2 includes full validator metadata directly on each balance *** ### ActionDto Comparison (Enter-Stake Flow) ```json theme={null} { "addresses": { "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx" }, "integrationId": "tron-trx-native-staking", "args": { "tronResource": "ENERGY", "amount": "1", "validatorAddresses": ["TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"] } } ``` ```json theme={null} { "yieldId": "tron-trx-native-staking", "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx", "arguments": { "amount": "1", "validatorAddresses": ["TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"], "tronResource": "ENERGY" } } ``` ```json theme={null} { "id": "65be9010-2a52-41d6-9389-9594e2a0e1fd", "integrationId": "tron-trx-native-staking", "status": "CREATED", "type": "STAKE", "transactions": [ { "id": "a89db9a6-d0e8-4d43-addd-c00c800c5a3d", "status": "CREATED", "type": "FREEZE_ENERGY", "unsignedTransaction": null } ] } ``` *In v1, developers were required to call `PATCH /transaction/{id}` per transaction step to get the `unsignedTransaction`* ```json theme={null} { "id": "0d5a5efd-c8e6-4908-9650-2e10dea9f782", "intent": "enter", "type": "STAKE", "yieldId": "tron-trx-native-staking", "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx", "amount": "1", "amountRaw": "1000000", "amountUsd": "0.29", "transactions": [ { "id": "e3ea6342-44fd-423f-97b5-aed43cfa1399", "title": "FREEZE_ENERGY Transaction", "status": "CREATED", "type": "FREEZE_ENERGY", "unsignedTransaction": "{...fully populated...}", "stepIndex": 0, "gasEstimate": "{\"amount\":\"0.000251\"}" }, { "id": "ab2e16c8-8845-4b8d-8799-fc39078211c1", "title": "VOTE Transaction", "status": "CREATED", "type": "VOTE", "unsignedTransaction": "{...fully populated...}", "stepIndex": 1, "gasEstimate": "{\"amount\":\"0.000268\"}" } ], "executionPattern": "synchronous", "status": "CREATED" } ``` **Key differences:** * **Schema-driven requests** – v2 replaces nested `args` with top-level `arguments` object * **Unified action structure** – All actions return same `ActionDto` format with `intent`, `type`, `yieldId` * **Transactions included by default** – v2 embeds `unsignedTransaction`, `structuredTransaction`, `annotatedTransaction` directly * **Gas estimates and step metadata** – Each transaction includes `gasEstimate`, `stepIndex`, and `title` *** ## Migration Tips Always pull `GET /v1/yields/{id}` and build your request exactly as that schema dictates. No need to construct transactions via endpoint one by one anymore. Simply create the action, sign and submit each transaction! v1 and v2 can run side by side under the same API key—migrate flow by flow. Use the balance endpoint to capture any passthrough needed for manage actions. *** ## Developer Update Checklist Switch to `yieldId`, `metadata.*`, `rewardRate.*`, lifecycle `type` Read `yield.mechanics.arguments` to create forms; note `validatorAddress` (string) vs `validatorAddresses` (array) Use `/validators` endpoint - no inline arrays Drive labels/buttons from `balance.type` and `pendingActions` One create-action call → sign each `TransactionDto` → `PUT /submit-hash`; no construct-tx calls needed Update TypeScript interfaces to match new DTO structures *** ## Support If you need help migrating, contact [hello@yield.xyz](mailto:hello@yield.xyz). *** ## Next Steps Current API documentation Get started with v2