> ## 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.

# 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

<Steps>
  <Step title="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](/documentation/core-concepts/api-keys-authentication) for details.
  </Step>

  <Step title="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](/documentation/core-concepts/projects-environments).
  </Step>

  <Step title="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](/documentation/build-with-api/discover-opportunities) for filtering patterns.
  </Step>

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

  <Step title="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](/documentation/core-concepts/actions) for the full action model.
  </Step>

  <Step title="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)

    <Info>
      For higher assurance, validate unsigned payloads with [Shield](/documentation/shield-security/shield) before presenting them for signing.
    </Info>
  </Step>

  <Step title="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](/documentation/core-concepts/balances-positions) for lifecycle states.
  </Step>
</Steps>

***

## Minimal API walkthrough (with examples)

<Tabs>
  <Tab title="Native staking (validator-based)">
    This example shows a typical validator flow with schema-driven arguments and an ordered transaction sequence.

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

    **Step 1: Get yield metadata**

    <CodeGroup>
      ```bash Get yield metadata theme={null}
      curl --request GET \
        --url https://api.yield.xyz/v1/yields/ethereum-matic-native-staking \
        --header 'accept: application/json' \
        --header 'x-api-key: <API_KEY>'
      ```
    </CodeGroup>

    **Step 2: Request enter action**

    <CodeGroup>
      ```bash Enter action theme={null}
      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"
          }
        }'
      ```
    </CodeGroup>

    The response includes an ordered list of transactions:

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

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

    **Step 3: Fetch balances after confirmation**

    <CodeGroup>
      ```bash Get balances theme={null}
      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"
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="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**

    <CodeGroup>
      ```bash Get yield metadata theme={null}
      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>'
      ```
    </CodeGroup>

    **Step 2: Request enter action**

    <CodeGroup>
      ```bash Enter action theme={null}
      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" }
        }'
      ```
    </CodeGroup>

    Expect a multi-step response (example patterns):

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

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

    **Step 3: Fetch balances after confirmation**

    <CodeGroup>
      ```bash Get balances theme={null}
      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"
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

## Signing & submission patterns

<Tabs>
  <Tab title="Wallet / EOA signing">
    Use your standard chain SDK (e.g., ethers, web3, cosmjs, solana/web3.js) to sign and broadcast the returned `unsignedTransaction` object.

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

    ```typescript Example with ethers.js theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="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

    <Warning>
      Custody systems often require deterministic review. Use [Shield](/documentation/shield-security/shield) validation before signing in production/institutional flows.
    </Warning>

    See [Custody signing flows](/guides/enterprise/custody-signing-flows) for institutional patterns.
  </Tab>
</Tabs>

***

## 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)

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

```typescript Example: handling pending actions theme={null}
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:

<AccordionGroup>
  <Accordion title="Environment separation">
    Use separate API keys for sandbox, staging, and production environments. Never share keys across environments.
  </Accordion>

  <Accordion title="Rate limit handling">
    Implement exponential backoff for 429 responses. See [Rate limits](/documentation/plans-limits/rate-limits) for tier-specific limits.
  </Accordion>

  <Accordion title="Transaction ordering">
    Enforce transaction ordering in your signing flow. Multi-step actions must be executed sequentially.
  </Accordion>

  <Accordion title="Observability">
    Log request IDs, action IDs, transaction hashes, and timestamps for debugging and audit trails.
  </Accordion>

  <Accordion title="Shield validation">
    Enable [Shield](/documentation/shield-security/shield) validation for institutional flows to verify unsigned payloads before signing.
  </Accordion>

  <Accordion title="Incident runbooks">
    Prepare internal runbooks for incident response, protocol disablement, and error handling.
  </Accordion>
</AccordionGroup>

***

## 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).                                                   |

<Info>
  Most partners go live within **one week** for EVM-based integrations, extending slightly for multi-network coverage.
</Info>

***

## Where to go next

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/documentation/core-concepts/actions">
    Understand Actions, Balances, and Fees
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/getting-started">
    Explore endpoint specs and schemas
  </Card>

  <Card title="Coverage" icon="globe" href="/documentation/coverage/supported-networks">
    Browse supported networks and yields
  </Card>

  <Card title="Shield & Security" icon="shield" href="/documentation/shield-security/shield">
    Learn about transaction validation
  </Card>

  <Card title="Integration Patterns" icon="diagram-project" href="/guides/integration-patterns/enter-exit-flows">
    See detailed flow guides
  </Card>

  <Card title="Recipes" icon="utensils" href="/guides/recipes">
    Copy-paste code examples
  </Card>
</CardGroup>

***

## Need help?

* Email: **[hello@yield.xyz](mailto:hello@yield.xyz)**
* Partner support: use your dedicated Slack/Telegram channel (if provisioned)

For common issues, see the [FAQs](/documentation/faqs).