> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API 2.0 migration guide

> Move a legacy (v1) integration to the current Earn API, endpoint by endpoint, with the key workflow and schema changes.

Use this page to move an integration built on the legacy (v1) API to the current Earn API. It maps each legacy endpoint and field to its current equivalent; for the current model itself, see [Actions](/documentation/earn/core-concepts/actions.md) and the [enter and exit guide](/guides/earn/enter-exit-flows.md).

## What changed at a glance

| 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, for example for addresses. | 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 | None | General overhaul of DTOs and interfaces to align concepts |

***

## Yield discovery and 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 | None | `GET /v1/providers` | Added ability to discover providers |

***

## Actions and 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": "<user address>",
  "arguments": {
    "amount": "1",
    "validatorAddresses": ["<validator>"],
    "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 or 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 top-level `"action": "CLAIM_REWARDS"` next to the passthrough blob supplied by the balance endpoint. |
| Construct transactions one by one | Same one-shot transaction return pattern. |

***

## 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 | None (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.

***

## Before and 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 top-level `"action":"CLAIM_REWARDS"` and `passthrough` |

***

## Other 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.

***

## Side-by-side naming and DTO comparison

### YieldDto comparison

**API 1.0 (Legacy)**

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

**API 2.0 (Current)**

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

**API 1.0 (Legacy)**

```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..."
    }
]
```

**API 2.0 (Current)**

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

**API 1.0 request**

```json theme={null}
{
    "addresses": { "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx" },
    "integrationId": "tron-trx-native-staking",
    "args": {
        "tronResource": "ENERGY",
        "amount": "1",
        "validatorAddresses": ["TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"]
    }
}
```

**API 2.0 request**

```json theme={null}
{
    "yieldId": "tron-trx-native-staking",
    "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx",
    "arguments": {
        "amount": "1",
        "validatorAddresses": ["TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"],
        "tronResource": "ENERGY"
    }
}
```

**API 1.0 response**

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

**API 2.0 response**

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

**1. Drive everything from the schema**

Always pull `GET /v1/yields/{id}` and build your request exactly as that schema dictates.

**2. Remove transaction construction logic**

You no longer construct transactions one endpoint call at a time: create the action, then sign and submit each transaction.

**3. Test in parallel**

v1 and v2 can run side by side under the same API key: migrate flow by flow.

**4. Use balance endpoint for passthrough**

Use the balance endpoint to capture any passthrough needed for manage actions.

***

## Developer update checklist

> **Rename and map fields**
>
> Switch to `yieldId`, `metadata.*`, `rewardRate.*`, lifecycle `type`

> **Generate UI from schema**
>
> Read `yield.mechanics.arguments` to create forms; note `validatorAddress` (string) vs `validatorAddresses` (array)

> **Fetch validators separately**
>
> Use `/validators` endpoint - no inline arrays

> **Use balance lifecycle**
>
> Drive labels/buttons from `balance.type` and `pendingActions`

> **Simplify actions**
>
> One create-action call → sign each `TransactionDto` → `PUT /submit-hash`; no construct-tx calls needed

> **Update types**
>
> Update TypeScript interfaces to match new DTO structures

***

## Support

If you need help migrating, contact [hello@yield.xyz](mailto:hello@yield.xyz).

***

## Next steps

> **[API reference](/api-reference/getting-started.md)**
>
> Current API documentation

> **[Quickstart](/documentation/get-started/quickstart.md)**
>
> Get started with v2


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.