API 2.0 migration guide

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 and the enter and exit guide.

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:

{
  "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)
API 2.0 (Current)

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

{
    "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)
API 2.0 (Current)

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

{
    "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
API 2.0 request

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

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

API 1.0 response
API 2.0 response

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

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

Drive everything from the schema

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

Remove transaction construction logic

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

Test in parallel

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

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.

Next steps

API reference

Current API documentation

Quickstart

Get started with v2

Get started

AI & Agents

Earn

Trade

Borrow

Widgets & UI

Dashboards

Integrations & signing

Legacy & migration

API 2.0 migration guide

What changed at a glance

Yield discovery and metadata

Actions and transaction workflow

Entering a yield

Exiting or unstaking

Manage actions (claims, restakes, redelegations)

Balances

Before and after quick reference

Other notable changes

Side-by-side naming and DTO comparison

YieldDto comparison

YieldBalanceDto comparison

ActionDto comparison (enter stake flow)

Migration tips

Developer update checklist

Rename and map fields

Generate UI from schema

Fetch validators separately

Use balance lifecycle

Simplify actions

Update types

Support

Next steps

API reference

Quickstart

​What changed at a glance

​Yield discovery and metadata

​Actions and transaction workflow

​Entering a yield

​Exiting or unstaking

​Manage actions (claims, restakes, redelegations)

​Balances

​Before and after quick reference

​Other notable changes

​Side-by-side naming and DTO comparison

​YieldDto comparison

​YieldBalanceDto comparison

​ActionDto comparison (enter stake flow)

​Migration tips

​Developer update checklist

Rename and map fields

Generate UI from schema

Fetch validators separately

Use balance lifecycle

Simplify actions

Update types

​Support

​Next steps

API reference

Quickstart

What changed at a glance

Yield discovery and metadata

Actions and transaction workflow

Entering a yield

Exiting or unstaking

Manage actions (claims, restakes, redelegations)

Balances

Before and after quick reference

Other notable changes

Side-by-side naming and DTO comparison

YieldDto comparison

YieldBalanceDto comparison

ActionDto comparison (enter stake flow)

Migration tips

Developer update checklist

Support

Next steps