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:

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

API 1.0 (Legacy)

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

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

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

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

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

API 2.0 Request

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

API 1.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

API 2.0 Response

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

   No need to construct transactions via endpoint one by one anymore. Simply create the action, 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 & 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 [e-mail].

---

Next Steps

API Reference

Current API documentation

Quickstart

Get started with v2