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

# Prompting patterns

> Give a coding agent the context it needs to build a correct Yield.xyz integration, and verify what it produces.

These patterns work in Claude Code, Cursor, Codex, or any coding agent, whether or not it has MCP access. The agent's training data goes stale the moment the API changes; a good prompt tells it what to build and where to check its own work against the live API instead of guessing from memory.

## Give it the right context

Paste this and fill in the brackets. An agent that starts with this much context asks fewer clarifying questions and guesses at fewer fields.

```text theme={null}
Product: Earn API, base URL https://api.yield.xyz, requests authenticated with
header x-api-key: $YIELD_API_KEY (my key is in that env var, never a literal in code).

Network: [e.g. Base]
Asset: [e.g. USDC]
Target yield: [a yieldId, e.g. base-usdc-aave-v3-lending] OR
  "discover a yield for this network and asset from my project's enabled yields"
Custody / signing: [browser wallet | server-side custody (HSM/KMS) | smart account]
Action(s): [enter | exit | manage/claim | balances | full lifecycle]

Constraints:
- GET /v1/yields and related discovery endpoints only return yields enabled for
  my API key's project. Don't assume a yield exists just because it's in a doc
  example; discover it or tell me to enable it first.
- Amounts are human-readable decimal strings ("100", not wei).

Sources to use, in this order:
1. The live OpenAPI spec at https://api.yield.xyz/docs.json for exact field names.
2. https://docs.yield.xyz (or https://docs.yield.xyz/llms.txt) for how the flow works.
3. If MCP doc tools are connected (yield_get_api_spec, yield_lookup_docs,
   yield_fetch_doc, yield_troubleshoot_error), use them instead of memory.
Do not rely on training data for field names, endpoint shapes, or status values.
```

Adjust the bracketed lines per task: a portfolio view needs several networks, not one; a debugging prompt needs an error body instead of an action. See [AI coding tools](https://docs.yield.xyz/guides/ai/cursor-setup.md) to wire up the MCP doc tools and live doc sources referenced above.

## Make it verify, not guess

Add whichever of these lines apply to the task. Each tells the agent to check something live instead of assuming it.

* Fetch the live spec for the exact endpoint before writing code (`https://api.yield.xyz/docs.json`, or `yield_get_api_spec` if connected); do not reuse field names from an old answer or a training-data memory of the API.
* Read `mechanics.arguments.enter` / `.exit` `.fields[]` from `GET /v1/yields/{yieldId}` instead of hardcoding arguments. See [Yield metadata](https://docs.yield.xyz/documentation/earn/core-concepts/yield-metadata.md).
* Confirm `status.enter` / `status.exit` on the yield before building an enter or exit action; a closed yield returns `412`, not a validation error.
* Iterate `transactions[]` by `stepIndex` and respect `executionPattern` (`synchronous` waits for each confirmation; `batch` bundles multiple operations into one transaction). `asynchronous` is also a declared value, but current actions return `synchronous` or `batch`. See [Actions](https://docs.yield.xyz/documentation/earn/core-concepts/actions.md#status-lifecycle).
* Submit the hash, or submit the signed transaction, exactly once per transaction: `PUT /v1/transactions/{id}/submit-hash` after you broadcast, or `POST /v1/transactions/{id}/submit` to have Yield.xyz broadcast. Never both for the same transaction.
* Poll `GET /v1/transactions/{id}` or `GET /v1/actions/{id}` to a terminal status; don't assume success right after a broadcast.
* Read balances and `pendingActions` before a manage call. See [Balances and positions](https://docs.yield.xyz/documentation/earn/core-concepts/balances-positions.md).
* Check network and provider availability for this project through discovery (`GET /v1/networks`, `GET /v1/providers`, `GET /v1/yields`) rather than assuming a network or protocol is enabled.

## Prompt patterns

### Discover yields, with pagination

```text theme={null}
Using the Earn API (https://api.yield.xyz, header x-api-key: $YIELD_API_KEY),
write a function that lists yields for network "base" and token "USDC" using
GET /v1/yields with offset/limit pagination (limit max 100). Check the live
spec for the exact query parameter names before writing the request; don't
assume from memory. Return items[] plus whether more pages remain. Remember
this only returns yields enabled for my project, not the full catalog.
```

### Enter a position

```text theme={null}
Build a TypeScript function to enter a yield position with the Earn API.

1. GET /v1/yields/base-usdc-aave-v3-lending and read mechanics.arguments.enter.fields
   to confirm what arguments are required (don't hardcode "amount" from memory).
   If this yield isn't enabled for my project, tell me instead of guessing another id.
2. POST /v1/actions/enter with { yieldId, address, arguments }. Amount is a
   human-readable string like "100", not wei.
3. Iterate the returned transactions[] in stepIndex order. Skip any already at
   a terminal status (CONFIRMED, FAILED, SKIPPED). Sign each unsignedTransaction
   exactly as returned; never modify it.
4. After broadcasting, call PUT /v1/transactions/{id}/submit-hash with the hash.
5. Poll GET /v1/actions/{id} until status is terminal.
```

### Exit a position and claim a pending action

```text theme={null}
Write a function that exits a yield position and then handles any follow-up
claim for address 0xYOUR_WALLET_ADDRESS:

1. POST /v1/actions/exit with yieldId, address, and arguments (check
   mechanics.arguments.exit.fields for what's required; some yields need
   useMaxAmount instead of amount for a full exit).
2. Process transactions[] in stepIndex order, submit-hash after each broadcast,
   poll to a terminal status.
3. After the exit settles, call POST /v1/yields/{yieldId}/balances for that
   address and look for a balance with pendingActions[].
4. For a pendingAction you want to complete, call POST /v1/actions/manage with
   action set to that pendingAction's type and passthrough copied unchanged
   from the response. Don't construct or guess a passthrough value.
```

### Portfolio balances across networks

```text theme={null}
Using POST /v1/yields/balances, write a function that takes an array of
{ address, network } (1 to 25 queries per call, yieldId optional in each) and
returns a portfolio summary grouped by balance type (active, entering,
exiting, withdrawable, claimable, locked). Read the live spec for the exact
request and response shape first. Flag any pendingActions found on a balance
instead of dropping them.
```

### Debug an API error

```text theme={null}
This call to Earn API returned an error. Here is the exact request and the
response body:

[paste the request: method, path, headers minus the key, body]
[paste the full response body, including statusCode and any validation array]

Check this status and message against the live spec or yield_troubleshoot_error
if connected, tell me what caused it, and propose a fix. Don't assume it's a
400 for bad field names without checking; a disabled or blocked yield also
returns 400, and a yield closed for entry or exit returns 412.
```

## Review before anything signs

Never sign a generated transaction without inspecting it yourself. This applies whether the transaction came from a builder plugin, a one-off prompt, or code you wrote by hand.

For generated code, check:

* Every request goes to `https://api.yield.xyz` with `x-api-key` from an environment variable; no key literal in source.
* Action arguments came from the yield's schema, not copied from another yield or from memory.
* Amounts are human-readable decimal strings, never wei.
* `transactions[]` are processed in `stepIndex` order, and nothing modifies `unsignedTransaction`.

For any transaction an agent built, before you sign:

* Inspect the decoded `to` address, amount, and network yourself; don't trust a summary the agent wrote.
* Confirm it targets the yield and action you asked for, not a different one.
* Run a small test amount first, on a network where a mistake is cheap.

The full set of non-custodial rules an agent must follow, and the exact checks to run before a `manage` action, are in [Guardrails](https://docs.yield.xyz/documentation/ai-agents/agentkit/guardrails.md).

## Anti-patterns

* Asking for "the best APY" with no network, asset, or risk scope: the agent will invent a ranking instead of querying one.
* Letting the agent pick a `yieldId` from memory instead of discovering it from your project's enabled yields.
* Asking the agent to "fix" a failed transaction by editing the returned payload. Request a new action instead; a modified `unsignedTransaction` can send funds to the wrong place.

## Next steps

> [card] [AgentKit builder](https://docs.yield.xyz/guides/ai/agentkit-builder.md)
>
> Install the plugin that applies these patterns automatically while it writes your integration.

> [card] [AI coding tools](https://docs.yield.xyz/guides/ai/cursor-setup.md)
>
> Connect your agent to the live docs, spec, and MCP doc tools these prompts rely on.

> [card] [Enter and exit flows](https://docs.yield.xyz/guides/earn/enter-exit-flows.md)
>
> Build the same flow by hand, endpoint by endpoint, to check what an agent generated.

> [card] [Guardrails](https://docs.yield.xyz/documentation/ai-agents/agentkit/guardrails.md)
>
> The non-custodial rules an agent or generated integration must follow.


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