Yield.xyz AgentKit

A skill for discovering and acting on DeFi yield opportunities via the Yield.xyz MCP server.

⚠️ How to Call Tools — Read This First

Always call tools via the connected MCP server (https://mcp.yield.xyz/mcp). Never fall back to curl, bash, or raw HTTP requests.

The MCP server exposes these tools directly — call them like any other tool:

• yields_get_all — list/filter yields
• yields_get — get one yield by ID
• yields_get_validators — list validators for a yield
• yields_get_balances — check wallet balances
• yields_get_reward_rate_history — historical APY/reward rate data for a yield
• yields_get_tvl_history — historical TVL data for a yield
• yields_get_risk — detailed risk parameters for a yield
• actions_enter — enter a position
• actions_exit — exit a position
• actions_manage — claim rewards / manage position
• actions_get — get status of a specific action
• actions_get_all — list action history for a wallet
• submit_hash — submit on-chain tx hash after signing and broadcasting (mandatory)
• get_transaction — poll transaction confirmation status
• networks_get_all — list all supported networks
• providers_get_all — list all supported protocols and providers

---

⚠️ CRITICAL: Never Modify Transactions

DO NOT modify unsignedTransaction returned by any action tool under any circumstances. Not addresses, amounts, fees, encoding — nothing.

• Amount wrong → call the action tool again with corrected amount
• Gas insufficient → ask user to add funds, call again
• Anything looks off → STOP, do not proceed

Modifying unsignedTransaction will result in permanent loss of funds.

---

Available Tools

1. yields_get_all

List and filter yield opportunities across networks and tokens.

Key parameters:

• networks — array of network slugs e.g. ["base"], ["ethereum", "arbitrum"]. For unified search pass all in one array. For fair cross-network comparison ("ethereum vs arbitrum", "which network is better") run one call per network in parallel — see Intelligence Notes. Use networks_get_all to resolve a network name if unsure.
• token — token symbol e.g. "USDC", "ETH", "WBTC" or a contract address.
• types — array of yield types. Valid values: staking, restaking, lending, vault, fixed_yield, real_world_asset, concentrated_liquidity_pool, liquidity_pool. These are the only valid types. Map user requests to nearest match (e.g. "liquid staking" → staking, "earn" → vault, "LP" → liquidity_pool) or confirm before calling.
• sort — server-side sort order. Always pass rewardRateDesc by default — do not re-sort client-side. Switch to rewardRateAsc, statusEnterDesc, statusEnterAsc, statusExitDesc, or statusExitAsc per user request.
• search — free-text search across yield names, token names, provider names, and descriptions.
• yieldIds — batch fetch up to 100 specific yields by ID.
• inputTokens — filter by accepted deposit token symbols or addresses e.g. ["USDC"].
• providers — filter by provider IDs e.g. ["lido", "aave"]. Use providers_get_all to get valid IDs.
• hasCooldownPeriod — true to show only yields with a cooldown, false to exclude them.
• hasWarmupPeriod — true to show only yields with a warmup period.
• limit / offset — pagination (default 20, max 50)

Returns: { total, offset, limit, items[] } — each item includes: id, tokenSymbol, network, type, providerId, rewardRate, tvlUsd, status, cooldownPeriod, warmupPeriod, lockupPeriod, minEntry, maxEntry

Use when: User wants to browse or compare yield options.

---

2. yields_get

Fetch full details for a single yield opportunity by its ID.

Key parameters:

• yieldId — the id field from yields_get_all results

Returns: Full YieldDto including state, mechanics, risk, statistics.

Use when: User wants deep detail on a specific yield (fees, lockup, validators, etc.).

---

3. yields_get_validators

List validators for a yield that requires validator selection.

Key parameters:

• yieldId
• limit / offset — pagination (default 20, max 50)
• preferred — pass true to return only curated/recommended validators.
• name — filter by validator name (partial match).
• status — filter by status e.g. "active", "jailed".
• address — filter by exact validator address.
• provider — filter by provider ID.

Returns: { total, offset, limit, items: ValidatorDto[] }

Use when: mechanics.requiresValidatorSelection === true, or user asks to pick a validator.

Display & selection rules:

• Always call this before entering a staking position — never hardcode or guess a validator address.
• Default to limit: 20 unless the user asks to see more.
• Display as a table sorted by: preferred validators first, then APR descending within each group.
• Columns to show: Validator, Commission, APR, TVL, Voting Power.
• Flag validators with preferred: true with a ✓ or "Curated" label.
• Warn if a validator has 0% commission — note it may be a temporary rate.
• If the user doesn't specify a validator, recommend the top preferred validator by APR and explain why.
• Never pick a validator autonomously without confirming with the user first.

---

4. yields_get_balances

Fetch the user's balances across one or more yield positions.

Key parameters:

• address — single wallet address (string)
• network — required, e.g. "base", "ethereum"
• yieldIds — optional array of yield IDs to filter

Returns: { items: YieldBalancesDto[], errors: [{ yieldId, error }] }

Each YieldBalancesDto has yieldId, balances: BalanceDto[], and optional outputTokenBalance.

Use when: User asks "what are my positions?", "how much am I earning?", or "show my balances".

---

5. actions_enter

Initiate entering (depositing into) a yield position.

Key parameters:

• yieldId
• address — user's wallet address
• amount — human-readable (e.g. "100", never raw wei)
• args — optional extras like validatorAddress, inputToken

Returns: ActionDto with transactions: TransactionDto[]

Use when: User wants to stake, deposit, or enter a position.

---

6. actions_exit

Initiate exiting (withdrawing from) a yield position.

Key parameters:

• yieldId, address, amount
• passthrough — from pendingActions[].passthrough if available
• validatorAddress — optional

Returns: ActionDto

Use when: User wants to unstake, withdraw, or exit. Always check cooldown/lockup first.

---

7. actions_manage

Perform a management action on an existing position (claim rewards, restake, change validator).

Key parameters:

• yieldId
• address — user's wallet address
• action — required, action type from pendingActions[].type (e.g. "CLAIM_REWARDS")
• passthrough — required, from pendingActions[].passthrough in balances response
• amount — optional, human-readable amount for partial claims e.g. "10.5". Omit to claim the full available amount.

Returns: ActionDto

Use when: User has pending actions on a balance, or wants to claim rewards.

---

8. submit_hash

Submit the on-chain transaction hash after the user has signed and broadcasted a transaction.

This is mandatory after every transaction. Never skip this step.

Key parameters:

• transactionId — the transaction UUID from the transactions[] array in the ActionDto
• hash — the on-chain hash returned after broadcasting e.g. "0x1234…abcdef"

Returns: Updated TransactionDto

Use when: User has signed and broadcasted any transaction from an enter, exit, or manage action.

---

9. get_transaction

Poll the status of a transaction by its ID.

Key parameters:

• transactionId — the transaction UUID from the transactions[] array

Returns: TransactionDto with status: CREATED | BROADCASTED | CONFIRMED | FAILED

Use when: After calling submit_hash, poll until status is CONFIRMED or FAILED before proceeding to the next transaction in a multi-step action.

---

10. actions_get

Get the current status and transactions of a specific action.

Key parameters:

• actionId — the action UUID returned by actions_enter, actions_exit, or actions_manage

Returns: Full ActionDto with current status and all transactions.

Use when: Checking whether an action has completed, or tracking an async execution pattern where approval may take time.

---

11. actions_get_all

List past and pending actions for a wallet address.

Key parameters:

• address — wallet address to query
• statuses — filter by one or more statuses: "CREATED", "PROCESSING", "WAITING_FOR_NEXT", "SUCCESS", "FAILED", "CANCELED", "STALE"
• intent — filter by "enter", "exit", or "manage"
• type — filter by action type e.g. "STAKE", "UNSTAKE", "CLAIM_REWARDS"
• yieldId — filter by yield ID
• network — filter by network
• limit / offset — pagination (default 20, max 100)

Returns: Paginated list of ActionDto

Use when: User asks "show my pending actions", "what did I do recently?", or to find actions waiting for a next step.

---

12. networks_get_all

List all networks supported by Yield.xyz.

Key parameters:

• search — filter by name or ID (min 2 chars) e.g. "eth", "bnb", "base"
• category — filter by "evm", "cosmos", "substrate", or "misc"

Returns: Array of { id, name, category, logoURI }

Use when: Resolving a network name the user mentioned (e.g. user says "Binance Smart Chain" → search "bnb" to get the correct slug), or when listing supported chains.

---

13. providers_get_all

List all supported protocols and validator providers (e.g. Lido, Aave, Morpho).

Key parameters:

• limit / offset — pagination (default 20, max 100)

Returns: Paginated list with id, name, description, website, tvlUsd, type

Use when: User asks what protocols Yield.xyz supports, or to get valid provider IDs for yields_get_all filters.

---

14. yields_get_reward_rate_history

Get historical APY/reward rate snapshots for a yield over time.

Key parameters:

• yieldId
• period — predefined window: "1d", "7d", "30d", "90d", "1y", "all". Default: "30d". Ignored if from/to are set.
• from / to — ISO 8601 date range e.g. "2025-01-01T00:00:00Z". Overrides period.
• interval — sampling resolution: "day", "week", "month". Default: "day".
• limit / offset — pagination (default 30, max 365)

Returns: { yieldId, interval, from, to, items: [{ timestamp, rewardRate }], total }

Important: If items is empty (total: 0), historical reward rate data is not available for this yield. This is expected for many yields — it is not an error.

Use when: User asks "has this APY been stable?", "what was the yield last month?", or wants to see APY trends.

---

15. yields_get_tvl_history

Get historical Total Value Locked snapshots for a yield.

Key parameters:

• yieldId
• period — predefined window: "1d", "7d", "30d", "90d", "1y", "all". Default: "30d". Ignored if from/to are set.
• from / to — ISO 8601 date range. Overrides period.
• interval — "day", "week", "month". Default: "day".
• limit / offset — pagination (default 30, max 365)

Returns: { yieldId, interval, from, to, items: [{ timestamp, tvlUsd }], total }

Important: If items is empty (total: 0), TVL history is not available for this yield. This is expected for many yields — it is not an error.

Use when: User asks about protocol health, TVL growth/decline, or wants to assess liquidity trends.

---

16. yields_get_risk

Get detailed risk parameters for a yield — more granular than the risk field in yields_get.

Key parameters:

• yieldId

Returns: { updatedAt, exponentialFi: { poolRating, poolScore, ratingDescription, url }, credora: { rating, score, ... } }

Important: If the response contains only updatedAt with no exponentialFi or credora fields, detailed risk data is not available for this yield. This is expected for many yields — it is not an error. Fall back to the risk field in yields_get if present.

Use when: User asks about protocol safety, risk rating, or audit status for a specific yield.

---

Key Data Shapes

YieldDto — a yield opportunity

Field	Description
id	Unique yield ID — required for all other calls
network	Chain name (e.g. "base")
token	Primary input token
rewardRate	{ total, rateType, components[] } — APY/APR
status	{ enter: boolean, exit: boolean }
mechanics	Lockup, cooldown, fees, validator requirement, entry limits
statistics	TVL, unique users
risk	Exponential.fi / Credora ratings
metadata	Name, logo, description, documentation URL

TransactionDto — a transaction to execute

Field	Description
unsignedTransaction	Raw tx data — never modify
isMessage	If true, sign as message not tx
gasEstimate	Estimated gas
explorerUrl	Block explorer link

---

Output Formatting

For all display rules, number formatting, badges, tables, and action summaries, see references/output-formats.md.

Never dump raw JSON or plain comma-separated data. Always follow the formats defined there.

MANDATORY: Before displaying any results, read references/output-formats.md using the Read tool. Do not skip this step.

---

⚠️ API Usage Policy

You must follow the guidelines defined in policies.md for API usage, data fetching, and efficiency.

---

Recommended Workflows

Find and enter a yield

1. yields_get_all — networks + token, sort: "rewardRateDesc", limit: 20
2. Present top 10 in formatted list
3. User picks one → yields_get on that ID — show reward breakdown + mechanics
4. If requiresValidatorSelection, call yields_get_validators, present top 10
5. Run safety checklist, get user confirmation
6. actions_enter → present structured transaction summary
7. User signs and broadcasts each transaction → call submit_hash with the tx hash (mandatory)
8. Poll get_transaction until CONFIRMED before proceeding to the next transaction

Check balances and claim rewards

1. yields_get_balances with wallet address + yield IDs
2. Show portfolio summary, each position sorted by value
3. Highlight pendingActions with claimable amounts
4. User wants to claim → actions_manage with passthrough from pending action
5. Present transaction summary
6. User signs and broadcasts → call submit_hash (mandatory)
7. Poll get_transaction until CONFIRMED

Exit a position

1. yields_get → confirm status.exit === true
2. Surface cooldown/lockup from safety checklist
3. Get user confirmation
4. actions_exit → return structured transaction summary
5. User signs and broadcasts → call submit_hash (mandatory)
6. Poll get_transaction until CONFIRMED

Compare yields

1. yields_get_all with token filter, sort: "rewardRateDesc", limit: 20
2. Top 10 ranked table
3. Note any high-APY entries that appear incentivised (check rewardRate.components)
4. Offer to drill into any specific one

Check APY/TVL trends for a yield

1. yields_get_reward_rate_history — period: "30d", interval: "day"
2. yields_get_tvl_history — period: "30d", interval: "day"
3. If either returns empty items, note that historical data is not available for this yield
4. Present as a trend summary (see output-formats.md)

Assess risk for a yield

1. yields_get_risk — get detailed risk data
2. If response has no exponentialFi or credora fields, fall back to risk field from yields_get
3. Present ratings and scores clearly (see output-formats.md)

Resolve an unknown network name

1. networks_get_all with search set to the user's network name e.g. "bnb", "binance"
2. Use the returned id slug in subsequent calls

---

Intelligence Notes

• High APY (>20%): Check rewardRate.components — if driven by incentives, flag as potentially short-lived.
• Low TVL (<$100k): Flag as low liquidity — may indicate higher risk or new/unaudited protocol.
• Risk ratings: If risk data is present, always show it — never hide from users.
• Multi-network intent detection: Detect whether the user wants a unified search or a fair comparison. Keywords like "compare", "vs", "which network is better", "ethereum vs arbitrum" → parallel calls (one per network, limit: 20 each) so every network gets fair representation. Keywords like "show me yields on ethereum and arbitrum", "find yields across chains" → single call (networks: [...], limit: 50). The API sorts globally — without parallel calls for comparisons, a high-APY network will crowd out all others from the results.
• Async execution pattern: Remind user upfront that a second step may be needed later.
• Amount near limits: If user's amount is close to entryLimits.minimum or maximum, note it proactively.
• submit_hash is mandatory: Always call after every broadcast. Never skip — without it, the platform cannot track the transaction.
• Empty history/risk data: If yields_get_reward_rate_history or yields_get_tvl_history returns items: [], or yields_get_risk returns only updatedAt, this means data is not available for that yield — it is not an error. Tell the user data is unavailable rather than showing an empty result.
• Network resolution: If a user mentions a chain name that doesn't match a known slug (e.g. "Binance Smart Chain", "BNB Chain"), call networks_get_all with a search term before calling any other tool.
• Declining TVL: If yields_get_tvl_history shows a consistent downward trend, flag it as a potential risk signal.