Guides
Log inRegister interest
Start typing to search…

API 2.0 Migration Guide

Endpoint-by-Endpoint Comparison & Key Workflow Changes

1. High-Level Evolution

AreaLegacy (v1)New (v2)
Action modelSeparate “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.
SchemaArguments 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.
ValidatorsUsually 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 trackingSubmit hash per transaction.Submit hash per transaction.
Discovery filtersLimited filtering.Advanced query params (input tokens, network, provider) plus /networks and /providersendpoints for context.
PerformanceMonolithic payloads, no pagination.Pagination on large lists, leaner responses, lower latency.
InterfacesGeneral overhaul of Dtos and interfaces to align concepts

2. Yield Discovery & Metadata

PurposeLegacy EndpointNew EndpointWhat Changed
List all yieldsGET /v1/yieldsGET /v1/yieldsNow paginated; validators no longer embedded. Adds full argument schema (mechanics.arguments) + Improved interface
Single-yield metadataGET /v1/yields/{yieldId}GET /v1/yields/{yieldId}Same as above
Validator listGET /v1/yields/{yieldId}/validatorsGET /v1/yields/{yieldId}/validatorsImproved interface
NetworksGET /v1/yields/networksGET /v1/networksImproved interface
Providers—GET /v1/providersAdded ability to discover providers

3. Actions & Transaction Workflow

Entering a Yield

  • Legacy — POST /v1/actions/enter

    1. Send payload with nested addresses and custom fields.
    2. Response: action ID + list of transaction IDs.
    3. For each ID call PATCH /v1/transactions/{id} to fetch unsigned tx.
    4. 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/actions/{actionId}/transactions/{index}/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 "arguments": { "action": "CLAIM_REWARDS", ... } plus the passthrough blob supplied by the balance endpoint.
Construct transactions one by oneSame one-shot transaction return pattern.

4. Balances

PurposeLegacy EndpointNew EndpointNotes
Batch balancesPOST /v1/yields/balancesPOST /v1/yields/balancesMore advanced request: See docs for more details
Single balance— (POST only)GET /v1/yields/{yieldId}/balances?address=Read-only GET for quick look-ups.

Each balance payload directly includes any passthrough strings required for future manage calls.

5. Before / After Quick Reference

StepLegacy v1New v2
Fetch validators for Cosmos stakingGET /v1/yields/cosmos-atom-native-staking (validators inline)GET /v1/yields/cosmos-atom-native-staking/validators
Stake 100 ATOMPOST /v1/actions/enter → multiple PATCH /transactions/{id}POST /v1/actions/enter → ready-to-sign tx list returned directly
Claim rewardsPOST /v1/actions/pending with "action":"CLAIM_REWARDS"and passthroughPOST /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

Concrete JSON Diffs

YieldDto

API 1.0 (example)

{
    "id": "ethereum-matic-native-staking",
    "token": {
        "network": "ethereum",
        "name": "Polygon Ecosystem Token",
        "decimals": 18,
        "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
        "symbol": "POL",
        "logoURI": "https://assets.stakek.it/tokens/pol.svg",
        "coinGeckoId": "polygon-ecosystem-token"
    },
    "tokens": [
        {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        {
            "network": "ethereum",
            "name": "Polygon",
            "decimals": 18,
            "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
            "symbol": "MATIC",
            "logoURI": "https://assets.stakek.it/tokens/matic.svg",
            "coinGeckoId": "matic-network"
        }
    ],
    "args": {
        "enter": {
            "addresses": {
                "address": {
                    "required": true,
                    "network": "ethereum"
                }
            },
            "args": {
                "amount": {
                    "required": true,
                    "minimum": 1
                },
                "validatorAddress": {
                    "required": true
                },
                "inputToken": {
                    "required": false,
                    "options": [
                        {
                            "network": "ethereum",
                            "name": "Polygon Ecosystem Token",
                            "decimals": 18,
                            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                            "symbol": "POL",
                            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                            "coinGeckoId": "polygon-ecosystem-token"
                        },
                        {
                            "network": "ethereum",
                            "name": "Polygon",
                            "decimals": 18,
                            "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
                            "symbol": "MATIC",
                            "logoURI": "https://assets.stakek.it/tokens/matic.svg",
                            "coinGeckoId": "matic-network"
                        }
                    ]
                }
            }
        },
        "exit": {
            "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",
        "logoURI": "https://assets.stakek.it/tokens/matic.svg",
        "description": "Stake your MATIC natively",
        "documentation": "https://docs.stakek.it/docs/ethereum-matic-native-staking",
        "gasFeeToken": {
            "network": "ethereum",
            "name": "Ethereum",
            "symbol": "ETH",
            "decimals": 18,
            "coinGeckoId": "ethereum",
            "logoURI": "https://assets.stakek.it/tokens/eth.svg"
        },
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "tokens": [
            {
                "network": "ethereum",
                "name": "Polygon Ecosystem Token",
                "decimals": 18,
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "coinGeckoId": "polygon-ecosystem-token"
            },
            {
                "network": "ethereum",
                "name": "Polygon",
                "decimals": 18,
                "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
                "symbol": "MATIC",
                "logoURI": "https://assets.stakek.it/tokens/matic.svg",
                "coinGeckoId": "matic-network"
            }
        ],
        "type": "staking",
        "rewardSchedule": "day",
        "cooldownPeriod": {
            "days": 2
        },
        "warmupPeriod": {
            "days": 0
        },
        "rewardClaiming": "manual",
        "supportsMultipleValidators": true,
        "supportsLedgerWalletApi": true,
        "revshare": {
            "enabled": false
        },
        "fee": {
            "enabled": false,
            "depositFee": false,
            "managementFee": false,
            "performanceFee": false
        }
    },
    "validators": [
        {
            "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951",
            "status": "active",
            "name": "Luganodes",
            "image": "https://assets.stakek.it/validators/luganodes.png",
            "website": "https://luganodes.com/",
            "apr": 0.034445959222433965,
            "commission": 0.1,
            "stakedBalance": "261849883",
            "votingPower": 0.0007025174416982057,
            "preferred": true,
            "providerId": "9ef6235e-b039-4619-8307-c675d374ef8c"
        },
        {
            "address": "0xF30Cf4ed712D3734161fDAab5B1DBb49Fd2D0E5c",
            "status": "active",
            "name": "Everstake",
            "image": "https://assets.stakek.it/validators/everstake.png",
            "website": "https://everstake.one/link/stake",
            "apr": 0.038273288024926626,
            "commission": 0,
            "stakedBalance": "88674976",
            "votingPower": 0.00023790622538551905,
            "preferred": true,
            "providerId": "71535f4e-0f56-409c-88ac-86ad7f92156b"
        },
        
        ....
        ....
     "isAvailable": true,
    "feeConfigurations": []
}

API 2.0 (example)

{
    "id": "ethereum-matic-native-staking",
    "network": "ethereum",
    "inputTokens": [
        {
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "decimals": 18,
            "name": "Polygon Ecosystem Token",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "network": "ethereum",
            "isPoints": false,
            "coinGeckoId": "polygon-ecosystem-token"
        },
        {
            "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
            "decimals": 18,
            "name": "Polygon",
            "symbol": "MATIC",
            "logoURI": "https://assets.stakek.it/tokens/matic.svg",
            "network": "ethereum",
            "isPoints": false,
            "coinGeckoId": "matic-network"
        }
    ],
    "token": {
        "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
        "decimals": 18,
        "name": "Polygon Ecosystem Token",
        "symbol": "POL",
        "logoURI": "https://assets.stakek.it/tokens/pol.svg",
        "network": "ethereum",
        "isPoints": false,
        "coinGeckoId": "polygon-ecosystem-token"
    },
    "rewardRate": {
        "total": 0.03957252184265532,
        "rateType": "APR",
        "components": [
            {
                "rate": 0.03957252184265532,
                "rateType": "APR",
                "token": {
                    "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                    "decimals": 18,
                    "name": "Polygon Ecosystem Token",
                    "symbol": "POL",
                    "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                    "network": "ethereum",
                    "isPoints": false,
                    "coinGeckoId": "polygon-ecosystem-token"
                },
                "yieldSource": "staking",
                "description": "Earn staking rewards by participating in ethereum consensus with POL"
            }
        ]
    },
    "status": {
        "enter": true,
        "exit": true
    },
    "metadata": {
        "name": "Native Staking",
        "description": "Stake your MATIC natively",
        "documentation": "https://docs.stakek.it/docs/ethereum-matic-native-staking",
        "logoURI": "https://assets.stakek.it/tokens/matic.svg"
    },
    "mechanics": {
        "type": "staking",
        "rewardSchedule": "day",
        "rewardClaiming": "manual",
        "gasFeeToken": {
            "decimals": 18,
            "name": "Ethereum",
            "symbol": "ETH",
            "logoURI": "https://assets.stakek.it/tokens/eth.svg",
            "network": "ethereum",
            "isPoints": false,
            "coinGeckoId": "ethereum"
        },
        "requiresValidatorSelection": true,
        "supportsLedgerWalletApi": true,
        "cooldownPeriod": {
            "seconds": 172800
        },
        "arguments": {
            "enter": {
                "fields": [
                    {
                        "name": "amount",
                        "type": "string",
                        "label": "Amount",
                        "required": true,
                        "description": "Amount for the transaction",
                        "minimum": "1"
                    },
                    {
                        "name": "validatorAddress",
                        "type": "address",
                        "label": "Validator Address",
                        "required": true,
                        "description": "The validator address to interact with",
                        "optionsRef": "v1/yields/ethereum-matic-native-staking/validators"
                    },
                    {
                        "name": "inputToken",
                        "type": "enum",
                        "label": "Token",
                        "required": false,
                        "description": "Which token to use for this operation",
                        "options": [
                            "POL",
                            "MATIC"
                        ]
                    }
                ]
            },
            "exit": {
                "fields": [
                    {
                        "name": "amount",
                        "type": "string",
                        "label": "Amount",
                        "required": true,
                        "description": "Amount for the transaction",
                        "minimum": "1"
                    },
                    {
                        "name": "validatorAddress",
                        "type": "address",
                        "label": "Validator Address",
                        "required": true,
                        "description": "The validator address to interact with",
                        "optionsRef": "v1/yields/ethereum-matic-native-staking/validators"
                    }
                ]
            }
        },
        "entryLimits": {
            "minimum": "1",
            "maximum": null
        }
    },
    "providerId": "",
    "tags": [
        "ethereum",
        "POL",
        "MATIC",
        "staking",
        "manual-rewards",
        "multi-validator",
        "cooldown",
        "ledger-support"
    ]
}

Key differences

  • Schema-driven arguments – v2 introduces structured mechanics.arguments for enter, exit, and manage actions, using a formal fields[] array instead of deeply nested args objects. This enables dynamic forms, validation, and introspection.
  • Top-level token definitions – v2 exposes inputTokens and token at the root of each yield, separating them from the argument schema and making discovery and filtering much easier.
  • Normalized reward rate format – rewardRate in v2 includes a detailed breakdown via components[], with explicit rateType, yieldSource, and token metadata for full transparency.
  • Separated metadata and mechanics – v2 cleanly separates UI-facing display data (metadata) from execution logic (mechanics), improving clarity and integration maintainability.
  • Option references for validators and enums – Instead of embedding token or validator objects in the schema, v2 uses optionsRef to point to relevant endpoints, enabling lightweight, reference-based UI rendering.

YieldBalanceDto

API 1.0 (example)

[
    {
        "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5",
        "type": "staked",
        "amount": "4.000000000000000000",
        "pricePerShare": "1.00308",
        "pendingActions": [],
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "validatorAddress": "0x35B1CA0F398905Cf752e6FE122b51c88022FCa32"
    },
    {
        "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5",
        "type": "rewards",
        "amount": "0.012320444949004356",
        "pricePerShare": "1.00308",
        "pendingActions": [],
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "validatorAddress": "0x35B1CA0F398905Cf752e6FE122b51c88022FCa32"
    },
]

API 2.0 (example)

{
    "yieldId": "ethereum-matic-native-staking",
    "balances": [
        {
            "address": "0x6877BB79f680216BbdF01704939037F22193e771",
            "amount": "4.012320000000000000",
            "amountRaw": "4012320000000000000",
            "type": "active",
            "token": {
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "decimals": 18,
                "name": "Polygon Ecosystem Token",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "network": "ethereum",
                "isPoints": false,
                "coinGeckoId": "polygon-ecosystem-token"
            },
            "pendingActions": [],
            "amountUsd": "0.753225",
            "isEarning": true,
	          "validator": {
                "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951",
                "preferred": true,
                "name": "Luganodes",
                "logoURI": "https://assets.stakek.it/validators/luganodes.png",
                "website": "https://luganodes.com/",
                "commission": 0.1,
                "votingPower": 0.0007025174416982057,
                "status": "active",
                "providerId": "9ef6235e-b039-4619-8307-c675d374ef8c",
                "tvl": "261849883",
                "rewardRate": {
                    "total": 0.034445959222433965,
                    "rateType": "APR",
                    "components": []
                }
            }
        },
        {
            "address": "0x6877BB79f680216BbdF01704939037F22193e771",
            "amount": "0.012358391919447289",
            "amountRaw": "12358391919447289",
            "type": "claimable",
            "token": {
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "decimals": 18,
                "name": "Polygon Ecosystem Token",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "network": "ethereum",
                "isPoints": false,
                "coinGeckoId": "polygon-ecosystem-token"
            },
            "pendingActions": [],
            "amountUsd": "0.002320",
            "isEarning": false,
            "validator": {
                "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951",
                "preferred": true,
                "name": "Luganodes",
                "logoURI": "https://assets.stakek.it/validators/luganodes.png",
                "website": "https://luganodes.com/",
                "commission": 0.1,
                "votingPower": 0.0007025174416982057,
                "status": "active",
                "providerId": "9ef6235e-b039-4619-8307-c675d374ef8c",
                "tvl": "261849883",
                "rewardRate": {
                    "total": 0.034445959222433965,
                    "rateType": "APR",
                    "components": []
                }
            }
        },
    }
    ]
}

Key differences

  • Unified Lifecycle States – v2 replaces loosely defined balance type values like "staked", "unstaked", and "rewards" with a consistent set of lifecycle states: active, claimable, withdrawable, entering, exiting, and locked. This provides clearer modeling across all yield types.
  • Flattened Balance Structure – v2 eliminates grouped balances (e.g., by groupId) in favor of a flat list of discrete positions, each with its own type, validator, and token context — simplifying frontend rendering and logic.
  • Simplified Amount Handling – v2 removes pricePerShare and standardizes on amount, amountRaw, and amountUsd. All values are quoted in the underlying token for simplicity, making balances easier to display without additional calculations or conversions.
  • Embedded Validator Metadata – v2 includes full validator metadata directly on each balance (e.g., name, status, commission, reward rate), reducing the need for additional joins or lookups when displaying validator-specific data.
  • Executable Pending Actions – v2 pending actions now follow the same structure as /v1/actions/manage with intent, type, passthrough, and optional arguments. All pending actions are immediately actionable and schema-driven.

ActionDto (enter-stake flow)

API 1.0 Request

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

API 1.0 Response

{
    "id": "65be9010-2a52-41d6-9389-9594e2a0e1fd",
    "integrationId": "tron-trx-native-staking",
    "status": "CREATED",
    "type": "STAKE",
    "currentStepIndex": 0,
    "amount": "1",
    "USDAmount": "0.285219",
    "tokenId": "tron-undefined",
    "validatorAddress": null,
    "validatorAddresses": [
        "TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"
    ],
    "transactions": [
        {
            "id": "a89db9a6-d0e8-4d43-addd-c00c800c5a3d",
            "network": "tron",
            "status": "CREATED",
            "type": "FREEZE_ENERGY",
            "hash": null,
            "createdAt": "2025-07-03T20:32:20.254Z",
            "broadcastedAt": null,
            "signedTransaction": null,
            "unsignedTransaction": null,
            "structuredTransaction": null,
            "annotatedTransaction": null,
            "stepIndex": 0,
            "error": null,
            "gasEstimate": null,
            "explorerUrl": null,
            "ledgerHwAppId": null,
            "isMessage": false
        },
        {
            "id": "d9eae7f9-ca01-4b66-9e18-cc14f61d9a3a",
            "network": "tron",
            "status": "CREATED",
            "type": "VOTE",
            "hash": null,
            "createdAt": "2025-07-03T20:32:20.254Z",
            "broadcastedAt": null,
            "signedTransaction": null,
            "unsignedTransaction": null,
            "structuredTransaction": null,
            "annotatedTransaction": null,
            "stepIndex": 1,
            "error": null,
            "gasEstimate": null,
            "explorerUrl": null,
            "ledgerHwAppId": null,
            "isMessage": false
        }
    ],
    "createdAt": "2025-07-03T20:32:20.254Z",
    "completedAt": null,
    "inputToken": {
        "name": "Tron",
        "symbol": "TRX",
        "network": "tron",
        "decimals": 6,
        "coinGeckoId": "tron",
        "logoURI": "https://assets.stakek.it/tokens/trx.svg"
    },
    "addresses": {
        "address": "TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx"
    },
    "projectId": "480c9173-613c-4c15-80ba-1f5a9a46a389"
}

(In v1, developers were required to call patch /transaction per transaction step to get the unsignedTransaction ”)

API 2.0 Request (Schema driven)

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

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",
            "network": "tron",
            "status": "CREATED",
            "type": "FREEZE_ENERGY",
            "hash": null,
            "createdAt": "2025-07-03T20:37:51.066Z",
            "broadcastedAt": null,
            "signedTransaction": null,
            "unsignedTransaction": "{\"txID\":\"30d961cf6921e0fd9675f935bd1b946931180128c07cbf0fc6863b2b0588755e\",\"raw_data\":{\"contract\":[{\"parameter\":{\"value\":{\"resource\":\"ENERGY\",\"frozen_balance\":1000000,\"owner_address\":\"415e345c087a39d4d59339131e74f884d1e7420a2f\"},\"type_url\":\"type.googleapis.com/protocol.FreezeBalanceV2Contract\"},\"type\":\"FreezeBalanceV2Contract\"}],\"ref_block_bytes\":\"a45a\",\"ref_block_hash\":\"a6cd284cd7540a32\",\"expiration\":1751575428000,\"timestamp\":1751575068000},\"raw_data_hex\":\"0a02a45a2208a6cd284cd7540a3240a0f79f90fd325a59083612550a34747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e467265657a6542616c616e63655632436f6e7472616374121d0a15415e345c087a39d4d59339131e74f884d1e7420a2f10c0843d180170e0fa8990fd32\",\"visible\":false}",
            "stepIndex": 0,
            "gasEstimate": "{\"amount\":\"0.000251\",\"token\":{\"name\":\"Tron\",\"symbol\":\"TRX\",\"network\":\"tron\",\"decimals\":6,\"coinGeckoId\":\"tron\",\"logoURI\":\"https://assets.stakek.it/tokens/trx.svg\"}}",
            "structuredTransaction": {
                "owner_address": "415e345c087a39d4d59339131e74f884d1e7420a2f",
                "type": "Freeze Energy",
                "frozen_balance": 1000000,
                "resource": "ENERGY"
            },
            "annotatedTransaction": {
                "fields": [
                    {
                        "key": "transaction_type",
                        "value": "FREEZE_ENERGY",
                        "label": "Transaction Type",
                        "description": "Freeze Energy"
                    },
                    {
                        "key": "owner_address",
                        "value": "415e345c087a39d4d59339131e74f884d1e7420a2f",
                        "label": "Owner Address",
                        "description": "Address that owns the transaction"
                    },
                    {
                        "key": "frozen_balance",
                        "value": "1000000",
                        "label": "Frozen Balance",
                        "description": "Amount of TRX frozen in SUN (1 TRX = 1,000,000 SUN)"
                    },
                    {
                        "key": "resource",
                        "value": "ENERGY",
                        "label": "Resource Type",
                        "description": "Type of resource (BANDWIDTH or ENERGY)"
                    }
                ]
            }
        },
        {
            "id": "ab2e16c8-8845-4b8d-8799-fc39078211c1",
            "title": "VOTE Transaction",
            "network": "tron",
            "status": "CREATED",
            "type": "VOTE",
            "hash": null,
            "createdAt": "2025-07-03T20:37:51.066Z",
            "broadcastedAt": null,
            "signedTransaction": null,
            "unsignedTransaction": "{\"txID\":\"cb7de68c95721548b9a1eccd10bb9322d61cd2df1b6a02a148aa93961437d673\",\"raw_data\":{\"contract\":[{\"parameter\":{\"value\":{\"owner_address\":\"415e345c087a39d4d59339131e74f884d1e7420a2f\",\"votes\":[{\"vote_address\":\"414ce8225c8ea6c8e1e0a483132211610c765fc6df\",\"vote_count\":5}]},\"type_url\":\"type.googleapis.com/protocol.VoteWitnessContract\"},\"type\":\"VoteWitnessContract\"}],\"ref_block_bytes\":\"a45a\",\"ref_block_hash\":\"a6cd284cd7540a32\",\"expiration\":1751575428000,\"timestamp\":1751575068000},\"raw_data_hex\":\"0a02a45a2208a6cd284cd7540a3240a0f79f90fd325a6a080412660a30747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e566f74655769746e657373436f6e747261637412320a15415e345c087a39d4d59339131e74f884d1e7420a2f12190a15414ce8225c8ea6c8e1e0a483132211610c765fc6df100570e0fa8990fd32\",\"visible\":false}",
            "stepIndex": 1,
            "gasEstimate": "{\"amount\":\"0.000268\",\"token\":{\"name\":\"Tron\",\"symbol\":\"TRX\",\"network\":\"tron\",\"decimals\":6,\"coinGeckoId\":\"tron\",\"logoURI\":\"https://assets.stakek.it/tokens/trx.svg\"}}",
            "structuredTransaction": {
                "owner_address": "415e345c087a39d4d59339131e74f884d1e7420a2f",
                "type": "Vote",
                "votes": [
                    {
                        "vote_address": "414ce8225c8ea6c8e1e0a483132211610c765fc6df",
                        "vote_count": 5
                    }
                ]
            },
            "annotatedTransaction": {
                "fields": [
                    {
                        "key": "transaction_type",
                        "value": "VOTE",
                        "label": "Transaction Type",
                        "description": "Vote"
                    },
                    {
                        "key": "owner_address",
                        "value": "415e345c087a39d4d59339131e74f884d1e7420a2f",
                        "label": "Owner Address",
                        "description": "Address that owns the transaction"
                    },
                    {
                        "key": "votes",
                        "value": "[{\"vote_address\":\"414ce8225c8ea6c8e1e0a483132211610c765fc6df\",\"vote_count\":5}]",
                        "label": "Votes",
                        "description": "Distribution of votes among validators"
                    }
                ]
            }
        }
    ],
    "executionPattern": "synchronous",
    "rawArguments": null,
    "createdAt": "2025-07-03T20:37:51.066Z",
    "completedAt": null,
    "status": "CREATED"
}

Key differences

  • Schema-driven requests – v2 replaces nested args with a clean, top-level arguments object that is defined by the yield’s mechanics.arguments.enter schema. This allows for dynamic validation and UI generation based on field definitions.
  • Unified action structure – All actions in v2 (enter, exit, manage) return the same ActionDto format with clear intent, type, yieldId, address, and transactions, regardless of protocol.
  • Structured transactions included by default – v2 embeds unsigendTransaction, structuredTransaction and annotatedTransaction directly in the response. No need to call /construct for each transaction step — everything is returned up front.
  • Gas estimates and step metadata – Each transaction now includes gasEstimate, stepIndex, and user-facing title, making it easier to display transaction flows and costs to users in order.
  • Cleaner response shape, better separation of concerns – v2 removes legacy concepts like projectId, scattered validator fields, and loosely typed type/status, replacing them with consistent data across all chains and flows.

Take-away

API 2.0 delivers richer metadata, formal schemas, lifecycle flags, and fully prepared transactions the moment you hit the endpoint—meaning you write less glue code and ship faster. The release is currently in public beta, and we’re actively smoothing edge-cases and polishing DX in weekly updates. Your feedback during this phase is hugely valuable.

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 any custom transaction-construction logic: No need to construct transactions via our endpoint one by one anymore, simply create the action, and 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 the balance endpoint to capture any passthrough needed for manage actions.

With these adjustments, you can transition smoothly to the more streamlined, scalable v2 API while keeping legacy integrations online until you’re ready to deprecate them.

Developer Update Checklist

  1. Rename & map fields – switch to yieldId, metadata.*, rewardRate.*, lifecycle type.
  2. Generate UI from schema – read yield.mechanics.arguments to create forms; note "validatorAddress"(string) vs "validatorAddresses" (array) per schema.
  3. **Fetch validators via /**validators – no inline arrays.
  4. Use balance lifecycle – drive labels/buttons from balance.type and pendingActions.
  5. Simplify actions – one create-action call → sign each TransactionDto → PUT /hash; no construct-tx calls needed.

Adopting these v2 structures removes edge cases and future-proofs your integration for every new yield opportunity.

Updated 9 days ago