YieldAgent by Yield.xyz

Access the complete on-chain yield landscape through Yield.xyz's unified API. Discover 2600+ yields across staking, lending, vaults, restaking, and liquidity pools. Build transactions and manage positions across 80+ networks.

CRITICAL: Never Modify Transactions From The API

DO NOT MODIFY unsignedTransaction returned by the API UNDER ANY CIRCUMSTANCES.

> Do not change, reformat, or "fix" any part of it — not addresses, amounts, fees, encoding, or any other field, on any chain.

> If the amount is wrong: Request a NEW action from the API with the correct amount.

If gas is insufficient: Ask the user to add funds, then request a NEW action.

If anything looks wrong: STOP. Always request a new action with corrected arguments. Never attempt to "fix" an existing transaction.

> Modifying unsignedTransaction WILL RESULT IN PERMANENT LOSS OF FUNDS.

Key Rules

The API is self-documenting. Every yield describes its own requirements through the YieldDto. Before taking any action, always fetch the yield and inspect it. The mechanics field tells you everything: what arguments are needed (mechanics.arguments.enter, .exit), entry limits (mechanics.entryLimits), and what tokens are accepted (inputTokens[]). Never assume — always check the yield first.

• Always fetch the yield before calling an action. Call GET /v1/yields/{yieldId} and read mechanics.arguments.enter (or .exit) to discover the exact fields required. Each yield is different — the schema is the contract. Do not guess or hardcode arguments.

• name: the field name (e.g., amount, validatorAddress, inputToken)
• type: the value type (string, number, address, enum, boolean)
• required: whether it must be provided
• options: static choices for enum fields (e.g., ["individual", "batched"])
• optionsRef: a dynamic API endpoint to fetch choices (e.g., /api/v1/validators?integrationId=...) — if present, call it to get the valid options (validators, providers, etc.)
• minimum / maximum: value constraints
• isArray: whether the field expects an array

• For manage actions, always fetch balances first. Call POST /v1/yields/{yieldId}/balances and read pendingActions[] on each balance. Each pending action tells you its type, passthrough, and optional arguments schema. Only call manage with values from this response.
• Amounts are human-readable. "100" means 100 USDC. "1" means 1 ETH. "0.5" means 0.5 SOL. Do NOT convert to wei or raw integers — the API handles decimals internally.
• Set inputToken to what the user wants to deposit — but only if inputToken appears in the yield's mechanics.arguments.enter schema. The API handles the full flow (swaps, wrapping, routing) to get the user into the position.
• ALWAYS submit the transaction hash after broadcasting — no exceptions. For every transaction: sign, broadcast, then submit the hash via PUT /v1/transactions/{txId}/submit-hash with { "hash": "0x..." }. Balances will not appear until the hash is submitted. This is the most common mistake — do not skip this step.
• Execute transactions in exact order. If an action has multiple transactions, they are ordered by stepIndex. Wait for CONFIRMED before proceeding to the next. Never skip or reorder.
• Consult {baseDir}/references/openapi.yaml for types. All enums, DTOs, and schemas are defined there. Do not hardcode values.

Quick Start

# Discover yields on a network
./scripts/find-yields.sh base USDC

# Inspect a yield's schema before entering
./scripts/get-yield-info.sh base-usdc-aave-v3-lending

# Enter a position (amounts are human-readable)
./scripts/enter-position.sh base-usdc-aave-v3-lending 0xYOUR_ADDRESS '{"amount":"100"}'

# Check balances and pending actions
./scripts/check-portfolio.sh base-usdc-aave-v3-lending 0xYOUR_ADDRESS

Scripts

Common Patterns

Enter a Position

• Discover yields: find-yields.sh base USDC
• Inspect the yield: get-yield-info.sh — read mechanics.arguments.enter
• Enter: enter-position.sh
  '{"amount":"100"}'
• For each transaction: wallet signs → broadcast → submit hash → wait for CONFIRMED

Manage a Position

• Check balances: check-portfolio.sh
• Read pendingActions[] — each has { type, passthrough, arguments? }
• Manage: manage-position.sh

Full Lifecycle

• Discover → 2. Enter → 3. Check balances → 4. Claim rewards → 5. Exit

Transaction Flow

After any action (enter/exit/manage), the response contains transactions[]. For EACH transaction:

• Pass unsignedTransaction to wallet skill for signing and broadcasting
• Submit the hash — PUT /v1/transactions/{txId}/submit-hash with { "hash": "0x..." }
• Poll GET /v1/transactions/{txId} until CONFIRMED or FAILED
• Proceed to next transaction

TX1: sign → broadcast → submit-hash → poll until CONFIRMED
TX2: sign → broadcast → submit-hash → poll until CONFIRMED
TX3: sign → broadcast → submit-hash → poll until CONFIRMED

unsignedTransaction format varies by chain. See {baseDir}/references/chain-formats.md for details.

API Endpoints

All endpoints documented in {baseDir}/references/openapi.yaml. Quick reference:

References

Detailed reference files — read on demand when you need specifics.

• API types and schemas: {baseDir}/references/openapi.yaml — source of truth for all DTOs, enums, request/response shapes
• Chain transaction formats: {baseDir}/references/chain-formats.md — unsignedTransaction encoding per chain family (EVM, Cosmos, Solana, Substrate, etc.)
• Wallet integration: {baseDir}/references/wallet-integration.md — Crossmint, Portal, Turnkey, Privy, signing flow
• Agent conversation examples: {baseDir}/references/examples.md — 10 conversation patterns with real yield IDs
• Safety checks: {baseDir}/references/safety.md — pre-execution checks, constraints

Error Handling

The API returns structured errors with message, error, and statusCode. Read the message. Error shapes are in {baseDir}/references/openapi.yaml. Respect retry-after on 429s.

Add-on Modules

Modular instructions that extend core functionality. Read when relevant.

• {baseDir}/references/superskill.md — 40 advanced capabilities: rate monitoring, cross-chain comparison, portfolio diversification, rotation workflows, reward harvesting, scheduled checks

Resources

• API Docs: https://docs.yield.xyz
• API Recipes: https://github.com/stakekit/api-recipes
• Get API Key: https://dashboard.yield.xyz