AgentKit builder

Install the AgentKit builder plugin and prompt it to write a working yield.xyz integration into your app.

This guide installs the yield-xyz-agentkit-builder plugin in Claude Code, then walks through the first prompt that gets it writing real integration code against your own API key. For what the plugin is and what it generates, see AgentKit for builders.

Prerequisites

• A yield.xyz API key for a project with at least one yield enabled. Discovery calls are project-scoped: an empty project returns empty yield lists, and a call on a non-enabled yield returns 400. Get a key from Projects & API keys and enable at least one yield before you prompt the builder.
• Claude Code. It is the primary target for this plugin. The skill also installs standalone for other MCP-compatible agents, and the plugin ships a Codex manifest (.codex-plugin/plugin.json) so Codex picks up the same skill and MCP config.
• Node.js, so npx can run. The plugin’s bundled MCP connection launches npx -y mcp-remote https://mcp.yield.xyz/mcp, which needs Node available on your machine.

Install the plugin

1. Add the AgentKit marketplace

   Once per machine:

   /plugin marketplace add stakekit/agentkit
   
2. Install the builder plugin

   /plugin install yield-xyz-agentkit-builder@agentkit
   

   This installs the builder skill and its MCP connection; see AgentKit for builders for what each does. You don’t need the base yield-xyz-agentkit plugin installed too.

3. Confirm the MCP connected

   claude mcp list
   

   Look for yield-xyz-agentkit with status Connected. If it’s missing or failing, re-run the install command or check .mcp.json for typos. This step is a convenience, not a blocker: if the MCP never connects, the agent falls back to fetching https://api.yield.xyz/docs.json directly and keeps building.

Not using Claude Code? Install the skill standalone instead:

npx skills add stakekit/agentkit --skill yield-xyz-agentkit-builder

Give the builder context in your first prompt

The builder asks clarifying questions if you leave things out, but a first prompt that already answers these gets you a working integration faster:

• Existing app or new project. Adding yield to a repo that already exists gets a component, route, or endpoints wired into your stack and conventions. Only a new project gets scaffolded from scratch.
• Stack and language. TypeScript/React, Next.js, Python, Go, whatever you’re actually running.
• Product type and signing model, since this decides who signs: a custody platform or backend service signs server-side (HSM/KMS); a consumer wallet or mobile app signs client-side with the user’s own browser wallet or embedded/WalletConnect signer; a neobank or yield aggregator adds server-side signing plus its own concerns (fee monetization, discovery at scale).
• Network, token, and the target yield or yield type you want (for example, USDC lending on Base, or ETH liquid staking).
• Which action(s) you want: enter, exit, manage, or the full lifecycle.
• Where your API key lives: an environment variable, conventionally YIELD_API_KEY. The builder asks for a key before it generates any code if you don’t supply one, and it never hardcodes it.

Two example first prompts:

I have an existing Next.js app with a Postgres backend. Custody platform, server-side
signing via our KMS. Add a POST /api/yield/enter endpoint that deposits USDC into an
Aave lending yield on Base for a given user address. My key is in YIELD_API_KEY.

New project, greenfield. Scaffold a React app where a connected browser wallet
(MetaMask) can deposit USDC into a vault yield on Base and see its balance.
Discover the vault from my project's enabled yields. My key is in YIELD_API_KEY.

What the builder does

Once it has your key and enough context, the builder grounds every field name against the live spec (yield_get_api_spec, or https://api.yield.xyz/docs.json directly if the MCP isn’t connected) rather than trusting memory or cached docs, and reads the target yield’s mechanics.arguments before writing any action call so required fields aren’t guessed. It then writes code that calls https://api.yield.xyz directly through REST or @yieldxyz/sdk, following the full enter/exit lifecycle: discover, read the schema, build the action, sign and broadcast each transaction in order, then submit the hash so yield.xyz can track it to confirmation.

For a new project it also installs dependencies, starts the servers and reports the working URLs; for an existing app it runs your dev server and points you at the route it added.

Verify the generated code before you trust it

Read the code before you run it against real funds. Check for:

• Every request goes to https://api.yield.xyz, never a placeholder or guessed host.
• The x-api-key header reads from an environment variable; no key literal anywhere in the source.
• Action arguments come from the yield’s mechanics.arguments.enter / .exit schema, not copied from another yield or hardcoded from memory.
• Amounts are human-readable decimal strings ("100", "1.5"), never wei or another raw integer.
• transactions[] are processed in stepIndex order, and a transaction already at a terminal status (SKIPPED, CONFIRMED, FAILED) is skipped rather than re-signed.
• For the synchronous execution pattern, the code waits for each transaction to confirm before signing the next.
• submit-hash (or submit) is called exactly once per transaction, right after broadcast.
• Status tracking polls GET /v1/transactions/{id} or GET /v1/actions/{id} to a terminal status rather than assuming an immediate result.
• Any list of yields, balances, validators, or transactions is paginated, not fetched in full and sliced client-side.
• Nothing modifies unsignedTransaction before signing.
• No MCP action tool (actions_enter, actions_exit, actions_manage, submit_hash, yields_get_balances, and so on) appears in the shipped code path; those are build-time-only tools for the agent.
• Every new dependency in the manifest is one you recognize, not something the builder introduced without asking.

Then run a small test transaction with a low-value amount, and inspect the unsigned transaction yourself before you sign it. We construct. You sign. yield.xyz never signs your transactions and never holds your keys.

For the full status vocabulary these checks rely on, see Actions. For chain-specific signing detail beyond what the builder generates, see Transaction signing.

Troubleshooting

Discovery returns an empty yield list

Discovery is project-scoped. A project with no yields enabled gets empty results from GET /v1/yields and related endpoints, not an error. Enable at least one yield for the key’s project (see Yield blocking) before prompting the builder to build against it.

A specific yield returns 400

A 400 with a message like Yield "<id>" is not enabled for this project means the yield exists in the catalog but isn’t turned on for your key. Enable it in the dashboard rather than treating this as a bug in the generated code.

The MCP server never connects

claude mcp list not showing yield-xyz-agentkit as Connected doesn’t block the build. The builder falls back to fetching https://api.yield.xyz/docs.json directly for the same field-name grounding; keep prompting it normally.

Next steps

AgentKit for builders

What the plugin is, what it generates per situation, and how it’s wired.

Prompting patterns

More prompt patterns for discovery, actions, and error handling.

Enter and exit flows

Build the deposit and withdrawal flow by hand, endpoint by endpoint.

Guardrails

The non-custodial rules an agent or generated integration must follow.