feat: add new tools and sync mcp changes

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"]`. For unified search pass all in one array. For fair cross-network comparison ("ethereum vs arbitrum", "which network is better") run one call per network in parallel — see Intelligence Notes. Use `networks_get_all` to resolve a network name if unsure.
+- `token` — token symbol e.g. `"USDC"`, `"ETH"`, `"WBTC"` or a contract address.
+- `types` — array of yield types. Valid values: `staking`, `restaking`, `lending`, `vault`, `fixed_yield`, `real_world_asset`, `concentrated_liquidity_pool`, `liquidity_pool`. These are the **only valid types**. Map user requests to nearest match (e.g. "liquid staking" → `staking`, "earn" → `vault`, "LP" → `liquidity_pool`) or confirm before calling.
+- `sort` — server-side sort order. **Always pass `rewardRateDesc` by default** — do not re-sort client-side. Switch to `rewardRateAsc`, `statusEnterDesc`, `statusEnterAsc`, `statusExitDesc`, or `statusExitAsc` per user request.
+- `search` — free-text search across yield names, token names, provider names, and descriptions.
+- `yieldIds` — batch fetch up to 100 specific yields by ID.
+- `inputTokens` — filter by accepted deposit token symbols or addresses e.g. `["USDC"]`.
+- `providers` — filter by provider IDs e.g. `["lido", "aave"]`. Use `providers_get_all` to get valid IDs.
+- `hasCooldownPeriod` — `true` to show only yields with a cooldown, `false` to exclude them.
+- `hasWarmupPeriod` — `true` to show only yields with a warmup period.
+- `limit` / `offset` — pagination (default 20, max 50)
+
+**Returns:** `{ total, offset, limit, items[] }` — each item includes: `id`, `tokenSymbol`, `network`, `type`, `providerId`, `rewardRate`, `tvlUsd`, `status`, `cooldownPeriod`, `warmupPeriod`, `lockupPeriod`, `minEntry`, `maxEntry`
 
 **Use when:** User wants to browse or compare yield options.
 
@@ -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,13 +165,146 @@ 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`
 
 **Use when:** User has pending actions on a balance, or wants to claim rewards.
 
 ---
 
+### 8. `submit_hash`
+Submit the on-chain transaction hash after the user has signed and broadcasted a transaction.
+
+**This is mandatory after every transaction.** Never skip this step.
+
+**Key parameters:**
+- `transactionId` — the transaction UUID from the `transactions[]` array in the `ActionDto`
+- `hash` — the on-chain hash returned after broadcasting e.g. `"0x1234…abcdef"`
+
+**Returns:** Updated `TransactionDto`
+
+**Use when:** User has signed and broadcasted any transaction from an enter, exit, or manage action.
+
+---
+
+### 9. `get_transaction`
+Poll the status of a transaction by its ID.
+
+**Key parameters:**
+- `transactionId` — the transaction UUID from the `transactions[]` array
+
+**Returns:** `TransactionDto` with `status`: `CREATED` | `BROADCASTED` | `CONFIRMED` | `FAILED`
+
+**Use when:** After calling `submit_hash`, poll until status is `CONFIRMED` or `FAILED` before proceeding to the next transaction in a multi-step action.
+
+---
+
+### 10. `actions_get`
+Get the current status and transactions of a specific action.
+
+**Key parameters:**
+- `actionId` — the action UUID returned by `actions_enter`, `actions_exit`, or `actions_manage`
+
+**Returns:** Full `ActionDto` with current status and all transactions.
+
+**Use when:** Checking whether an action has completed, or tracking an async execution pattern where approval may take time.
+
+---
+
+### 11. `actions_get_all`
+List past and pending actions for a wallet address.
+
+**Key parameters:**
+- `address` — wallet address to query
+- `statuses` — filter by one or more statuses: `"CREATED"`, `"PROCESSING"`, `"WAITING_FOR_NEXT"`, `"SUCCESS"`, `"FAILED"`, `"CANCELED"`, `"STALE"`
+- `intent` — filter by `"enter"`, `"exit"`, or `"manage"`
+- `type` — filter by action type e.g. `"STAKE"`, `"UNSTAKE"`, `"CLAIM_REWARDS"`
+- `yieldId` — filter by yield ID
+- `network` — filter by network
+- `limit` / `offset` — pagination (default 20, max 100)
+
+**Returns:** Paginated list of `ActionDto`
+
+**Use when:** User asks "show my pending actions", "what did I do recently?", or to find actions waiting for a next step.
+
+---
+
+### 12. `networks_get_all`
+List all networks supported by Yield.xyz.
+
+**Key parameters:**
+- `search` — filter by name or ID (min 2 chars) e.g. `"eth"`, `"bnb"`, `"base"`
+- `category` — filter by `"evm"`, `"cosmos"`, `"substrate"`, or `"misc"`
+
+**Returns:** Array of `{ id, name, category, logoURI }`
+
+**Use when:** Resolving a network name the user mentioned (e.g. user says "Binance Smart Chain" → search `"bnb"` to get the correct slug), or when listing supported chains.
+
+---
+
+### 13. `providers_get_all`
+List all supported protocols and validator providers (e.g. Lido, Aave, Morpho).
+
+**Key parameters:**
+- `limit` / `offset` — pagination (default 20, max 100)
+
+**Returns:** Paginated list with `id`, `name`, `description`, `website`, `tvlUsd`, `type`
+
+**Use when:** User asks what protocols Yield.xyz supports, or to get valid provider IDs for `yields_get_all` filters.
+
+---
+
+### 14. `yields_get_reward_rate_history`
+Get historical APY/reward rate snapshots for a yield over time.
+
+**Key parameters:**
+- `yieldId`
+- `period` — predefined window: `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` are set.
+- `from` / `to` — ISO 8601 date range e.g. `"2025-01-01T00:00:00Z"`. Overrides `period`.
+- `interval` — sampling resolution: `"day"`, `"week"`, `"month"`. Default: `"day"`.
+- `limit` / `offset` — pagination (default 30, max 365)
+
+**Returns:** `{ yieldId, interval, from, to, items: [{ timestamp, rewardRate }], total }`
+
+**Important:** If `items` is empty (`total: 0`), historical reward rate data is not available for this yield. This is expected for many yields — it is not an error.
+
+**Use when:** User asks "has this APY been stable?", "what was the yield last month?", or wants to see APY trends.
+
+---
+
+### 15. `yields_get_tvl_history`
+Get historical Total Value Locked snapshots for a yield.
+
+**Key parameters:**
+- `yieldId`
+- `period` — predefined window: `"1d"`, `"7d"`, `"30d"`, `"90d"`, `"1y"`, `"all"`. Default: `"30d"`. Ignored if `from`/`to` are set.
+- `from` / `to` — ISO 8601 date range. Overrides `period`.
+- `interval` — `"day"`, `"week"`, `"month"`. Default: `"day"`.
+- `limit` / `offset` — pagination (default 30, max 365)
+
+**Returns:** `{ yieldId, interval, from, to, items: [{ timestamp, tvlUsd }], total }`
+
+**Important:** If `items` is empty (`total: 0`), TVL history is not available for this yield. This is expected for many yields — it is not an error.
+
+**Use when:** User asks about protocol health, TVL growth/decline, or wants to assess liquidity trends.
+
+---
+
+### 16. `yields_get_risk`
+Get detailed risk parameters for a yield — more granular than the `risk` field in `yields_get`.
+
+**Key parameters:**
+- `yieldId`
+
+**Returns:** `{ updatedAt, exponentialFi: { poolRating, poolScore, ratingDescription, url }, credora: { rating, score, ... } }`
+
+**Important:** If the response contains only `updatedAt` with no `exponentialFi` or `credora` fields, detailed risk data is not available for this yield. This is expected for many yields — it is not an error. Fall back to the `risk` field in `yields_get` if present.
+
+**Use when:** User asks about protocol safety, risk rating, or audit status for a specific yield.
+
+---
+
 ## Key Data Shapes
 
 ### `YieldDto` — a yield opportunity
@@ -196,39 +349,64 @@ 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
 
 - **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.

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` |