> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/documentation/ai-agents/integrate/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](/documentation/get-started/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

<Steps>
  <Step title="Add the AgentKit marketplace">
    Once per machine:

    ```bash theme={null}
    /plugin marketplace add stakekit/agentkit
    ```
  </Step>

  <Step title="Install the builder plugin">
    ```bash theme={null}
    /plugin install yield-xyz-agentkit-builder@agentkit
    ```

    This installs the builder skill and its MCP connection; see [AgentKit for builders](/documentation/ai-agents/integrate/agentkit-for-builders#what-happens-after-installation) for what each does. You don't need the base `yield-xyz-agentkit` plugin installed too.
  </Step>

  <Step title="Confirm the MCP connected">
    ```bash theme={null}
    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.
  </Step>
</Steps>

Not using Claude Code? Install the skill standalone instead:

```bash theme={null}
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:

```text theme={null}
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.
```

```text theme={null}
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.

<Warning>
  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.
</Warning>

For the full status vocabulary these checks rely on, see [Actions](/documentation/earn/core-concepts/actions#status-lifecycle). For chain-specific signing detail beyond what the builder generates, see [Transaction signing](/guides/transaction-signing/index).

## Troubleshooting

<AccordionGroup>
  <Accordion title="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](/documentation/advanced-setup/dashboard/yield-blocking)) before prompting the builder to build against it.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="AgentKit for builders" icon="hammer" href="/documentation/ai-agents/integrate/agentkit-for-builders">
    What the plugin is, what it generates per situation, and how it's wired.
  </Card>

  <Card title="Prompting patterns" icon="message" href="/guides/ai/prompting-patterns">
    More prompt patterns for discovery, actions, and error handling.
  </Card>

  <Card title="Enter and exit flows" icon="arrow-right-arrow-left" href="/guides/earn/enter-exit-flows">
    Build the deposit and withdrawal flow by hand, endpoint by endpoint.
  </Card>

  <Card title="Guardrails" icon="shield" href="/documentation/ai-agents/agentkit/guardrails">
    The non-custodial rules an agent or generated integration must follow.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.