From bc7bce7083af81cba876e3101c29fa5324f10f84 Mon Sep 17 00:00:00 2001 From: Ishita Agarwal Date: Mon, 20 Apr 2026 14:17:07 +0530 Subject: [PATCH 1/3] feat: add new tools and sync mcp changes --- yield-agentkit-plugin/yield-agentkit/SKILL.md | 206 ++++++++++++++- .../references/output-formats.md | 127 ++++++++- .../skills/yield-agentkit-moonpay/SKILL.md | 24 +- .../references/input-format.md | 142 +++++++++- .../references/output-formats.md | 129 ++++++++- .../skills/yield-agentkit-privy/SKILL.md | 26 +- .../references/privy-transactions.md | 8 +- .../references/privy-wallets.md | 13 + .../references/semi-autonomous.md | 10 +- .../references/yield-input-format.md | 157 ++++++++++- .../references/yield-mcp-tools.md | 244 ------------------ .../references/yield-output-format.md | 127 ++++++++- .../skills/yield-agentkit/SKILL.md | 209 +++++++++++++-- .../references/output-formats.md | 127 ++++++++- 14 files changed, 1209 insertions(+), 340 deletions(-) delete mode 100644 yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-mcp-tools.md diff --git a/yield-agentkit-plugin/yield-agentkit/SKILL.md b/yield-agentkit-plugin/yield-agentkit/SKILL.md index 8707172..27c926b 100644 --- a/yield-agentkit-plugin/yield-agentkit/SKILL.md +++ b/yield-agentkit-plugin/yield-agentkit/SKILL.md @@ -20,9 +20,18 @@ The MCP server exposes these tools directly — call them like any other tool: - `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 --- @@ -45,13 +54,19 @@ Modifying `unsignedTransaction` **will result in permanent loss of funds.** List and filter yield opportunities across networks and tokens. **Key parameters:** -- `network` — e.g. `"base"`, `"ethereum"`, `"arbitrum"` -- `token` — e.g. `"USDC"`, `"ETH"`, `"WBTC"` -- `type` — must be one of: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. These are the **only valid types** — no others exist. If the user asks for a type not in this list, map it to the nearest match (e.g. "liquid staking" → `staking`, "earn" → `vault`, "LP" → `liquidity_pool`) or confirm with the user before calling the tool. -- `limit` / `offset` — pagination (default limit: 20, max: 50) -- `status` — filter by `enter`/`exit` availability - -**Returns:** `{ total, offset, limit, items: YieldDto[] }` +- `networks` — array of network slugs e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls per network — pass all in one array. 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. @@ -74,7 +89,12 @@ List validators for a yield that requires validator selection. **Key parameters:** - `yieldId` -- `limit` / `offset` — pagination +- `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[] }` @@ -145,6 +165,7 @@ Perform a management action on an existing position (claim rewards, restake, cha - `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` @@ -152,6 +173,138 @@ Perform a management action on an existing position (claim rewards, restake, cha --- +### 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 @@ -196,32 +349,53 @@ Never dump raw JSON or plain comma-separated data. Always follow the formats def ## Recommended Workflows ### Find and enter a yield -1. `yields_get_all` — `network` + `token`, `limit: 50` -2. Sort by APY, present top 10 in formatted list +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. Return transaction summary +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, `limit: 50` -2. Sort APY descending, top 10 ranked table +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 @@ -229,6 +403,10 @@ Never dump raw JSON or plain comma-separated data. Always follow the formats def - **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 results:** Group by network for clarity. +- **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. diff --git a/yield-agentkit-plugin/yield-agentkit/references/output-formats.md b/yield-agentkit-plugin/yield-agentkit/references/output-formats.md index fa3d413..b451cdb 100644 --- a/yield-agentkit-plugin/yield-agentkit/references/output-formats.md +++ b/yield-agentkit-plugin/yield-agentkit/references/output-formats.md @@ -26,23 +26,49 @@ All display rules for Yield.xyz Agent tool outputs. Always follow these formats ## yields_get_all — Listing Yields -Default: call with `limit: 20`, sort client-side by `rewardRate.total` descending, show **top 10**. +**Single network:** call with `limit: 20`, `sort: "rewardRateDesc"` — results arrive pre-sorted, show top 10. -Always display as a table, never as individual cards: +**Multiple networks — two intents, two strategies:** + +- **Unified search** ("show me top yields on ethereum and arbitrum", "find me ETH yields across chains") → single call with `networks: [...]`, `limit: 50`, `sort: "rewardRateDesc"`. Group results by network in the table. Acceptable that one network may dominate if its APYs are genuinely higher. + +- **Fair comparison** ("compare yields between ethereum and arbitrum", "which network has better USDC yields", "ethereum vs arbitrum") → run one call per network **in parallel** (same params, each with `limit: 20`). Show a table per network side by side. This guarantees every network gets fair representation regardless of APY distribution. + +Always display as a table, never as individual cards. + +**Single network example:** + +📈 Top ETH Yields on Ethereum +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +Showing top 5 of 24 — ask for more or filter. + +**Multi-network comparison example (parallel calls, one per network):** -📈 Top USDC Yields on Base (76 total) +📈 ETH Yields · Ethereum vs Arbitrum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +**🔵 Ethereum** +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +**🟠 Arbitrum** | # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | |---|----------|-------|-----|-----|------|--------|----------|-----| -| 🥇 | Morpho | coUSDC | 7.02% | $4.93M | vault | None | None | — | -| 🥈 | Morpho | csrUSDC | 6.20% | $322K | vault | None | None | — | -| 🥉 | Euler | eUSDC-29 | 6.04% | $145K | vault | None | None | — | -| #4 | Euler | eUSDC-49 | 5.81% | $567K | vault | None | None | — | -| #5 | Yo Protocol | yoUSD | 5.02% | — | vault | None | None | — | +| 🥇 | Aave | aWETH | 2.85% | $210M | lending | None | None | — | +| 🥈 | Compound | cWETH | 2.40% | $88M | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.10% | $65M | vault | None | None | — | -Showing top 10 of 76 — ask for more or filter by network/token. +Showing top 5 per network — ask for more or filter. Badges go in the Protocol cell when applicable, e.g. `Morpho ⭐`. @@ -150,6 +176,89 @@ Before calling any action tool, check and surface **all that apply**. Never skip --- +## actions_get_all — Displaying Action History + +Always display as a table, never as a list of cards: + +``` +📋 Action History · 0x742d…f44e +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Yield | Type | Amount | Network | Status | Date | +|---|-------|------|--------|---------|--------|------| +| 1 | Lido stETH | STAKE | 1.5 ETH | ethereum | ✅ SUCCESS | Apr 18 | +| 2 | Aave USDC | STAKE | 500 USDC | base | ⏳ PROCESSING | Apr 20 | +| 3 | Cosmos ATOM | CLAIM_REWARDS | — | cosmos | ✅ SUCCESS | Apr 15 | + +Showing 3 of 12 — ask for more or filter by status/network. +``` + +**Status badges:** +- `✅ SUCCESS` — confirmed on-chain +- `⏳ PROCESSING` — in-flight +- `🕐 CREATED` — submitted, not yet on-chain +- `⏸ WAITING_FOR_NEXT` — multi-step, awaiting next tx +- `❌ FAILED` — reverted or errored +- `🚫 CANCELED` — user-cancelled +- `⌛ STALE` — timed out + +--- + +## yields_get_reward_rate_history — APY Trend + +``` +📈 APY History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: 2.51% (Mar 28) + Low: 2.39% (Apr 10) + Current: 2.43% + + Trend: ↘ Slight decline over the period. +``` + +- `rewardRate` values are decimals — format as `(value * 100).toFixed(2) + "%"` +- If `items` is empty: *"Historical APY data is not available for this yield."* + +--- + +## yields_get_tvl_history — TVL Trend + +``` +📊 TVL History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: $32.1B (Mar 21) + Low: $30.4B (Apr 14) + Current: $31.2B + + Trend: → Relatively stable over the period. +``` + +- Format TVL values as `$4.93M` / `$322K` / `$1.2B` — never raw string +- Trend direction: ↗ Growing / ↘ Declining / → Stable (use ±5% as threshold) +- If `items` is empty: *"Historical TVL data is not available for this yield."* +- ⚠️ Flag a consistent downward trend as a potential risk signal + +--- + +## yields_get_risk — Risk Rating + +``` +🛡 Risk Assessment · Lido stETH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Exponential.fi: A (Score: 1) — "A" + 🔗 Full report: https://exponential.fi/pools/… +``` + +- If both `exponentialFi` and `credora` are present, show both +- If only one is present, show it and note the other is unavailable +- If neither is present: *"Detailed risk data is not available for this yield."* +- Always show the `exponentialFi.url` link when present + +--- + ## actions_enter / actions_exit / actions_manage — After an Action is Created **✅ Action Created — {intent}** diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md index 28caefc..a0af7be 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md @@ -25,7 +25,7 @@ This skill requires both MCP servers to be connected: | MCP | Role | Tools used | |---|---|---| -| **Yield.xyz AgentKit** | Yield discovery + transaction building | `yields_get_all`, `yields_get`, `yields_get_validators`, `yields_get_balances`, `actions_enter`, `actions_exit`, `actions_manage` | +| **Yield.xyz AgentKit** | Yield discovery + transaction building | `yields_get_all`, `yields_get`, `yields_get_validators`, `yields_get_balances`, `yields_get_reward_rate_history`, `yields_get_tvl_history`, `yields_get_risk`, `actions_enter`, `actions_exit`, `actions_manage`, `actions_get`, `actions_get_all`, `submit_hash`, `get_transaction`, `networks_get_all`, `providers_get_all` | | **MoonPay** | Auth + wallet + sign + broadcast | `wallet_list`, `transaction_sign`, `transaction_send`, `token_balance_list` and more | If either MCP is missing, stop and tell the user. See @@ -67,10 +67,12 @@ Before anything else: Call `yields_get_all` with the user's preferred network and token. -- Sort results: preferred validators/yields first, then by APY descending -- Show a table: Protocol, Type, APY, Network, Token +- Pass `sort: "rewardRateDesc"` — always use server-side sort, never re-sort client-side +- Pass `networks` as an array e.g. `["base"]` — never make multiple calls per network - Default to `limit: 20` unless user asks for more -- Valid `type` values: `staking`, `restaking`, `lending`, `vault`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool` +- Show a table: Protocol, Type, APY, Network, Token +- Valid `types` values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool` +- If the user's network name doesn't match a known slug, call `networks_get_all` to resolve it first ### Step 3 — Inspect the yield Call `yields_get` with the chosen `yieldId`. Read: @@ -109,6 +111,10 @@ You now have `transactions[]` from Step 5, ordered by `stepIndex`. Execute each transaction **sequentially**, never in parallel, never out of order. Do not begin transaction N+1 until transaction N is `CONFIRMED`. +After MoonPay broadcasts each transaction: +1. Call `submit_hash` with the `transactionId` (from `transactions[].id`) and the on-chain hash — **this is mandatory** +2. Poll `get_transaction` until status is `CONFIRMED` or `FAILED` before moving to the next step + ### Step 7 — Confirm After all transactions are confirmed: @@ -124,6 +130,16 @@ For claiming rewards, restaking, or exiting: 2. Each action has `type`, `passthrough`, optional `arguments` 3. Call `actions_manage` or `actions_exit` with values from the response 4. Sign each transaction via MoonPay (same as Step 6) +5. Call `submit_hash` after each broadcast (**mandatory**), then poll `get_transaction` until `CONFIRMED` + +--- + +## Intelligence Notes + +- **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. +- **High APY (>20%):** Check `rewardRate.components` — if driven by incentives, flag as potentially short-lived. +- **submit_hash is mandatory:** Always call after every broadcast. Never skip — without it, the platform cannot track the transaction. +- **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. --- diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md index ef72626..95a1e80 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md @@ -10,8 +10,9 @@ Always match these types precisely. Type mismatches will cause MCP validation er - `limit` and `offset` are **always numbers**, never strings. Pass `20`, not `"20"`. - `amount` is **always a string** — human-readable decimal, never raw wei. Pass `"100"`, not `100`. - `network` is **always a lowercase string**. Pass `"base"`, not `"Base"`. +- `networks` is **always an array of lowercase strings**. Pass `["base"]`, not `"base"`. - `token` is **always uppercase**. Pass `"USDC"`, not `"usdc"`. -- `type` must be an **exact enum value** — see `yields_get_all` below. +- `types` must be an **array of exact enum values** — see `yields_get_all` below. --- @@ -21,16 +22,22 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| -| `network` | `string` | No | Lowercase. e.g. `"base"`, `"ethereum"`, `"arbitrum"` | +| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls — pass all in one array. | | `token` | `string` | No | Uppercase. e.g. `"USDC"`, `"ETH"`, `"WBTC"` | -| `type` | `string` (enum) | No | Must be one of: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. These are the **only valid types** — no others exist. If the user asks for a type not in this list, map it to the nearest match (e.g. "liquid staking" → `staking`, "earn" → `vault`, "LP" → `liquidity_pool`) or confirm with the user before calling the tool. | +| `types` | `string[]` (enum) | No | Array. Valid values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. Map user requests to nearest match or confirm before calling. | +| `sort` | `string` (enum) | No | Server-side sort. **Always pass `"rewardRateDesc"` by default.** Other values: `rewardRateAsc`, `statusEnterDesc`, `statusEnterAsc`, `statusExitDesc`, `statusExitAsc`. | +| `search` | `string` | No | Free-text search across names, tokens, providers. | +| `yieldIds` | `string[]` | No | Batch fetch up to 100 specific yields by ID. | +| `inputTokens` | `string[]` | No | Filter by accepted deposit tokens e.g. `["USDC"]`. | +| `providers` | `string[]` | No | Filter by provider IDs e.g. `["lido", "aave"]`. | +| `hasCooldownPeriod` | `boolean` | No | `true` to include only yields with a cooldown. | +| `hasWarmupPeriod` | `boolean` | No | `true` to include only yields with a warmup period. | | `limit` | `number` | No | ✅ Integer. Default: `20`, max: `50`. **Never pass as string.** | | `offset` | `number` | No | ✅ Integer. Default: `0`. **Never pass as string.** | -| `status` | `string` | No | `"enter"` or `"exit"` | **Correct:** ```json -{ "network": "base", "token": "USDC", "limit": 20, "offset": 0 } +{ "networks": ["base"], "token": "USDC", "sort": "rewardRateDesc", "limit": 20, "offset": 0 } ``` **Wrong:** ```json @@ -57,12 +64,17 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| | `yieldId` | `string` | ✅ Yes | Yield ID that requires validator selection | -| `limit` | `number` | No | ✅ Integer. Default: `10`. **Never pass as string.** | +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `50`. **Never pass as string.** | | `offset` | `number` | No | ✅ Integer. Default: `0`. **Never pass as string.** | +| `preferred` | `boolean` | No | `true` to return only curated validators. | +| `name` | `string` | No | Filter by validator name (partial match). | +| `status` | `string` | No | Filter by status e.g. `"active"`, `"jailed"`. | +| `address` | `string` | No | Filter by exact validator address. | +| `provider` | `string` | No | Filter by provider ID. | **Correct:** ```json -{ "yieldId": "ethereum-eth-p2p", "limit": 10, "offset": 0 } +{ "yieldId": "ethereum-eth-p2p", "limit": 20, "offset": 0 } ``` --- @@ -127,6 +139,7 @@ Always match these types precisely. Type mismatches will cause MCP validation er | `address` | `string` | ✅ Yes | User's wallet address | | `action` | `string` | ✅ Yes | Exact value from `pendingActions[].type` e.g. `"CLAIM_REWARDS"` | | `passthrough` | `string` | ✅ Yes | Exact value from `pendingActions[].passthrough` in balances response | +| `amount` | `string` | No | Human-readable amount for partial claims e.g. `"10.5"`. Omit to claim full amount. | **Correct:** ```json @@ -135,14 +148,123 @@ Always match these types precisely. Type mismatches will cause MCP validation er --- +### `submit_hash` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `transactionId` | `string` | ✅ Yes | UUID from `transactions[].id` in the action response | +| `hash` | `string` | ✅ Yes | On-chain tx hash after broadcasting e.g. `"0x1234…abcdef"` | + +**Call this after every broadcast — mandatory.** + +--- + +### `get_transaction` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `transactionId` | `string` | ✅ Yes | Same UUID passed to `submit_hash` | + +Returns `status`: `CREATED` | `BROADCASTED` | `CONFIRMED` | `FAILED` + +--- + +### `actions_get` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `actionId` | `string` | ✅ Yes | Action UUID from `actions_enter`, `actions_exit`, or `actions_manage` response | + +--- + +### `actions_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `address` | `string` | ✅ Yes | Wallet address to query | +| `statuses` | `string[]` | No | Filter by status. Values: `"CREATED"`, `"PROCESSING"`, `"WAITING_FOR_NEXT"`, `"SUCCESS"`, `"FAILED"`, `"CANCELED"`, `"STALE"` | +| `intent` | `string` | No | `"enter"`, `"exit"`, or `"manage"` | +| `type` | `string` | No | e.g. `"STAKE"`, `"UNSTAKE"`, `"CLAIM_REWARDS"` | +| `yieldId` | `string` | No | Filter by yield ID | +| `network` | `string` | No | Filter by network | +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `100`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `networks_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `search` | `string` | No | Filter by name or ID (min 2 chars) e.g. `"bnb"`, `"base"` | +| `category` | `string` | No | `"evm"`, `"cosmos"`, `"substrate"`, or `"misc"` | + +--- + +### `providers_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `100`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_reward_rate_history` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | +| `period` | `string` | No | `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` set. | +| `from` | `string` | No | ISO 8601 start date. Overrides `period`. | +| `to` | `string` | No | ISO 8601 end date. Defaults to now. | +| `interval` | `string` | No | `"day"`, `"week"`, `"month"`. Default: `"day"`. | +| `limit` | `number` | No | ✅ Integer. Default: `30`, max: `365`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_tvl_history` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | +| `period` | `string` | No | `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` set. | +| `from` | `string` | No | ISO 8601 start date. Overrides `period`. | +| `to` | `string` | No | ISO 8601 end date. Defaults to now. | +| `interval` | `string` | No | `"day"`, `"week"`, `"month"`. Default: `"day"`. | +| `limit` | `number` | No | ✅ Integer. Default: `30`, max: `365`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_risk` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | + +If response contains only `updatedAt` (no `exponentialFi` or `credora`), risk data is unavailable — not an error. + +--- + ## Quick Reference | Tool | `limit` / `offset` | `amount` | |---|---|---| -| `yields_get_all` | `number` ✅ | — | +| `yields_get_all` | `number` ✅ (max 50) | — | | `yields_get` | — | — | -| `yields_get_validators` | `number` ✅ | — | +| `yields_get_validators` | `number` ✅ (max 50) | — | | `yields_get_balances` | — | — | +| `yields_get_reward_rate_history` | `number` ✅ (max 365) | — | +| `yields_get_tvl_history` | `number` ✅ (max 365) | — | +| `yields_get_risk` | — | — | | `actions_enter` | — | `string` ✅ | | `actions_exit` | — | `string` ✅ | -| `actions_manage` | — | — | \ No newline at end of file +| `actions_manage` | — | `string` (optional) | +| `actions_get` | — | — | +| `actions_get_all` | `number` ✅ (max 100) | — | +| `submit_hash` | — | — | +| `get_transaction` | — | — | +| `networks_get_all` | — | — | +| `providers_get_all` | `number` ✅ (max 100) | — | \ No newline at end of file diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/output-formats.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/output-formats.md index 30edc94..ad5d43c 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/output-formats.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/output-formats.md @@ -26,23 +26,51 @@ All display rules for Yield.xyz Agentkit tool outputs. Always follow these forma ## yields_get_all — Listing Yields -Default: call with `limit: 20`, sort client-side by `rewardRate.total` descending, show **top 10**. +**Single network:** call with `limit: 20`, `sort: "rewardRateDesc"` — results arrive pre-sorted, show top 10. -Always display as a table, never as individual cards: +**Multiple networks — two intents, two strategies:** + +- **Unified search** ("show me top yields on ethereum and arbitrum", "find me ETH yields across chains") → single call with `networks: [...]`, `limit: 50`, `sort: "rewardRateDesc"`. Group results by network in the table. Acceptable that one network may dominate if its APYs are genuinely higher. + +- **Fair comparison** ("compare yields between ethereum and arbitrum", "which network has better USDC yields", "ethereum vs arbitrum") → run one call per network **in parallel** (same params, each with `limit: 20`). Show a table per network side by side. This guarantees every network gets fair representation regardless of APY distribution. + +Always display as a table, never as individual cards. + +**Single network example:** + +📈 Top ETH Yields on Ethereum + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | +Showing top 5 of 24 — ask for more or filter. + +**Multi-network comparison example (parallel calls, one per network):** + +📈 ETH Yields · Ethereum vs Arbitrum -📈 Top USDC Yields on Base (76 total) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +**🔵 Ethereum** +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +**🟠 Arbitrum** | # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | |---|----------|-------|-----|-----|------|--------|----------|-----| -| 🥇 | Morpho | coUSDC | 7.02% | $4.93M | vault | None | None | — | -| 🥈 | Morpho | csrUSDC | 6.20% | $322K | vault | None | None | — | -| 🥉 | Euler | eUSDC-29 | 6.04% | $145K | vault | None | None | — | -| #4 | Euler | eUSDC-49 | 5.81% | $567K | vault | None | None | — | -| #5 | Yo Protocol | yoUSD | 5.02% | — | vault | None | None | — | +| 🥇 | Aave | aWETH | 2.85% | $210M | lending | None | None | — | +| 🥈 | Compound | cWETH | 2.40% | $88M | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.10% | $65M | vault | None | None | — | -Showing top 10 of 76 — ask for more or filter by network/token. +Showing top 5 per network — ask for more or filter. Badges go in the Protocol cell when applicable, e.g. `Morpho ⭐`. @@ -150,6 +178,89 @@ Before calling any action tool, check and surface **all that apply**. Never skip --- +## actions_get_all — Displaying Action History + +Always display as a table, never as a list of cards: + +``` +📋 Action History · 0x742d…f44e +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Yield | Type | Amount | Network | Status | Date | +|---|-------|------|--------|---------|--------|------| +| 1 | Lido stETH | STAKE | 1.5 ETH | ethereum | ✅ SUCCESS | Apr 18 | +| 2 | Aave USDC | STAKE | 500 USDC | base | ⏳ PROCESSING | Apr 20 | +| 3 | Cosmos ATOM | CLAIM_REWARDS | — | cosmos | ✅ SUCCESS | Apr 15 | + +Showing 3 of 12 — ask for more or filter by status/network. +``` + +**Status badges:** +- `✅ SUCCESS` — confirmed on-chain +- `⏳ PROCESSING` — in-flight +- `🕐 CREATED` — submitted, not yet on-chain +- `⏸ WAITING_FOR_NEXT` — multi-step, awaiting next tx +- `❌ FAILED` — reverted or errored +- `🚫 CANCELED` — user-cancelled +- `⌛ STALE` — timed out + +--- + +## yields_get_reward_rate_history — APY Trend + +``` +📈 APY History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: 2.51% (Mar 28) + Low: 2.39% (Apr 10) + Current: 2.43% + + Trend: ↘ Slight decline over the period. +``` + +- `rewardRate` values are decimals — format as `(value * 100).toFixed(2) + "%"` +- If `items` is empty: *"Historical APY data is not available for this yield."* + +--- + +## yields_get_tvl_history — TVL Trend + +``` +📊 TVL History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: $32.1B (Mar 21) + Low: $30.4B (Apr 14) + Current: $31.2B + + Trend: → Relatively stable over the period. +``` + +- Format TVL values as `$4.93M` / `$322K` / `$1.2B` — never raw string +- Trend direction: ↗ Growing / ↘ Declining / → Stable (use ±5% as threshold) +- If `items` is empty: *"Historical TVL data is not available for this yield."* +- ⚠️ Flag a consistent downward trend as a potential risk signal + +--- + +## yields_get_risk — Risk Rating + +``` +🛡 Risk Assessment · Lido stETH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Exponential.fi: A (Score: 1) — "A" + 🔗 Full report: https://exponential.fi/pools/… +``` + +- If both `exponentialFi` and `credora` are present, show both +- If only one is present, show it and note the other is unavailable +- If neither is present: *"Detailed risk data is not available for this yield."* +- Always show the `exponentialFi.url` link when present + +--- + ## actions_enter / actions_exit / actions_manage — After an Action is Created **✅ Action Created — {intent}** diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/SKILL.md b/yield-agentkit-skills/skills/yield-agentkit-privy/SKILL.md index b8a82da..d679735 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/SKILL.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/SKILL.md @@ -217,6 +217,15 @@ The user can now issue DeFi instructions directly: --- +## Intelligence Notes + +- **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. +- **High APY (>20%):** Check `rewardRate.components` — if driven by incentives, flag as potentially short-lived. +- **submit_hash is mandatory:** Always call after every broadcast. Never skip — without it, the platform cannot track the transaction. +- **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. + +--- + ## Key Rules ### Yield.xyz AgentKit MCP @@ -280,7 +289,10 @@ transaction, in `stepIndex` order: 4. Privy TEE evaluates policy (if set) → signs → broadcasts Response: { "data": { "hash": "0x..." } } -5. Move to next transaction (if any) +5. Call submit_hash with transactionId (from transactions[].id) and the hash — MANDATORY + Then poll get_transaction until status is CONFIRMED or FAILED. + +6. Move to next transaction (if any) ``` For Solana, use `"method": "signAndSendTransaction"` and @@ -309,11 +321,20 @@ REST API directly with curl. | `yields_get` | **Always call before enter/exit** — inspect schema, limits, tokens | | `yields_get_balances` | **Always call before manage** — read pendingActions[] | | `yields_get_validators` | When enter schema has a `validatorAddress` optionsRef | +| `yields_get_reward_rate_history` | Historical APY trend for a yield | +| `yields_get_tvl_history` | Historical TVL trend for a yield | +| `yields_get_risk` | Detailed risk data for a yield | | `actions_enter` | Build enter-position transactions | | `actions_exit` | Build exit-position transactions | | `actions_manage` | Build claim / restake / redelegate transactions | +| `actions_get` | Check status of a specific action | +| `actions_get_all` | List action history for a wallet | +| `submit_hash` | **Call after every broadcast** — submit on-chain tx hash | +| `get_transaction` | Poll transaction status until CONFIRMED or FAILED | +| `networks_get_all` | Resolve network names to slugs | +| `providers_get_all` | List supported protocols/providers | -Full parameter reference: `references/yield-mcp-tools.md` +Full parameter reference and common mistakes: `references/yield-input-format.md` --- @@ -352,7 +373,6 @@ Read on demand when you need specifics. | **`references/yield-input-format.md`** | **Before every yield.xyz MCP tool call** — exact input parameters | | **`references/yield-output-format.md`** | **Before displaying any yield.xyz result** — exact output format per tool | | `references/architecture.md` | You need the full system diagram | -| `references/yield-mcp-tools.md` | You need MCP tool params or response shapes | | `references/yield-policies.md` | Data fetching and API usage rules for Yield AgentKit MCP | | `references/privy-policies.md` | Creating or updating policies and rules | | `references/privy-wallets.md` | Creating wallets or checking balances | diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-transactions.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-transactions.md index d86b09e..d493bb8 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-transactions.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-transactions.md @@ -147,11 +147,13 @@ a time, never in parallel: > back to hex before submitting to Privy. ``` -TX stepIndex=0: use nonce as-is → Privy signs → broadcast → poll CONFIRMED -TX stepIndex=1: increment nonce by 1 → Privy signs → broadcast → poll CONFIRMED -TX stepIndex=2: increment nonce by 2 → Privy signs → broadcast → poll CONFIRMED +TX stepIndex=0: use nonce as-is → Privy signs → broadcast → poll CONFIRMED → submit_hash ← mandatory +TX stepIndex=1: increment nonce by 1 → Privy signs → broadcast → poll CONFIRMED → submit_hash ← mandatory +TX stepIndex=2: increment nonce by 2 → Privy signs → broadcast → poll CONFIRMED → submit_hash ← mandatory ``` +After each transaction reaches `CONFIRMED`, call `submit_hash(actionId, hash)` on the Yield.xyz MCP before proceeding to the next transaction. This is mandatory — without it, Yield.xyz cannot track the position. + If any transaction reaches `FAILED`, stop immediately. Do not proceed with subsequent transactions. Report the failure and the hash to the user so they can inspect it on a block explorer. diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-wallets.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-wallets.md index 850d311..efd9049 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-wallets.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/privy-wallets.md @@ -38,6 +38,19 @@ curl -s "https://api.privy.io/v1/wallets" \ -H "privy-app-id: $PRIVY_APP_ID" | jq . ``` +**During onboarding, always call List Wallets before prompting to create a new one.** If the response contains existing wallets, show them to the user as a table: + +| # | Wallet ID | Address | Chain | Owner | +|---|-----------|---------|-------|-------| +| 1 | `abc123…` | `0x742d…` | ethereum | key quorum (semi-auto) | +| 2 | `def456…` | `0x9f3a…` | ethereum | none (autonomous) | + +Ask: *"You already have wallets set up. Would you like to use one of these, or create a new one?"* + +- If the user picks an existing wallet → store its `id` as `PRIVY_WALLET_ID` and proceed. +- If the user wants a new one → proceed to Create Wallet below. +- Use the `owner_id` field to determine wallet type: present → semi-autonomous (use Intents API), absent → autonomous (use normal RPC). + --- ## Get Wallet diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/semi-autonomous.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/semi-autonomous.md index 6fdc035..ee522a2 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/semi-autonomous.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/semi-autonomous.md @@ -256,8 +256,14 @@ Ask the user to check the dashboard and manually approve this. 6. Agent polls the intent until executed GET /v1/intents/{intent_id} → Poll until status = "executed" + → Extract transaction hash from the executed intent response -7. Agent confirms execution to user +7. Agent calls submit_hash on the Yield.xyz MCP (mandatory) + submit_hash(actionId, hash) + This is required — without it, Yield.xyz cannot track the position. + Never skip this step, even in semi-autonomous flow. + +8. Agent confirms execution to user ### Submitting the Intent (curl) @@ -342,6 +348,7 @@ TX stepIndex=0: → POST /v1/intents/wallets/{id}/rpc → get intent_id_0 → Notify user → user approves on dashboard → Poll GET /v1/intents/{intent_id_0} until "executed" + → Call submit_hash(actionId, hash) on Yield.xyz MCP ← mandatory → Confirm to user TX stepIndex=1: @@ -349,6 +356,7 @@ TX stepIndex=1: → POST /v1/intents/wallets/{id}/rpc → get intent_id_1 → Notify user → user approves on dashboard → Poll GET /v1/intents/{intent_id_1} until "executed" + → Call submit_hash(actionId, hash) on Yield.xyz MCP ← mandatory → Confirm to user ``` diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md index 55e8a15..2f0de02 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md @@ -10,8 +10,9 @@ Always match these types precisely. Type mismatches will cause MCP validation er - `limit` and `offset` are **always numbers**, never strings. Pass `20`, not `"20"`. - `amount` is **always a string** — human-readable decimal, never raw wei. Pass `"100"`, not `100`. - `network` is **always a lowercase string**. Pass `"base"`, not `"Base"`. +- `networks` is **always an array of lowercase strings**. Pass `["base"]`, not `"base"`. - `token` is **always uppercase**. Pass `"USDC"`, not `"usdc"`. -- `type` must be an **exact enum value** — see `yields_get_all` below. +- `types` must be an **array of exact enum values** — see `yields_get_all` below. --- @@ -21,16 +22,22 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| -| `network` | `string` | No | Lowercase. e.g. `"base"`, `"ethereum"`, `"arbitrum"` | +| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls — pass all in one array. | | `token` | `string` | No | Uppercase. e.g. `"USDC"`, `"ETH"`, `"WBTC"` | -| `type` | `string` (enum) | No | Must be one of: `staking`, `restaking`, `lending`, `vault`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. These are the **only valid types** — no others exist. If the user asks for a type not in this list, map it to the nearest match (e.g. "liquid staking" → `staking`, "earn" → `vault`, "LP" → `liquidity_pool`) or confirm with the user before calling the tool. | +| `types` | `string[]` (enum) | No | Array. Valid values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. Map user requests to nearest match or confirm before calling. | +| `sort` | `string` (enum) | No | Server-side sort. **Always pass `"rewardRateDesc"` by default.** Other values: `rewardRateAsc`, `statusEnterDesc`, `statusEnterAsc`, `statusExitDesc`, `statusExitAsc`. | +| `search` | `string` | No | Free-text search across names, tokens, providers. | +| `yieldIds` | `string[]` | No | Batch fetch up to 100 specific yields by ID. | +| `inputTokens` | `string[]` | No | Filter by accepted deposit tokens e.g. `["USDC"]`. | +| `providers` | `string[]` | No | Filter by provider IDs e.g. `["lido", "aave"]`. | +| `hasCooldownPeriod` | `boolean` | No | `true` to include only yields with a cooldown. | +| `hasWarmupPeriod` | `boolean` | No | `true` to include only yields with a warmup period. | | `limit` | `number` | No | ✅ Integer. Default: `20`, max: `50`. **Never pass as string.** | | `offset` | `number` | No | ✅ Integer. Default: `0`. **Never pass as string.** | -| `status` | `string` | No | `"enter"` or `"exit"` | **Correct:** ```json -{ "network": "base", "token": "USDC", "limit": 20, "offset": 0 } +{ "networks": ["base"], "token": "USDC", "sort": "rewardRateDesc", "limit": 20, "offset": 0 } ``` **Wrong:** ```json @@ -57,12 +64,17 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| | `yieldId` | `string` | ✅ Yes | Yield ID that requires validator selection | -| `limit` | `number` | No | ✅ Integer. Default: `10`. **Never pass as string.** | +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `50`. **Never pass as string.** | | `offset` | `number` | No | ✅ Integer. Default: `0`. **Never pass as string.** | +| `preferred` | `boolean` | No | `true` to return only curated validators. | +| `name` | `string` | No | Filter by validator name (partial match). | +| `status` | `string` | No | Filter by status e.g. `"active"`, `"jailed"`. | +| `address` | `string` | No | Filter by exact validator address. | +| `provider` | `string` | No | Filter by provider ID. | **Correct:** ```json -{ "yieldId": "ethereum-eth-p2p", "limit": 10, "offset": 0 } +{ "yieldId": "ethereum-eth-p2p", "limit": 20, "offset": 0 } ``` --- @@ -127,6 +139,7 @@ Always match these types precisely. Type mismatches will cause MCP validation er | `address` | `string` | ✅ Yes | User's wallet address | | `action` | `string` | ✅ Yes | Exact value from `pendingActions[].type` e.g. `"CLAIM_REWARDS"` | | `passthrough` | `string` | ✅ Yes | Exact value from `pendingActions[].passthrough` in balances response | +| `amount` | `string` | No | Human-readable amount for partial claims e.g. `"10.5"`. Omit to claim full amount. | **Correct:** ```json @@ -135,14 +148,138 @@ Always match these types precisely. Type mismatches will cause MCP validation er --- +### `submit_hash` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `transactionId` | `string` | ✅ Yes | UUID from `transactions[].id` in the action response | +| `hash` | `string` | ✅ Yes | On-chain tx hash after broadcasting e.g. `"0x1234…abcdef"` | + +**Call this after every broadcast — mandatory.** + +--- + +### `get_transaction` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `transactionId` | `string` | ✅ Yes | Same UUID passed to `submit_hash` | + +Returns `status`: `CREATED` | `BROADCASTED` | `CONFIRMED` | `FAILED` + +--- + +### `actions_get` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `actionId` | `string` | ✅ Yes | Action UUID from `actions_enter`, `actions_exit`, or `actions_manage` response | + +--- + +### `actions_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `address` | `string` | ✅ Yes | Wallet address to query | +| `statuses` | `string[]` | No | Filter by status. Values: `"CREATED"`, `"PROCESSING"`, `"WAITING_FOR_NEXT"`, `"SUCCESS"`, `"FAILED"`, `"CANCELED"`, `"STALE"` | +| `intent` | `string` | No | `"enter"`, `"exit"`, or `"manage"` | +| `type` | `string` | No | e.g. `"STAKE"`, `"UNSTAKE"`, `"CLAIM_REWARDS"` | +| `yieldId` | `string` | No | Filter by yield ID | +| `network` | `string` | No | Filter by network | +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `100`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `networks_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `search` | `string` | No | Filter by name or ID (min 2 chars) e.g. `"bnb"`, `"base"` | +| `category` | `string` | No | `"evm"`, `"cosmos"`, `"substrate"`, or `"misc"` | + +--- + +### `providers_get_all` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `limit` | `number` | No | ✅ Integer. Default: `20`, max: `100`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_reward_rate_history` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | +| `period` | `string` | No | `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` set. | +| `from` | `string` | No | ISO 8601 start date. Overrides `period`. | +| `to` | `string` | No | ISO 8601 end date. Defaults to now. | +| `interval` | `string` | No | `"day"`, `"week"`, `"month"`. Default: `"day"`. | +| `limit` | `number` | No | ✅ Integer. Default: `30`, max: `365`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_tvl_history` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | +| `period` | `string` | No | `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` set. | +| `from` | `string` | No | ISO 8601 start date. Overrides `period`. | +| `to` | `string` | No | ISO 8601 end date. Defaults to now. | +| `interval` | `string` | No | `"day"`, `"week"`, `"month"`. Default: `"day"`. | +| `limit` | `number` | No | ✅ Integer. Default: `30`, max: `365`. | +| `offset` | `number` | No | ✅ Integer. Default: `0`. | + +--- + +### `yields_get_risk` + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `yieldId` | `string` | ✅ Yes | Yield ID | + +If response contains only `updatedAt` (no `exponentialFi` or `credora`), risk data is unavailable — not an error. + +--- + +## Common Mistakes + +| Mistake | Correct Behaviour | +|---|---| +| Calling `actions_enter` without calling `yields_get` first | Always inspect the schema | +| Calling `actions_manage` without calling `yields_get_balances` first | Always read pendingActions[] | +| Modifying `unsignedTransaction` | Never — pass verbatim to Privy | +| Guessing or generating a `passthrough` value | Always take it from the balances response | +| Converting amounts to wei | Amounts are human-readable — the API handles decimals | +| Skipping `submit_hash` after broadcast | Always call — it's mandatory for tracking | +| Using `network` instead of `networks` in `yields_get_all` | Use the `networks` array parameter | +| Passing `type` instead of `types` in `yields_get_all` | Use the `types` array parameter | + +--- + ## Quick Reference | Tool | `limit` / `offset` | `amount` | |---|---|---| -| `yields_get_all` | `number` ✅ | — | +| `yields_get_all` | `number` ✅ (max 50) | — | | `yields_get` | — | — | -| `yields_get_validators` | `number` ✅ | — | +| `yields_get_validators` | `number` ✅ (max 50) | — | | `yields_get_balances` | — | — | +| `yields_get_reward_rate_history` | `number` ✅ (max 365) | — | +| `yields_get_tvl_history` | `number` ✅ (max 365) | — | +| `yields_get_risk` | — | — | | `actions_enter` | — | `string` ✅ | | `actions_exit` | — | `string` ✅ | -| `actions_manage` | — | — | \ No newline at end of file +| `actions_manage` | — | `string` (optional) | +| `actions_get` | — | — | +| `actions_get_all` | `number` ✅ (max 100) | — | +| `submit_hash` | — | — | +| `get_transaction` | — | — | +| `networks_get_all` | — | — | +| `providers_get_all` | `number` ✅ (max 100) | — | \ No newline at end of file diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-mcp-tools.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-mcp-tools.md deleted file mode 100644 index b5beea9..0000000 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-mcp-tools.md +++ /dev/null @@ -1,244 +0,0 @@ -# Yield.xyz AgentKit MCP Tools - -All 7 tools exposed by the Yield.xyz AgentKit MCP server. Use these -tools exclusively for all yield.xyz operations — never call the -yield.xyz REST API directly with curl. - -**MCP server registration:** -```bash -claude mcp add --transport http yield-agentkit https://mcp.yield.xyz/mcp -``` - ---- - -## Tool Index - -| Tool | Purpose | -|---|---| -| `yields_get_all` | Discover yields by network / token | -| `yields_get` | Full metadata for a single yield — **call before every action** | -| `yields_get_balances` | Current balances + pending actions — **call before manage** | -| `yields_get_validators` | Validators for delegation-based yields | -| `actions_enter` | Build enter-position transactions | -| `actions_exit` | Build exit-position transactions | -| `actions_manage` | Build claim / restake / redelegate transactions | - ---- - -## `yields_get_all` - -Discover yield opportunities. Filter by network and/or token. - -**Parameters:** - -| Parameter | Type | Required | Default | Description | -|---|---|---|---|---| -| `network` | string | No | — | Network slug (e.g., `base`, `ethereum`, `arbitrum`, `solana`) | -| `token` | string | No | — | Token symbol (e.g., `USDC`, `ETH`). Omit for all yields on network. | -| `limit` | number | No | 20 | Items per page (max 100) | -| `offset` | number | No | 0 | Pagination offset | - -**Response (abbreviated):** -```json -{ - "data": [ - { - "id": "base-usdc-aave-v3-lending", - "token": { "symbol": "USDC", "network": "base" }, - "apy": "0.0521", - "tvl": "450000000", - "metadata": { "name": "Aave V3 USDC on Base", "provider": "aave" } - } - ], - "hasNextPage": true -} -``` - -**Output format:** - -Present as a table sorted by APY descending: - -``` -| # | Yield ID | Protocol | APY | TVL | -|----|-------------------------------|-------------|--------|-------| -| 1 | base-usdc-aave-v3-lending | Aave V3 | 5.21% | $450M | -| 2 | base-usdc-compound-v3-lending | Compound V3 | 4.87% | $210M | -``` - ---- - -## `yields_get` - -Fetch full metadata for a single yield, including the exact argument -schema for entering and exiting the position. - -**Call this before every `actions_enter` or `actions_exit` call.** - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `yieldId` | string | Yes | Unique yield identifier (e.g., `base-usdc-aave-v3-lending`) | - -**Key fields to inspect:** - -``` -mechanics.arguments.enter ← required fields for actions_enter -mechanics.arguments.exit ← required fields for actions_exit -mechanics.entryLimits ← min / max deposit amounts -inputTokens[] ← tokens the yield accepts as input -``` - -**Each field in `mechanics.arguments.enter` (ArgumentFieldDto):** - -| Field | What it tells you | -|---|---| -| `name` | The field key to include in arguments_json | -| `type` | Value type: `string`, `number`, `address`, `enum`, `boolean` | -| `required` | Whether it must be included | -| `options` | Static enum choices — use these directly | -| `optionsRef` | Dynamic endpoint to fetch valid values — **call it if present** | -| `minimum` / `maximum` | Value constraints | -| `isArray` | Whether the field expects an array | - -If `optionsRef` is present on any field (e.g., for `validatorAddress`), -call `yields_get_validators` to get the valid options before proceeding. - ---- - -## `yields_get_balances` - -Check current position balances and discover available pending actions -(claim rewards, restake, redelegate, etc.). - -**Call this before every `actions_manage` call.** - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `address` | string | Yes | Wallet address | -| `network` | string | Yes | Network the address is on (e.g., `base`) | -| `yieldIds` | string[] | Optional | Optional array of yield ID strings to filter results | - -**Response (abbreviated):** -```json -[ - { - "amount": "205.34", - "token": { "symbol": "USDC" }, - "pendingActions": [ - { - "type": "CLAIM_REWARDS", - "passthrough": "eyJ...", - "arguments": [] - } - ] - } -] -``` - -**Reading `pendingActions[]`:** - -Each entry maps directly to `actions_manage` parameters: -- `type` → `action` parameter -- `passthrough` → `passthrough` parameter (pass verbatim, never modify) -- `arguments` → `arguments_json` parameter (if the array is non-empty) - ---- - -## `yields_get_validators` - -List validators for delegation-based yields that require validator -selection (Some liquid staking yields, etc.). - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `yieldId` | string | Yes | Unique yield identifier | -| `limit` | number | No | Max validators to return (default 20) | - -**When to call:** Only when `yields_get` returns an enter-schema field -that has `optionsRef` pointing to a validators endpoint. That field -requires a `validatorAddress` value — this tool provides it. - ---- - -## `actions_enter` - -Build unsigned transactions to enter a yield position. - -**Always call `yields_get` first** to read the exact enter schema. - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `yieldId` | string | Yes | Unique yield identifier | -| `address` | string | Yes | Wallet address entering the position | -| `amount` | `string` | ✅ Yes | ✅ Human-readable decimal string. e.g. `"100"`, `"0.5"`. **Never raw wei. Never a number.** | -| `args` | `object` | No | Optional. May include `validatorAddress` (string), `inputToken` (string) | - -**Response shape:** - -The response contains an `id` (action ID) and a `transactions[]` array. -Each transaction in the array includes: -- `id` — the yield.xyz transaction ID (needed for `submit-hash`) -- `stepIndex` — execution order, starting at 0 -- `type` — e.g., `"APPROVAL"`, `"STAKE"`, `"SUPPLY"` -- `unsignedTransaction` — the raw transaction object to pass to Privy. - ---- - -## `actions_exit` - -Build unsigned transactions to exit a yield position. - -**Always call `yields_get` first** to read the exact exit schema. - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `yieldId` | string | Yes | Unique yield identifier | -| `address` | string | Yes | Wallet address exiting the position | -| `amount` | `string` | ✅ Yes | ✅ Human-readable decimal string. e.g. `"100"`. **Never raw wei. Never a number.** | -| `passthrough` | `string` | No | From `pendingActions[].passthrough` in balances response | -| `validatorAddress` | `string` | No | Required if yield uses validator selection | - -**Note:** Some exit schemas include a `passthrough` field. When present, -fetch it from `yields_get_balances` → `pendingActions[]` on the matching -balance entry. Never generate or guess a passthrough value. - ---- - -## `actions_manage` - -Build unsigned transactions for managing an existing position — claim -rewards, restake, redelegate, etc. - -**Always call `yields_get_balances` first** to read available -`pendingActions[]` on the position. - -**Parameters:** - -| Parameter | Type | Required | Description | -|---|---|---|---| -| `yieldId` | string | Yes | Unique yield identifier | -| `address` | string | Yes | Wallet address | -| `action` | string | Yes | Action type from `pendingActions[].type` | -| `passthrough` | string | Yes | Passthrough string from `pendingActions[].passthrough` — pass verbatim | -| `arguments_json` | string | No | JSON string from `pendingActions[].arguments` schema, if non-empty | - ---- - -## Common Mistakes - -| Mistake | Correct Behaviour | -|---|---| -| Calling `actions_enter` without calling `yields_get` first | Always inspect the schema | -| Calling `actions_manage` without calling `yields_get_balances` first | Always read pendingActions[] | -| Modifying `unsignedTransaction` | Never — pass verbatim to Privy | -| Guessing or generating a `passthrough` value | Always take it from the balances response | -| Converting amounts to wei | Amounts are human-readable — the API handles decimals | \ No newline at end of file diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-output-format.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-output-format.md index c7fac6f..6008995 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-output-format.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-output-format.md @@ -26,23 +26,49 @@ All display rules for Yield.xyz Agent tool outputs. Always follow these formats ## yields_get_all — Listing Yields -Default: call with `limit: 20`, sort client-side by `rewardRate.total` descending, show **top 10**. +**Single network:** call with `limit: 20`, `sort: "rewardRateDesc"` — results arrive pre-sorted, show top 10. -Always display as a table, never as individual cards: +**Multiple networks — two intents, two strategies:** + +- **Unified search** ("show me top yields on ethereum and arbitrum", "find me ETH yields across chains") → single call with `networks: [...]`, `limit: 50`, `sort: "rewardRateDesc"`. Group results by network in the table. Acceptable that one network may dominate if its APYs are genuinely higher. + +- **Fair comparison** ("compare yields between ethereum and arbitrum", "which network has better USDC yields", "ethereum vs arbitrum") → run one call per network **in parallel** (same params, each with `limit: 20`). Show a table per network side by side. This guarantees every network gets fair representation regardless of APY distribution. + +Always display as a table, never as individual cards. + +**Single network example:** + +📈 Top ETH Yields on Ethereum +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +Showing top 5 of 24 — ask for more or filter. + +**Multi-network comparison example (parallel calls, one per network):** -📈 Top USDC Yields on Base (76 total) +📈 ETH Yields · Ethereum vs Arbitrum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +**🔵 Ethereum** +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +**🟠 Arbitrum** | # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | |---|----------|-------|-----|-----|------|--------|----------|-----| -| 🥇 | Morpho | coUSDC | 7.02% | $4.93M | vault | None | None | — | -| 🥈 | Morpho | csrUSDC | 6.20% | $322K | vault | None | None | — | -| 🥉 | Euler | eUSDC-29 | 6.04% | $145K | vault | None | None | — | -| #4 | Euler | eUSDC-49 | 5.81% | $567K | vault | None | None | — | -| #5 | Yo Protocol | yoUSD | 5.02% | — | vault | None | None | — | +| 🥇 | Aave | aWETH | 2.85% | $210M | lending | None | None | — | +| 🥈 | Compound | cWETH | 2.40% | $88M | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.10% | $65M | vault | None | None | — | -Showing top 10 of 76 — ask for more or filter by network/token. +Showing top 5 per network — ask for more or filter. Badges go in the Protocol cell when applicable, e.g. `Morpho ⭐`. @@ -150,6 +176,89 @@ Before calling any action tool, check and surface **all that apply**. Never skip --- +## actions_get_all — Displaying Action History + +Always display as a table, never as a list of cards: + +``` +📋 Action History · 0x742d…f44e +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Yield | Type | Amount | Network | Status | Date | +|---|-------|------|--------|---------|--------|------| +| 1 | Lido stETH | STAKE | 1.5 ETH | ethereum | ✅ SUCCESS | Apr 18 | +| 2 | Aave USDC | STAKE | 500 USDC | base | ⏳ PROCESSING | Apr 20 | +| 3 | Cosmos ATOM | CLAIM_REWARDS | — | cosmos | ✅ SUCCESS | Apr 15 | + +Showing 3 of 12 — ask for more or filter by status/network. +``` + +**Status badges:** +- `✅ SUCCESS` — confirmed on-chain +- `⏳ PROCESSING` — in-flight +- `🕐 CREATED` — submitted, not yet on-chain +- `⏸ WAITING_FOR_NEXT` — multi-step, awaiting next tx +- `❌ FAILED` — reverted or errored +- `🚫 CANCELED` — user-cancelled +- `⌛ STALE` — timed out + +--- + +## yields_get_reward_rate_history — APY Trend + +``` +📈 APY History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: 2.51% (Mar 28) + Low: 2.39% (Apr 10) + Current: 2.43% + + Trend: ↘ Slight decline over the period. +``` + +- `rewardRate` values are decimals — format as `(value * 100).toFixed(2) + "%"` +- If `items` is empty: *"Historical APY data is not available for this yield."* + +--- + +## yields_get_tvl_history — TVL Trend + +``` +📊 TVL History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: $32.1B (Mar 21) + Low: $30.4B (Apr 14) + Current: $31.2B + + Trend: → Relatively stable over the period. +``` + +- Format TVL values as `$4.93M` / `$322K` / `$1.2B` — never raw string +- Trend direction: ↗ Growing / ↘ Declining / → Stable (use ±5% as threshold) +- If `items` is empty: *"Historical TVL data is not available for this yield."* +- ⚠️ Flag a consistent downward trend as a potential risk signal + +--- + +## yields_get_risk — Risk Rating + +``` +🛡 Risk Assessment · Lido stETH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Exponential.fi: A (Score: 1) — "A" + 🔗 Full report: https://exponential.fi/pools/… +``` + +- If both `exponentialFi` and `credora` are present, show both +- If only one is present, show it and note the other is unavailable +- If neither is present: *"Detailed risk data is not available for this yield."* +- Always show the `exponentialFi.url` link when present + +--- + ## actions_enter / actions_exit / actions_manage — After an Action is Created **✅ Action Created — {intent}** diff --git a/yield-agentkit-skills/skills/yield-agentkit/SKILL.md b/yield-agentkit-skills/skills/yield-agentkit/SKILL.md index c48f2b6..db593c4 100644 --- a/yield-agentkit-skills/skills/yield-agentkit/SKILL.md +++ b/yield-agentkit-skills/skills/yield-agentkit/SKILL.md @@ -23,9 +23,18 @@ The MCP server exposes these tools directly — call them like any other tool: - **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 --- @@ -63,13 +72,19 @@ Never dump raw JSON or plain comma-separated data. Always follow the formats def List and filter yield opportunities across networks and tokens. **Key parameters:** -- `network` — e.g. `"base"`, `"ethereum"`, `"arbitrum"` -- `token` — e.g. `"USDC"`, `"ETH"`, `"WBTC"` -- `type` — must be one of: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. These are the **only valid types** — no others exist. If the user asks for a type not in this list, map it to the nearest match (e.g. "liquid staking" → `staking`, "earn" → `vault`, "LP" → `liquidity_pool`) or confirm with the user before calling the tool. -- `limit` / `offset` — pagination (default limit: 20, max: 50) -- `status` — filter by `enter`/`exit` availability - -**Returns:** `{ total, offset, limit, items: YieldDto[] }` +- `networks` — array of network slugs e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls per network — pass all in one array. 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. @@ -92,7 +107,12 @@ List validators for a yield that requires validator selection. **Key parameters:** - `yieldId` -- `limit` / `offset` — pagination +- `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[] }` @@ -156,11 +176,13 @@ Initiate exiting (withdrawing from) a yield position. --- ### 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` @@ -168,6 +190,138 @@ Perform a management action on an existing position (claim rewards, restake, cha --- +### 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 @@ -198,32 +352,53 @@ Perform a management action on an existing position (claim rewards, restake, cha ## Recommended Workflows ### Find and enter a yield -1. `yields_get_all` — `network` + `token`, `limit: 20` -2. Sort by APY, present top 10 in formatted table +1. `yields_get_all` — `networks` + `token`, `sort: "rewardRateDesc"`, `limit: 20` +2. Present top 10 in formatted table 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. Return transaction summary +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, `limit: 20` -2. Sort APY descending, top 10 ranked table +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 @@ -231,6 +406,10 @@ Perform a management action on an existing position (claim rewards, restake, cha - **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 results:** Group by network for clarity. +- **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. \ No newline at end of file +- **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. \ No newline at end of file diff --git a/yield-agentkit-skills/skills/yield-agentkit/references/output-formats.md b/yield-agentkit-skills/skills/yield-agentkit/references/output-formats.md index eb244b6..37a9e6f 100644 --- a/yield-agentkit-skills/skills/yield-agentkit/references/output-formats.md +++ b/yield-agentkit-skills/skills/yield-agentkit/references/output-formats.md @@ -26,23 +26,49 @@ All display rules for Yield.xyz Agent tool outputs. Always follow these formats ## yields_get_all — Listing Yields -Default: call with `limit: 20`, sort client-side by `rewardRate.total` descending, show **top 10**. +**Single network:** call with `limit: 20`, `sort: "rewardRateDesc"` — results arrive pre-sorted, show top 10. -Always display as a table, never as individual cards: +**Multiple networks — two intents, two strategies:** + +- **Unified search** ("show me top yields on ethereum and arbitrum", "find me ETH yields across chains") → single call with `networks: [...]`, `limit: 50`, `sort: "rewardRateDesc"`. Group results by network in the table. Acceptable that one network may dominate if its APYs are genuinely higher. + +- **Fair comparison** ("compare yields between ethereum and arbitrum", "which network has better USDC yields", "ethereum vs arbitrum") → run one call per network **in parallel** (same params, each with `limit: 20`). Show a table per network side by side. This guarantees every network gets fair representation regardless of APY distribution. + +Always display as a table, never as individual cards. + +**Single network example:** + +📈 Top ETH Yields on Ethereum +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +Showing top 5 of 24 — ask for more or filter. + +**Multi-network comparison example (parallel calls, one per network):** -📈 Top USDC Yields on Base (76 total) +📈 ETH Yields · Ethereum vs Arbitrum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +**🔵 Ethereum** +| # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | +|---|----------|-------|-----|-----|------|--------|----------|-----| +| 🥇 | Lido | stETH | 3.80% | $32.1B | staking | None | 1–5 days | — | +| 🥈 | Aave | aWETH | 3.10% | $1.2B | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.95% | $540M | vault | None | None | — | + +**🟠 Arbitrum** | # | Protocol | Vault | APY | TVL | Type | Lockup | Cooldown | Min | |---|----------|-------|-----|-----|------|--------|----------|-----| -| 🥇 | Morpho | coUSDC | 7.02% | $4.93M | vault | None | None | — | -| 🥈 | Morpho | csrUSDC | 6.20% | $322K | vault | None | None | — | -| 🥉 | Euler | eUSDC-29 | 6.04% | $145K | vault | None | None | — | -| #4 | Euler | eUSDC-49 | 5.81% | $567K | vault | None | None | — | -| #5 | Yo Protocol | yoUSD | 5.02% | — | vault | None | None | — | +| 🥇 | Aave | aWETH | 2.85% | $210M | lending | None | None | — | +| 🥈 | Compound | cWETH | 2.40% | $88M | lending | None | None | — | +| 🥉 | Morpho | mWETH | 2.10% | $65M | vault | None | None | — | -Showing top 10 of 76 — ask for more or filter by network/token. +Showing top 5 per network — ask for more or filter. Badges go in the Protocol cell when applicable, e.g. `Morpho ⭐`. @@ -150,6 +176,89 @@ Before calling any action tool, check and surface **all that apply**. Never skip --- +## actions_get_all — Displaying Action History + +Always display as a table, never as a list of cards: + +``` +📋 Action History · 0x742d…f44e +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +| # | Yield | Type | Amount | Network | Status | Date | +|---|-------|------|--------|---------|--------|------| +| 1 | Lido stETH | STAKE | 1.5 ETH | ethereum | ✅ SUCCESS | Apr 18 | +| 2 | Aave USDC | STAKE | 500 USDC | base | ⏳ PROCESSING | Apr 20 | +| 3 | Cosmos ATOM | CLAIM_REWARDS | — | cosmos | ✅ SUCCESS | Apr 15 | + +Showing 3 of 12 — ask for more or filter by status/network. +``` + +**Status badges:** +- `✅ SUCCESS` — confirmed on-chain +- `⏳ PROCESSING` — in-flight +- `🕐 CREATED` — submitted, not yet on-chain +- `⏸ WAITING_FOR_NEXT` — multi-step, awaiting next tx +- `❌ FAILED` — reverted or errored +- `🚫 CANCELED` — user-cancelled +- `⌛ STALE` — timed out + +--- + +## yields_get_reward_rate_history — APY Trend + +``` +📈 APY History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: 2.51% (Mar 28) + Low: 2.39% (Apr 10) + Current: 2.43% + + Trend: ↘ Slight decline over the period. +``` + +- `rewardRate` values are decimals — format as `(value * 100).toFixed(2) + "%"` +- If `items` is empty: *"Historical APY data is not available for this yield."* + +--- + +## yields_get_tvl_history — TVL Trend + +``` +📊 TVL History · Lido stETH · Last 30 days +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + High: $32.1B (Mar 21) + Low: $30.4B (Apr 14) + Current: $31.2B + + Trend: → Relatively stable over the period. +``` + +- Format TVL values as `$4.93M` / `$322K` / `$1.2B` — never raw string +- Trend direction: ↗ Growing / ↘ Declining / → Stable (use ±5% as threshold) +- If `items` is empty: *"Historical TVL data is not available for this yield."* +- ⚠️ Flag a consistent downward trend as a potential risk signal + +--- + +## yields_get_risk — Risk Rating + +``` +🛡 Risk Assessment · Lido stETH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Exponential.fi: A (Score: 1) — "A" + 🔗 Full report: https://exponential.fi/pools/… +``` + +- If both `exponentialFi` and `credora` are present, show both +- If only one is present, show it and note the other is unavailable +- If neither is present: *"Detailed risk data is not available for this yield."* +- Always show the `exponentialFi.url` link when present + +--- + ## actions_enter / actions_exit / actions_manage — After an Action is Created **✅ Action Created — {intent}** From e63d96db2e5ceee2efaece4daa12dd88fb2112be Mon Sep 17 00:00:00 2001 From: Ishita Agarwal Date: Mon, 20 Apr 2026 14:35:21 +0530 Subject: [PATCH 2/3] fix: resolved contradiction between multipple network passing --- yield-agentkit-plugin/yield-agentkit/SKILL.md | 2 +- yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md | 2 +- .../skills/yield-agentkit-moonpay/references/input-format.md | 2 +- .../yield-agentkit-privy/references/yield-input-format.md | 2 +- yield-agentkit-skills/skills/yield-agentkit/SKILL.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/yield-agentkit-plugin/yield-agentkit/SKILL.md b/yield-agentkit-plugin/yield-agentkit/SKILL.md index 27c926b..640f554 100644 --- a/yield-agentkit-plugin/yield-agentkit/SKILL.md +++ b/yield-agentkit-plugin/yield-agentkit/SKILL.md @@ -54,7 +54,7 @@ Modifying `unsignedTransaction` **will result in permanent loss of funds.** List and filter yield opportunities across networks and tokens. **Key parameters:** -- `networks` — array of network slugs e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls per network — pass all in one array. Use `networks_get_all` to resolve a network name if unsure. +- `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. diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md index a0af7be..6db0c05 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/SKILL.md @@ -68,7 +68,7 @@ Before anything else: Call `yields_get_all` with the user's preferred network and token. - Pass `sort: "rewardRateDesc"` — always use server-side sort, never re-sort client-side -- Pass `networks` as an array e.g. `["base"]` — never make multiple calls per network +- Pass `networks` as an array e.g. `["base"]` - Default to `limit: 20` unless user asks for more - Show a table: Protocol, Type, APY, Network, Token - Valid `types` values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool` diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md index 95a1e80..689b5a3 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/input-format.md @@ -22,7 +22,7 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| -| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls — pass all in one array. | +| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. For unified search pass all in one array (`limit: 50`). For fair cross-network comparison, run one call per network in parallel (`limit: 20` each) — see output-formats.md. | | `token` | `string` | No | Uppercase. e.g. `"USDC"`, `"ETH"`, `"WBTC"` | | `types` | `string[]` (enum) | No | Array. Valid values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. Map user requests to nearest match or confirm before calling. | | `sort` | `string` (enum) | No | Server-side sort. **Always pass `"rewardRateDesc"` by default.** Other values: `rewardRateAsc`, `statusEnterDesc`, `statusEnterAsc`, `statusExitDesc`, `statusExitAsc`. | diff --git a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md index 2f0de02..d25642e 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md +++ b/yield-agentkit-skills/skills/yield-agentkit-privy/references/yield-input-format.md @@ -22,7 +22,7 @@ Always match these types precisely. Type mismatches will cause MCP validation er | Parameter | Type | Required | Notes | |---|---|---|---| -| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls — pass all in one array. | +| `networks` | `string[]` | No | Array of lowercase slugs. e.g. `["base"]`, `["ethereum", "arbitrum"]`. For unified search pass all in one array (`limit: 50`). For fair cross-network comparison, run one call per network in parallel (`limit: 20` each) — see yield-output-format.md. | | `token` | `string` | No | Uppercase. e.g. `"USDC"`, `"ETH"`, `"WBTC"` | | `types` | `string[]` (enum) | No | Array. Valid values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. Map user requests to nearest match or confirm before calling. | | `sort` | `string` (enum) | No | Server-side sort. **Always pass `"rewardRateDesc"` by default.** Other values: `rewardRateAsc`, `statusEnterDesc`, `statusEnterAsc`, `statusExitDesc`, `statusExitAsc`. | diff --git a/yield-agentkit-skills/skills/yield-agentkit/SKILL.md b/yield-agentkit-skills/skills/yield-agentkit/SKILL.md index db593c4..37ab228 100644 --- a/yield-agentkit-skills/skills/yield-agentkit/SKILL.md +++ b/yield-agentkit-skills/skills/yield-agentkit/SKILL.md @@ -72,7 +72,7 @@ Never dump raw JSON or plain comma-separated data. Always follow the formats def List and filter yield opportunities across networks and tokens. **Key parameters:** -- `networks` — array of network slugs e.g. `["base"]`, `["ethereum", "arbitrum"]`. Never make multiple calls per network — pass all in one array. Use `networks_get_all` to resolve a network name if unsure. +- `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. From ba9e38473044715688db503332ede5ac9a45fc7f Mon Sep 17 00:00:00 2001 From: Ishita Agarwal Date: Mon, 20 Apr 2026 14:52:10 +0530 Subject: [PATCH 3/3] fix: correct balances endpoint mapping --- yield-agentkit-plugin/yield-agentkit/references/key-rules.md | 2 +- .../skills/yield-agentkit-moonpay/references/key-rules.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/yield-agentkit-plugin/yield-agentkit/references/key-rules.md b/yield-agentkit-plugin/yield-agentkit/references/key-rules.md index 7b9d25f..8dbced1 100644 --- a/yield-agentkit-plugin/yield-agentkit/references/key-rules.md +++ b/yield-agentkit-plugin/yield-agentkit/references/key-rules.md @@ -41,7 +41,7 @@ | `yields_get_all` | `GET /v1/yields` | | `yields_get` | `GET /v1/yields/{yieldId}` | | `yields_get_validators` | `GET /v1/yields/{yieldId}/validators` | - | `yields_get_balances` | `POST /v1/yields/{yieldId}/balances` | + | `yields_get_balances` | `POST /v1/yields/balances` | | `actions_enter` | `POST /v1/actions/enter` | | `actions_exit` | `POST /v1/actions/exit` | | `actions_manage` | `POST /v1/actions/manage` | diff --git a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/key-rules.md b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/key-rules.md index 268c0c4..6e86cc0 100644 --- a/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/key-rules.md +++ b/yield-agentkit-skills/skills/yield-agentkit-moonpay/references/key-rules.md @@ -45,7 +45,7 @@ | `yields_get_all` | `GET /v1/yields` | | `yields_get` | `GET /v1/yields/{yieldId}` | | `yields_get_validators` | `GET /v1/yields/{yieldId}/validators` | -| `yields_get_balances` | `POST /v1/yields/{yieldId}/balances` | +| `yields_get_balances` | `POST /v1/yields/balances` | | `actions_enter` | `POST /v1/actions/enter` | | `actions_exit` | `POST /v1/actions/exit` | | `actions_manage` | `POST /v1/actions/manage` |