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

Production

https://api.yield.xyz/v1

Use for mainnet transactions in production environments.

Staging

https://api.staging.yield.xyz/v1

Use for testing and development against staging environment.

Local Development

http://localhost:3000/v1

For local development when running the API locally.

See 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:

curl https://api.yield.xyz/v1/yields \
  -H "x-api-key: YOUR_API_KEY"

Get Your API Key

Sign up to create your API key

See Authentication for details.

---

Quick Start

1. Get Your API Key

Sign up and create an API key from your dashboard.

2. List Yield Opportunities

cURL

curl https://api.yield.xyz/v1/yields?limit=5 \
  -H "x-api-key: YOUR_API_KEY"

3. Get User Balances

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

Discovery

Find yield opportunities with up-to-date metrics and validator metadata

Actions

Create transactions for entering, exiting, and managing yields

Portfolio

Fetch and organize balance data across blockchains

Health

Check API status and availability

---

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

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.

---

What PerpsKit Standardizes

Markets

Market metadata and venue-specific constraints (order types, margin modes, leverage ranges, fees, funding)

Portfolio State

Positions, orders, collateral, margin usage, and unrealized PnL in a consistent shape across venues

Trading Actions

A unified action model (open/close/update leverage/stop-loss/take-profit/cancel) mapped to venue execution

Unsigned Transactions

Ordered, unsigned payloads you route into your signing stack (EOA, smart accounts, MPC, custody)

---

Next Steps

Authentication

Learn about API key authentication

Base URLs

Environments, staging, and rate limits

Yield Metadata

Understanding the YieldDto structure

Perps Markets

Browse available perps markets