# Yield Xyz Agentkit

> Discover and act on 2,900+ DeFi yield opportunities via Yield.xyz AgentKit Skills, find yields, check APY enter/exit positions, and manage rewards across 80+ networks.

- **Type:** Skill
- **Install:** `agentstack add skill-stakekit-agentkit-yield-xyz-agentkit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [stakekit](https://agentstack.voostack.com/s/stakekit)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [stakekit](https://github.com/stakekit)
- **Source:** https://github.com/stakekit/agentkit/tree/main/plugins/yield-xyz-agentkit/skills/yield-xyz-agentkit
- **Website:** https://docs.yield.xyz/docs/agents-overview

## Install

```sh
agentstack add skill-stakekit-agentkit-yield-xyz-agentkit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Yield.xyz AgentKit

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

---

## Integration Boundary

This skill is the **yield layer** — it discovers yields, inspects their schemas, and builds **unsigned** transactions. It **never holds keys, signs, or broadcasts**, and it's tied to no wallet or custody product. Drop it into any agent or app that can already sign, and it becomes that agent's expertise for earning yield.

Responsibility splits cleanly on every transaction:

1. **This skill** builds the `unsignedTransaction` (`actions_enter` / `actions_exit` / `actions_manage`).
2. **Your side signs and broadcasts it.** Whatever does that is your *signer* — a user's wallet, your agent's own custody (MPC / KMS / HSM), or a provider like Privy or MoonPay. This skill doesn't care which.
3. **This skill** records the result — `submit_hash` with the returned hash, then `get_transaction` until `CONFIRMED`.

This holds whether signing is human-approved or fully autonomous. Where a human is in the loop, confirm before signing; where the host signs on its own, skip the confirmation and let it run.

---

## 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
- **yields_get_kyc_status** — check a wallet's KYC/eligibility status for a permissioned (RWA) 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 → top up the wallet (or have the user add funds), call again
- Anything looks off → STOP, do not proceed

Modifying `unsignedTransaction` **will result in permanent loss of funds.**

---

## Output Formatting

For all display rules, number formatting, badges, tables, and action summaries, see **[`references/output-formats.md`](./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 **[`references/policies.md`](./references/policies.md)** for API usage, data fetching, and efficiency.

---

## Access Modes & Free Tier

The MCP works in two modes: **anonymous** (free tier, 30 calls per wallet per tool per 24h on four metered tools) and **BYO API key** (unlimited). See **[`references/x402-payments.md`](./references/x402-payments.md)** for which tools are gated, how to react to a `Free-tier quota exceeded` error, and when to guide the user toward an API key or the pay-per-call x402 surface.

**On any `Free-tier quota exceeded` error:** surface it to the user verbatim (the message includes the retry seconds and offending wallet) and offer the three options in `x402-payments.md`. Do NOT silently retry.

---

## 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 to yields whose **accepted deposit token** is in this list — symbols or contract addresses, e.g. `["USDC"]`. This is how you scope discovery to a wallet's holdings. A symbol like `USDC` can over-match contract variants (native vs bridged); pass the contract address when you need an exact token.
- `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 has: `id`, `tokenSymbol`, `network`, `type`, `providerId`, `rewardRate` (number, the APY/APR), `tvlUsd`, `status` `{ enter, exit }`, `cooldownPeriod`, `warmupPeriod`, `lockupPeriod`, `minEntry`, `maxEntry`, `kycRequired`, `authorizeUrl`. Use `yields_get` for full per-yield detail (fees, validators, full reward breakdown).

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

**Discovery — fetch *relevant* yields.** When a wallet is in context, scope discovery to what it can deposit: pass the wallet's held tokens as `inputTokens` (and their chains as `networks`) so you return only yields that **accept a token the wallet holds**, instead of the whole catalog. (Token match isn't a guarantee of entry — that still depends on holding enough vs `minEntry`, the yield's `status.enter`, and any gating like RWA KYC.) The base has no wallet — get holdings from the host's signer/wallet (e.g. a connector's balance read). With no wallet in context, discover by the user's stated `token` / `networks` instead.

---

### 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 "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 unilaterally — confirm with the user, or follow the host's configured selection criteria.

---

### 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` and `balances: BalanceDto[]`. **`pendingActions[]` lives on each `BalanceDto`** (path: `items[].balances[].pendingActions[]`), not on `YieldBalancesDto`. Each pending action has `intent`, `type`, `passthrough`, optional `arguments`, and optional `amount`. To act on one, pass `pendingActions[].type` as the `action` parameter and `pendingActions[].passthrough` as `passthrough` to `actions_manage`.

**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)
- `validatorAddress` — optional; required when `mechanics.requiresValidatorSelection`
- `receiverAddress`, `useMaxAllowance` — optional
- Any other per-yield enter fields come from `mechanics.arguments.enter` — pass them as top-level params (there is no `args` wrapper), and never invent an `inputToken` param

**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`
- `validatorAddress`, `receiverAddress`, `useMaxAmount`, `useAutoClaim` — optional
- `useInstantExecution` — optional; only when the yield offers it (e.g. some RWA redemptions). `true` → instant settlement, usually for a fee; `false` → standard NAV redemption, funds settle in ~1–7 business days. Ask the user which they want; never default it silently.
- Does **not** take `passthrough` (that's `actions_manage` only).

**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 signer has signed and broadcast 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:** The signer has signed and broadcast 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`: one of `NOT_FOUND` | `CREATED` | `BLOCKED` | `WAITING_FOR_SIGNATURE` | `SIGNED` | `BROADCASTED` | `PENDING` | `CONFIRMED` | `FAILED` | `SKIPPED`. Terminal states are `CONFIRMED`, `FAILED`, and `SKIPPED`.

**Use when:** After calling `submit_hash`, poll until status is terminal (`CONFIRMED`, `FAILED`, or `SKIPPED`) before proceeding. On `CONFIRMED` continue; on `FAILED` stop the sequence and report (don't sign later steps); `SKIPPED` means that step needs no on-chain tx — proceed to the next.

---

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

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [stakekit](https://github.com/stakekit)
- **Source:** [stakekit/agentkit](https://github.com/stakekit/agentkit)
- **License:** MIT
- **Homepage:** https://docs.yield.xyz/docs/agents-overview

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-stakekit-agentkit-yield-xyz-agentkit
- Seller: https://agentstack.voostack.com/s/stakekit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.