Authentication

Authenticate your API requests using API keys

Overview

All Yield.xyz API requests require authentication using an API key. API keys are passed in the x-api-key header.

Get Your API Key

Sign up to create your API key

---

API Key Format

API keys follow this format:

1a2b3c4d5e6f7g8h9i0j...  // Production key
9z8y7x6w5v4u3t2s1r0q...  // Test key

Test keys only work with testnets. Production keys work with mainnets.

---

Making Authenticated Requests

Include your API key in the x-api-key header:

cURL

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

---

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Common causes:

• API key is missing from the header
• API key is invalid or expired
• API key has been revoked
• Wrong header name (use x-api-key, not X-API-KEY or Authorization)

403 Forbidden

API key is valid but lacks required permissions:

{
  "message": "Access denied from US (US-CA)",
  "error": "Forbidden",
  "statusCode": 403
}

Common causes:

• Geoblocking restrictions
• Read-only key used for write operations
• API key disabled in dashboard

429 Rate Limited

Too many requests:

{
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "statusCode": 429,
  "retryAfter": 30
}

Response headers:

x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1698765432
retry-after: 30

---

Best Practices

Store keys securely

Never commit API keys to version control. Use environment variables:

.env

YIELD_API_KEY=abc123...

Use backend-only

Make API calls from your backend, not client-side JavaScript:

// ❌ Bad - exposes API key in browser
const apiKey = 'abc123...';

// ✅ Good - API key stays on server
const apiKey = process.env.YIELD_API_KEY;

Separate keys per environment

Use different API keys for development, staging, and production:

YIELD_API_KEY_DEV=test_...
YIELD_API_KEY_STAGING=test_...
YIELD_API_KEY_PROD=live_...

Rotate regularly

Generate new keys periodically and revoke old ones in your dashboard.

Monitor usage

Track API usage in your dashboard to detect anomalies or unauthorized access.

---

Rate Limits

Rate limits vary by plan:

Plan	Requests/Second	Requests/Month
Free	10	100,000
Starter	50	1,000,000
Pro	200	10,000,000
Enterprise	Custom	Unlimited

View Rate Limits

Learn more about rate limits and plans

---

Environments

Production

https://api.yield.xyz

Use production keys (live_...) for mainnet transactions.

Staging

https://api.staging.yield.xyz

Use test keys (test_...) for testing against staging environment.

---

Testing Authentication

Verify your API key works:

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

Success response:

{
  "items": [...],
  "total": 150,
  "offset": 0,
  "limit": 1
}

---

Next Steps

Create API Key

Step-by-step guide to creating your first API key

List Yields

Make your first API call

Project Setup

Complete integration guide