Yield.xyz AgentKit — Builder Skill

This skill helps developers build applications that integrate with the Yield.xyz API. It generates integration code, guides architecture decisions, and helps ensure correct API usage across all supported chains and protocols.

Scope: this skill builds Yield integrations — staking, lending, vaults, and RWA across 80+ networks.

What ships vs. what's build-time: the integration you ship always calls https://api.yield.xyz directly — via the @yieldxyz/sdk or REST/curl. Nothing the user ships calls the MCP. The MCP's doc tools are only a build-time reference for you (the builder) — they let you ground field names against the live spec/docs while generating code. The MCP is not a runtime dependency and not a hard prerequisite; if it's unavailable, fetch https://api.yield.xyz/docs.json directly.

Quickstart — minimal end-to-end (Yield)

The shortest happy path from nothing to a confirmed position. Language-agnostic REST; swap curl for fetch/requests/etc. Always confirm exact field names against the live spec (yield_get_api_spec or https://api.yield.xyz/docs.json) before generating code — the shapes below are a map, not a contract.

1. Discover — GET /v1/yields?network=<network>&token=<token> to find a yield id.
2. Read the schema — GET /v1/yields/{id} and read

mechanics.arguments.enter.fields[] to learn exactly which arguments the enter action requires (e.g. amount, sometimes a validator address).

1. Build the action — POST /v1/actions/enter with { yieldId, address, arguments }

(amounts are human-readable strings, not wei). Returns HTTP 201 with a transactions[] array.

1. Sign + broadcast each transaction — iterate transactions[] in **stepIndex

order**; for each, parse and sign its unsignedTransaction with the wallet for that chain, then broadcast. Never modify unsignedTransaction (Critical Rule #5).

1. Report the hash — PUT /v1/transactions/{id}/submit-hash with the broadcast

hash so Yield.xyz can track it.

1. Poll to confirm — GET /v1/transactions/{id} until status is CONFIRMED

(there are no webhooks — poll with backoff).

Non-TypeScript (Python, Go, …)? Every endpoint is plain REST — see references/signing-patterns.md for server-side signing (e.g. Python eth-account), and references/chains/<chain>.md.

For the full lifecycle (status states, error/retry handling, exit/manage) see references/transaction-lifecycle.md; for per-chain signing and transaction decoding see references/chains/<chain>.md.

When This Skill Activates

This skill is for building apps — not for exploring yields conversationally.

Activate when the user says things like:

• "Build me a staking app"
• "Integrate Yield.xyz into my project"
• "Generate code to deposit USDC into Aave"
• "How do I call the Yield.xyz API from my backend?"
• "Set up a neobank with yield features"
• "Add yield to my wallet app"

Route to a different skill when:

• Exploring yields conversationally ("What's the best USDC yield on Base?") → yield-xyz-agentkit.
• Building an autonomous agent — an agent with its own wallet that discovers and executes** yield strategies itself (autonomous or policy-gated signing/broadcasting) → a connector, which carries the wallet, policy, and signing an agent needs:
• yield-xyz-agentkit-privy — Privy agentic wallets; autonomous & semi-autonomous (approval) strategies; policy enforcement.
• yield-xyz-agentkit-moonpay — MoonPay wallet auth + signing.

This skill builds the integration surface — discovery, transaction construction, and wiring your own signing infra. Use it for the API/app layer; use a connector for an agent's wallet + autonomous execution. (For one-off execution the user wants to run, see Critical Rule #3.)

Critical Rules

1. API Base URL

The production base URL is https://api.yield.xyz, with the live OpenAPI spec at https://api.yield.xyz/docs.json. Every code sample, fetch call, and SDK config must use this base URL.

2. API Key Requirement

Every integration requires the user's own Yield.xyz API key.

Before generating any integration code, ask the user for their API key. If they don't have one, direct them to https://dashboard.yield.xyz/login to create a project and get a key.

Once you have the key:

• Use it in all generated code (x-api-key header or SDK apiKey config)
• Never hardcode the demo key into the user's codebase
• Recommend storing it in an environment variable (e.g., YIELD_API_KEY)

3. Never Call MCP Action Tools in a Builder Session — and Never Advise the User to

The MCP server's action tools (actions_enter, actions_exit, submit_hash, yields_get_balances, etc.) return trimmed/reshaped responses that omit fields present in the full API, so code built against them will be wrong. Never call them, and never advise the user to call them as part of their integration. Build against the REST API instead — call the live endpoint directly with the user's key (https://api.yield.xyz/v1/...) for the full, unmodified response. The only MCP tools you use are the read-only doc tools (yield_get_api_spec, yield_list_repos, etc.).

Explaining what an action tool does is fine (explaining ≠ calling). If the user actually wants to run one — enter/exit/manage, check live balances — that's out of scope here; redirect them to the matching execute skill (yield-xyz-agentkit, yield-xyz-agentkit-privy, yield-xyz-agentkit-moonpay), which carry the wallet/signing guidance execution requires.

Full action-tool list + which are safe (doc tools) vs. never-call, with a one-line description and REST equivalent for each — see [`references/mcp-tools.md`](./references/mcp-tools.md).

4. Never Hardcode Field Names — Always Fetch from the Live Spec

The API evolves continuously. Do not rely on hardcoded field names or schemas from this skill's reference files. Instead:

1. Fetch the live OpenAPI spec — yield_get_api_spec, or api.yield.xyz/docs.json

directly — to discover current field names, types, and constraints

1. Call the actual API endpoint with the user's key to see the real response shape
2. Then generate code based on what the live spec and actual responses show

This ensures generated code always matches the current API, even after breaking changes.

5. Never Modify Unsigned Transactions

Generated code must NEVER modify unsignedTransaction returned by the API. Not addresses, amounts, fees, encoding — nothing.

Amount wrong? Call the action endpoint again with the corrected amount. Gas insufficient? Ask user to add funds, call again.

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

6. Never Kill a Port Without Asking

When a local process (dev server, preview, DB, mock) hits a port conflict, never kill the occupying process automatically — the user may have it intentionally bound.

1. Try the default port (3000 Node, 5173 Vite, 8000 Python). If free, use it.
2. If taken, fall back to a nearby free port via PORT= env var or --port flag.
3. Only as a last resort, ask the user before killing anything — and kill only after

they explicitly agree.

7. Only Install Verified, Widely-Used Dependencies

Every dependency is a supply-chain risk — a single typosquatted package's postinstall can exfiltrate the user's YIELD_API_KEY, RPC keys, or wallet seed. Default to the smallest dependency set: prefer built-ins (fetch, crypto, …) and packages already implied by the stack (viem, wagmi, @tanstack/react-query, etc.). Before installing anything the user didn't name, verify it on npm (trusted maintainer, high weekly downloads, recent release, real repo, exact name — no typosquats). If a package fails those checks, stop and ask before installing (offer a popular alternative or a short inline implementation). Applies to every manifest — package.json, requirements.txt, go.mod, Cargo.toml.

8. Always Include Pagination When Listing Yields

Yield.xyz exposes 2,900+ yields across 80+ networks, so pagination is a default, not a feature request. Every list view you generate — yields, balances, validators, transactions — must ship paginated from the start; never render an unbounded list.

• Use the API's built-in params on GET /v1/yields (offset/limit, offset-only,

max limit 100; default ~20–50 per page). Don't fetch-all client-side and slice.

• Provide page navigation, preserve active filters across pages, and show the total

count when the API returns it.

• Sort, search, and filter via API query params, not on the client — a client-side

sort across thousands of yields produces wrong results across pages. Check the live spec for the available params; fall back to client-side only if a needed param truly doesn't exist.

Workflow

Step 0 — Register the MCP Doc Tools if Available (optional, best-effort)

If you can, register the yield-xyz-agentkit MCP server so its read-only doc tools (yield_get_api_spec, yield_lookup_docs, yield_fetch_doc, yield_troubleshoot_error, yield_list_repos) are available to you while you build. These help you (the builder) ground field names against the live spec and docs as you generate code. This is a build-time convenience, not a prerequisite — the integration you ship does not call the MCP, so don't block the build on it. If the MCP isn't registered, fetch https://api.yield.xyz/docs.json directly instead. (Static guidance — chains, transaction lifecycle, yield types, safety — lives in this skill's own references/ files, not on the MCP.)

Registration command, for convenience —

For Claude Code:

claude mcp add yield-xyz-agentkit --transport http https://mcp.yield.xyz/mcp
claude mcp list   # verify "yield-xyz-agentkit" shows "Connected"

For other agents (Codex, Gemini CLI, etc.), write the yield-xyz-agentkit entry into the appropriate MCP config file (~/.mcp.json or project-local .mcp.json).

If the MCP isn't available, just continue. The one thing the doc tools give you is easier live-spec lookup, and that's reachable without them: fetch https://api.yield.xyz/docs.json directly (the yield_list_repos content is a nice-to-have, not essential), so field-name grounding comes from docs.json + live responses. Full details and config snippets are in references/setup.md.

Step 1 — Understand the Use Case & Recommend an Approach

This skill builds Yield integrations (staking, lending, vaults, RWA), so there's no product choice to make — go straight to understanding what the user is building. Ask what they're building; the answer determines the integration option, architecture, signing approach, and which reference files to load.

First, fork on existing app vs. new project — most clients have an existing app:

• Existing app (you're adding yield to a repo that already exists) → the deliverable

is a component/route or a few endpoints plus the install/wiring into their codebase. Do not scaffold a new project. Match their stack, their conventions, their build.

• New project (greenfield, nothing exists yet) → scaffold a fresh project end-to-end.

Pick the integration option (default is decisive and situational):

• Greenfield / unspecified staking app → `@stakekit/widget` — drop-in UI, least

integration code to a running app. Already have a wallet / wagmi setup? The widget doesn't force its own connect flow — pass `externalProviders` (your address + signer) plus `disableInjectedProviderDiscovery`. See [`references/integration-patterns.md`](./references/integration-patterns.md) → "Bring your own signing infra".

• Existing React app needing custom UI → SDK or REST — typed API access via

@yieldxyz/sdk, or call REST directly.

• Non-JS (Python, Go, …) → REST — every endpoint is plain HTTP.

Then map their product type to the signing/architecture pattern below.

Map the product type to architecture and signing:

See [`references/integration-patterns.md`](./references/integration-patterns.md) for architecture diagrams and patterns per product type.

When the docs don't fully resolve an integration question — or you're stuck implementing one — use `yield_list_repos` to find the relevant public repo (widget, SDK, api-recipes, signers, shield, etc.) and read its raw source as a working reference.

Step 2 — Inspect the Live Spec & Real Responses

Ground every field name in the live API before generating code — never assume from memory:

• Spec: yield_get_api_spec({ endpoint: "/v1/actions/enter" }), or

curl https://api.yield.xyz/docs.json | jq '.paths["/v1/actions/enter"]'.

• Real response: call the endpoint with the user's key and inspect the actual shape:

  curl -s "https://api.yield.xyz/v1/yields?network=base&token=USDC&limit=1" \
    -H "x-api-key: $YIELD_API_KEY" | jq .

Build against what the spec and live response show — not the shapes in these docs.

Step 3 — Generate Code

Generate code that uses api.yield.xyz with the key in the x-api-key header, uses field names exactly as the live spec/responses show, follows the full transaction lifecycle from the Quickstart above (and references/transaction-lifecycle.md for status states, errors/retries, and exit/manage), and applies the signing pattern for the user's product type and wallet — see references/signing-patterns.md.

Step 4 — Run the Project Yourself and Report URLs

Do not tell the user "now run `npm run dev`" and walk away. The skill's job isn't done until the integration is actually running and you've shown the user it works.

If you integrated into an EXISTING app: run their dev server (use their existing dev/start script) and point the user at the specific route or endpoints you added — verify those work. Don't try to scaffold or boot a new multi-service project; the "Frontend / Backend / health URL" summary below is for greenfield new apps, not for a route you dropped into a running app.

If you scaffolded a NEW project (greenfield): run every step yourself:

1. Install dependencies yourself — pnpm install / npm install / yarn install

based on the lockfile you generated. Surface install errors and fix them.

1. Verify required env vars are set — YIELD_API_KEY, RPC URLs, any wallet

secrets. If something is missing, ask the user for it and write it into .env.

1. Start the servers yourself — run the dev command(s) for every service the

project exposes (backend API, frontend, worker, etc.). For multi-service projects, start each one (in the background if needed) and wait until each is healthy.

1. Respect the port rules (see Critical Rule #6) — try the default port, fall

back to a nearby free port, and only ask the user before killing an occupied port as a last resort.

1. Report every useful URL back to the user in a single clean summary. For

example:

   Project is running.

   Frontend:        http://localhost:3000
   Backend API:     http://localhost:3001
   API health:      http://localhost:3001/health

Include whichever URLs apply — frontend, backend, admin panel, WebSocket endpoint, any auth callback URLs, block explorer link for the test chain, etc.

1. Do a quick smoke test yourself — hit the backend health endpoint, load the

frontend, verify the Yield.xyz call returns data. Only then hand over to the user with the URL list above. If anything failed, fix it first; don't hand over a broken project.

Only after the above is green should you suggest a test transaction (small amount, low-value chain) and point the user at the block explorer to verify it.

Common Pitfalls

Before generating any code, read [`references/common-pitfalls.md`](./references/common-pitfalls.md).

This file documents real errors encountered during builder sessions — wrong API URLs, incorrect field names, browser wallet gas issues, and more. Every pitfall listed there has caused real failures. Avoid them.

Reference Files

Read these on demand when generating code. Always read the relevant reference before generating code for that topic.

SDK Option

For TypeScript/JavaScript projects, the @yieldxyz/sdk package wraps the REST API. It's a configured singleton — configure() once, then call sdk.api.*:

import { sdk } from "@yieldxyz/sdk";
sdk.configure({ apiKey: process.env.YIELD_API_KEY });

const yields = await sdk.api.getYields({ network: "ethereum" });

Source: github.com/stakekit/sdk (published on npm as @yieldxyz/sdk).

For other languages (Python, Go, Rust), or any non-TypeScript agent, skip the SDK and call the REST API directly — every endpoint is plain HTTP. Refer to https://api.yield.xyz/docs.json for the complete OpenAPI spec (or the yield_get_api_spec tool), and see github.com/stakekit/api-recipes for runnable REST examples.