Quickstart

Integrate Yield.xyz end-to-end: access → enable yields → discover → actions → sign → track balances

This quickstart walks you through the end-to-end Yield.xyz integration loop:

1. Get an API key
2. Enable yields for your project
3. Discover an opportunity
4. Request an action (enter/exit/manage)
5. Sign + submit the ordered transactions in your stack
6. Track balances and follow-up actions

---

Prerequisites

• A Yield.xyz dashboard account and a project/environment
• A signing + broadcast path (EOA wallet, smart account, MPC, or institutional custody)
• A way to store secrets securely (API key, environment config)

---

End-to-end flow

1. Get access + create an API key

   Create an API key for your environment in the dashboard.

   • Use a separate key per environment (sandbox/staging/production).
   • Treat API keys as secrets (never ship them to frontend clients).

   See API keys & authentication for details.

2. Enable yields for your project

   Yield availability is project-scoped. In the dashboard, enable the yield categories and individual opportunities you want to expose (staking, lending, vaults, etc.). Once saved, enabled yields become available via your API key.

   Learn more about Projects & environments.

3. Discover opportunities

   Use the discovery endpoint to list yields and filter by network, input token, provider, or yield type. This powers your “yield feed” and selection UX.

   See Discover opportunities for filtering patterns.

4. Inspect a specific yield (schema-first)

   Fetch yield metadata for the chosen yieldId to understand:

   • Supported intents (enter/exit/manage)
   • Required arguments and their schemas
   • Mechanics (validator selection, cooldown/withdraw windows, etc.)
5. Request an action (enter/exit/manage)

   Call the appropriate Actions endpoint with:

   • yieldId
   • address (the user/wallet address)
   • arguments (schema-compliant)

   The response is an Action containing one or more ordered transaction steps.

   See Actions for the full action model.

6. Sign + submit the returned transactions

   Execute transactions in the order returned. Each step includes an unsignedTransaction payload you can route to:

   • EOA signing (ethers / web3)
   • Smart accounts
   • MPC / institutional custody (e.g., Fireblocks)

   For higher assurance, validate unsigned payloads with Shield before presenting them for signing.

7. Track balances and pending actions

   After confirmation, fetch balances to power portfolio UX and operational reporting. Balances are lifecycle-aware (active, exiting, claimable, etc.) and may include pendingActions (claim, restake, redelegate, withdraw).

   See Balances & positions for lifecycle states.

---

Minimal API walkthrough (with examples)

Native staking (validator-based)

This example shows a typical validator flow with schema-driven arguments and an ordered transaction sequence.

Always fetch yield metadata first — it defines the required fields (e.g., validatorAddress) and lifecycle constraints (cooldown/withdraw windows).

Step 1: Get yield metadata

Get yield metadata

curl --request GET \
  --url https://api.yield.xyz/v1/yields/ethereum-matic-native-staking \
  --header 'accept: application/json' \
  --header 'x-api-key: <API_KEY>'

Step 2: Request enter action

Enter action

curl --request POST \
  --url https://api.yield.xyz/v1/actions/enter \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --data '{
    "yieldId": "ethereum-matic-native-staking",
    "address": "0xYOUR_USER_ADDRESS",
    "arguments": {
      "amount": "2",
      "validatorAddress": "0xVALIDATOR_ADDRESS"
    }
  }'

The response includes an ordered list of transactions:

• Step 0: approval (if required)
• Step 1: stake / delegate

Execute steps in order. Skipping steps can cause failures (e.g., missing approvals).

Step 3: Fetch balances after confirmation

Get balances

curl --request POST \
  --url https://api.yield.xyz/v1/yields/ethereum-matic-native-staking/balances \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --data '{
    "address": "0xYOUR_USER_ADDRESS"
  }'

ERC-4626 vault (multi-step)

This example shows a vault deposit/withdraw flow where the API returns multiple ordered transactions (e.g., approval → supply, and later withdraw → unwrap).

Step 1: Get yield metadata

Get yield metadata

curl --request GET \
  --url https://api.yield.xyz/v1/yields/ethereum-weth-speth-0xfe6eb3b609a7c8352a241f7f3a21cea4e9209b8f-4626-vault \
  --header 'accept: application/json' \
  --header 'x-api-key: <API_KEY>'

Step 2: Request enter action

Enter action

curl --request POST \
  --url https://api.yield.xyz/v1/actions/enter \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --data '{
    "yieldId": "ethereum-weth-speth-0xfe6eb3b609a7c8352a241f7f3a21cea4e9209b8f-4626-vault",
    "address": "0xYOUR_USER_ADDRESS",
    "arguments": { "amount": "0.0001" }
  }'

Expect a multi-step response (example patterns):

• approval → supply (deposit)
• withdraw → unwrap (exit, if the vault returns a wrapped asset)

Your UI can render these steps clearly (“Approve”, “Deposit”, “Withdraw”, “Unwrap”) using the transaction titles/types returned by the API.

Step 3: Fetch balances after confirmation

Get balances

curl --request POST \
  --url https://api.yield.xyz/v1/yields/ethereum-weth-speth-0xfe6eb3b609a7c8352a241f7f3a21cea4e9209b8f-4626-vault/balances \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --data '{
    "address": "0xYOUR_USER_ADDRESS"
  }'

---

Signing & submission patterns

Wallet / EOA signing

Use your standard chain SDK (e.g., ethers, web3, cosmjs, solana/web3.js) to sign and broadcast the returned unsignedTransaction object.

The API returns transactions that are already constructed — you should not re-encode calldata client-side.

Example with ethers.js

import { ethers } from 'ethers';

async function signAndSubmit(unsignedTransaction, signer) {
  const tx = await signer.sendTransaction({
    to: unsignedTransaction.to,
    data: unsignedTransaction.data,
    value: unsignedTransaction.value || '0x0',
    gasLimit: unsignedTransaction.gasLimit,
  });
  return tx.hash;
}

Institutional custody (e.g., Fireblocks)

Map each returned transaction step into your custody provider’s “contract call / raw transaction” format:

• to (target contract)
• data (calldata)
• value (if applicable)
• network/chain context

Custody systems often require deterministic review. Use Shield validation before signing in production/institutional flows.

See Custody signing flows for institutional patterns.

---

Tracking lifecycle + follow-up actions

Balances are lifecycle-aware and may include pending actions (e.g., claim, restake, redelegate, withdraw). Use balances to:

• Show active vs exiting vs claimable states
• Drive UX buttons (“Claim”, “Withdraw”, “Redelegate”)
• Call manage with the provided passthrough (when applicable)

If you need “manage” actions (claim/restake/redelegate), always start from balances — the response may include a required passthrough blob and an argument schema for the follow-up.

Example: handling pending actions

const balances = await fetchBalances(yieldId, address);

for (const balance of balances) {
  if (balance.pendingActions?.length > 0) {
    for (const action of balance.pendingActions) {
      console.log(`Available action: ${action.type}`);
      // Use action.passthrough when calling /actions/manage
    }
  }
}

---

Production readiness checklist

Before going live, ensure you have addressed:

Environment separation

Use separate API keys for sandbox, staging, and production environments. Never share keys across environments.

Rate limit handling

Implement exponential backoff for 429 responses. See Rate limits for tier-specific limits.

Transaction ordering

Enforce transaction ordering in your signing flow. Multi-step actions must be executed sequentially.

Observability

Log request IDs, action IDs, transaction hashes, and timestamps for debugging and audit trails.

Shield validation

Enable Shield validation for institutional flows to verify unsigned payloads before signing.

Incident runbooks

Prepare internal runbooks for incident response, protocol disablement, and error handling.

---

Integration complexity & timeline

Yield.xyz is designed for rapid integration with minimal engineering overhead.

Integration Type	Effort Level	Estimated Timeline	Notes
Widget (no-code)	Low	1–2 days	Embed the Yield.xyz Widget. Handles all yield flows and signing automatically.
API Integration (EVM networks)	Medium	3–7 days	Straightforward setup using /yields, /actions, and /balances. Works seamlessly with most wallet SDKs and custody solutions.
API Integration (non-EVM networks)	Medium–High	7–14 days	Requires additional setup for signing flows (e.g., Solana, Cosmos, Tron).

Most partners go live within one week for EVM-based integrations, extending slightly for multi-network coverage.

---

Where to go next

Core Concepts

Understand Actions, Balances, and Fees

API Reference

Explore endpoint specs and schemas

Coverage

Browse supported networks and yields

Shield & Security

Learn about transaction validation

Integration Patterns

See detailed flow guides

Recipes

Copy-paste code examples

---

Need help?

• Email: [e-mail]
• Partner support: use your dedicated Slack/Telegram channel (if provisioned)

For common issues, see the FAQs.