Usage Constraints

API usage constraints, limits, and best practices

Overview

Beyond rate limits, there are additional usage constraints to be aware of when integrating with Yield.xyz.

---

Request Limits

Constraint	Value
Max request body size	1 MB
Max URL length	8 KB
Max addresses per balance request	100
Max yield IDs per request	100

---

Response Limits

Constraint	Value
Max yields per page	100
Max validators per page	1,000
Max transactions per action	10

---

Timeout Limits

Operation	Timeout
API request	30 seconds
Webhook delivery	15 seconds
Transaction construction	30 seconds

---

Concurrent Connections

Plan	Max Connections
Standard	100
Pro	500
Enterprise	Custom

---

OAV Deployment Limits

Plan	OAV Deployments Included
Standard	10
Pro	25
Enterprise	Unlimited

Need additional OAV deployments beyond your plan’s allocation? Additional deployments are qualified based on your expected TVL and volume. Contact our team to discuss your requirements.

Request Additional OAVs

Contact us to discuss additional OAV deployments

---

Data Retention

Data Type	Retention
Transaction history	Indefinite
Action logs	90 days
Webhook delivery logs	30 days
Balance snapshots	Per configuration

---

Geoblocking Constraints

Certain jurisdictions are restricted by default or optionally. See Geoblocking for details.

---

Best Practices

Paginate large requests

Use offset and limit parameters to paginate through large result sets:

async function getAllYields() {
  const yields = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const response = await fetch(
      `https://api.yield.xyz/v1/yields?offset=${offset}&limit=${limit}`
    );
    const data = await response.json();
    yields.push(...data.items);
    
    if (data.items.length < limit) break;
    offset += limit;
  }
  
  return yields;
}

Batch address lookups

Use the aggregate balance endpoint instead of individual calls:

// Instead of:
for (const address of addresses) {
  await fetch(`/yields/${yieldId}/balances?address=${address}`);
}

// Use:
await fetch('/yields/balances', {
  method: 'POST',
  body: JSON.stringify({
    addresses: addresses.slice(0, 100), // Max 100 per request
    yieldIds: [yieldId],
  }),
});

Handle timeouts gracefully

Implement timeout handling for long-running requests:

async function fetchWithTimeout(url: string, timeoutMs = 30000) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
  
  try {
    const response = await fetch(url, { signal: controller.signal });
    return response;
  } catch (error) {
    if (error.name === 'AbortError') {
      throw new Error('Request timed out');
    }
    throw error;
  } finally {
    clearTimeout(timeout);
  }
}

---

Upgrade for Higher Limits

Upgrade to Pro

Higher connection limits and more OAV deployments

Enterprise Inquiry

Custom limits and dedicated infrastructure

---

Next Steps

Rate Limits

API rate limit details

Plans & Pricing

Compare all plan features