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

# Getting Started

> Get started with the Yield.xyz API - unified access to 2,900+ yields across 80+ blockchain networks

## Overview

The Yield.xyz API provides **unified infrastructure** for yield and perpetual futures trading. Access **2,900+ yield opportunities** across **80+ blockchain networks** through a single, normalized interface.

### Yield API

Build transactions for yield interaction and retrieve relevant balance and yield data. The API consolidates detailed yield metadata for all supported staking and DeFi projects into a single interface, including:

* **Up-to-date metrics** — Token and yield-specific APY/APR rates
* **Validator metadata** — Individual validator APY, commission, voting power, staked balance
* **Supplementary metadata** — Images, addresses, validator names, provider information
* **Balance types** — Staked, unstaking, unstaked, rewards, locked, unlocking, and more

### Perps API (PerpsKit)

PerpsKit is Yield.xyz's modular infrastructure for **on-chain perpetual futures ("perps")**. It aggregates perp venues behind a normalized interface so wallets, exchanges, and fintech apps can launch perps trading with minimal engineering lift — while keeping execution **self-custodial**.

PerpsKit provides:

* A unified model for **markets**, **portfolio state**, and **trading actions**
* **Transaction construction** that returns ordered, unsigned payloads for client-side signing
* Flexible **monetization** via builder codes / partner fee logic (venue-dependent)
* Operational controls for production deployments, including **configurable geo-restrictions**

***

## Base URLs

<Tabs>
  <Tab title="Production">
    ```
    https://api.yield.xyz/v1
    ```

    Use for mainnet transactions in production environments.
  </Tab>

  <Tab title="Staging">
    ```
    https://api.staging.yield.xyz/v1
    ```

    Use for testing and development against staging environment.
  </Tab>

  <Tab title="Local Development">
    ```
    http://localhost:3000/v1
    ```

    For local development when running the API locally.
  </Tab>
</Tabs>

See [Base URLs](/api-reference/base-urls) for complete environment details.

***

## API Endpoints

### Yield API

| Endpoint                         | Description                                                         |
| -------------------------------- | ------------------------------------------------------------------- |
| `GET /v1/yields`                 | List all yield opportunities with metadata, APY, and validator info |
| `GET /v1/yields/{id}`            | Get detailed information for a specific yield                       |
| `GET /v1/yields/{id}/validators` | Get validators for a specific yield                                 |
| `POST /v1/yields/balances`       | Get aggregated balances across yields                               |
| `POST /v1/yields/{id}/balances`  | Get balances for a specific yield                                   |
| `GET /v1/networks`               | List all supported networks                                         |
| `GET /v1/providers`              | List all yield providers                                            |
| `POST /v1/actions/enter`         | Create an enter/deposit action                                      |
| `POST /v1/actions/exit`          | Create an exit/withdraw action                                      |
| `POST /v1/actions/manage`        | Create a management action (claim, restake, etc.)                   |

### Perps API

| Endpoint                  | Description                              |
| ------------------------- | ---------------------------------------- |
| `GET /v1/perps/providers` | List aggregated trading platforms        |
| `GET /v1/perps/markets`   | List available markets across all venues |
| `GET /v1/perps/positions` | Get user positions                       |
| `GET /v1/perps/orders`    | Get user orders                          |
| `POST /v1/perps/actions`  | Execute trades                           |

***

## Authentication

All requests require an API key in the `x-api-key` header:

```bash theme={null}
curl https://api.yield.xyz/v1/yields \
  -H "x-api-key: YOUR_API_KEY"
```

<Card title="Get Your API Key" icon="key" href="https://dashboard.yield.xyz/sign-up/register-interest" horizontal>
  Sign up to create your API key
</Card>

See [Authentication](/api-reference/authentication) for details.

***

## Quick Start

### 1. Get Your API Key

[Sign up](https://dashboard.yield.xyz/sign-up/register-interest) and create an API key from your dashboard.

### 2. List Yield Opportunities

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.yield.xyz/v1/yields?limit=5 \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.yield.xyz/v1/yields?limit=5', {
    headers: {
      'x-api-key': process.env.YIELD_API_KEY
    }
  });

  const { items } = await response.json();
  console.log(items);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.yield.xyz/v1/yields',
      params={'limit': 5},
      headers={'x-api-key': 'YOUR_API_KEY'}
  )

  data = response.json()
  print(data['items'])
  ```
</CodeGroup>

### 3. Get User Balances

```bash theme={null}
curl -X POST https://api.yield.xyz/v1/yields/balances \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "network": "ethereum"
    }]
  }'
```

### 4. Explore the API

<CardGroup cols={2}>
  <Card title="Discovery" icon="magnifying-glass" href="/api-reference/YieldsController_getYields">
    Find yield opportunities with up-to-date metrics and validator metadata
  </Card>

  <Card title="Actions" icon="bolt" href="/api-reference/ActionsController_enterYield">
    Create transactions for entering, exiting, and managing yields
  </Card>

  <Card title="Portfolio" icon="wallet" href="/api-reference/YieldsController_getAggregateBalances">
    Fetch and organize balance data across blockchains
  </Card>

  <Card title="Health" icon="heart-pulse" href="/api-reference/HealthController_health">
    Check API status and availability
  </Card>
</CardGroup>

***

## Supported Perps Venues

PerpsKit aggregates multiple perp venues behind a normalized interface:

| Platform    | Status      | Description                               |
| ----------- | ----------- | ----------------------------------------- |
| Hyperliquid | Live        | High-performance perps on its own L1      |
| GMX         | Live        | Decentralized perpetual exchange          |
| dYdX        | Coming soon | Decentralized spot and perpetual exchange |
| Drift       | Coming soon | Solana-based perpetual exchange           |

<Note>
  Perps venues have venue-specific behavior (supported order types, margin modes, leverage caps, funding cadence, and collateral models). PerpsKit normalizes the integration surface while preserving venue constraints in metadata.
</Note>

***

## What PerpsKit Standardizes

<CardGroup cols={2}>
  <Card title="Markets" icon="list">
    Market metadata and venue-specific constraints (order types, margin modes, leverage ranges, fees, funding)
  </Card>

  <Card title="Portfolio State" icon="wallet">
    Positions, orders, collateral, margin usage, and unrealized PnL in a consistent shape across venues
  </Card>

  <Card title="Trading Actions" icon="bolt">
    A unified action model (open/close/update leverage/stop-loss/take-profit/cancel) mapped to venue execution
  </Card>

  <Card title="Unsigned Transactions" icon="shield-check">
    Ordered, unsigned payloads you route into your signing stack (EOA, smart accounts, MPC, custody)
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about API key authentication
  </Card>

  <Card title="Base URLs" icon="link" href="/api-reference/base-urls">
    Environments, staging, and rate limits
  </Card>

  <Card title="Yield Metadata" icon="database" href="/documentation/core-concepts/discover">
    Understanding the YieldDto structure
  </Card>

  <Card title="Perps Markets" icon="chart-candlestick" href="/api-reference/perps-api/discovery/list-markets">
    Browse available perps markets
  </Card>
</CardGroup>