Rate Limits

Vision.meme implements rate limits to ensure fair usage and system stability. This guide explains the limits, how to handle them, and best practices.

---

Rate Limit Tiers

Different endpoints have different rate limits based on their resource intensity.

General API Endpoints

Most read operations have generous limits:

Category	Endpoints	Limit
General	GET /tokens GET /tokens/:mintAddress GET /featured	100 requests per 15 minutes
Authentication	POST /auth/challenge POST /auth/verify	20 requests per minute

Resource-Intensive Endpoints

Operations that create resources or upload data have stricter limits:

Category	Endpoints	Limit
Token Creation	POST /tokens/create-unsigned POST /tokens/submit	5 requests per hour
File Upload	POST /tokens/upload-image	20 requests per hour
Distribution Updates	PATCH /distribution/:tokenId/settings	10 requests per hour
Featured Tokens	POST /featured/create-unsigned	5 requests per hour
DEX Operations	POST /dex/raydium/cpmm/create-unsigned POST /launchpad/create-unsigned	10 requests per hour

---

Rate Limit Headers

Every API response includes rate limit information in the headers:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1704124800
X-RateLimit-Window: 900

Header Descriptions

Header	Description	Example
X-RateLimit-Limit	Maximum requests allowed in window	100
X-RateLimit-Remaining	Requests remaining in current window	87
X-RateLimit-Reset	Unix timestamp when limit resets	1704124800
X-RateLimit-Window	Window size in seconds	900 (15 minutes)

Reading Headers

javascript

const response = await fetch('https://api.vision.meme/tokens');

const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const reset = parseInt(response.headers.get('X-RateLimit-Reset'));

console.log(`${remaining} of ${limit} requests remaining`);
console.log(`Resets at ${new Date(reset * 1000).toLocaleString()}`);

---

Rate Limit Exceeded (429)

When you exceed a rate limit, you'll receive a 429 Too Many Requests response:

Response:

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 300,
  "message": "Too many requests. Please try again in 300 seconds."
}

Response Headers:

http

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704124800
Retry-After: 300
Content-Type: application/json

Retry-After Header

The Retry-After header tells you how many seconds to wait before retrying:

javascript

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After'));
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  
  // Wait and retry
  await sleep(retryAfter * 1000);
  const retryResponse = await fetch(url, options);
}

---

Handling Rate Limits

Check Before Request

Monitor your rate limit usage and pause when approaching the limit:

javascript

class RateLimitedAPI {
  constructor() {
    this.limit = 100;
    this.remaining = 100;
    this.reset = Date.now();
  }
  
  updateFromHeaders(response) {
    this.limit = parseInt(response.headers.get('X-RateLimit-Limit')) || this.limit;
    this.remaining = parseInt(response.headers.get('X-RateLimit-Remaining')) || this.remaining;
    this.reset = parseInt(response.headers.get('X-RateLimit-Reset')) * 1000 || this.reset;
  }
  
  async makeRequest(url, options = {}) {
    // Check if we're close to limit
    if (this.remaining < 5) {
      const waitTime = this.reset - Date.now();
      if (waitTime > 0) {
        console.log(`Approaching rate limit. Waiting ${waitTime}ms...`);
        await sleep(waitTime);
      }
    }
    
    const response = await fetch(url, options);
    this.updateFromHeaders(response);
    
    return response;
  }
}

// Usage
const api = new RateLimitedAPI();
const response = await api.makeRequest('https://api.vision.meme/tokens');

Exponential Backoff

Implement exponential backoff for retries:

javascript

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
        const backoff = Math.min(retryAfter * Math.pow(2, i), 300); // Max 5 minutes
        
        console.log(`Rate limited. Retrying in ${backoff} seconds...`);
        await sleep(backoff * 1000);
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * Math.pow(2, i));
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Request Queue

Implement a queue system to prevent exceeding limits:

javascript

class RequestQueue {
  constructor(requestsPerWindow, windowMs) {
    this.requestsPerWindow = requestsPerWindow;
    this.windowMs = windowMs;
    this.queue = [];
    this.timestamps = [];
  }
  
  async enqueue(fn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ fn, resolve, reject });
      this.processQueue();
    });
  }
  
  async processQueue() {
    if (this.processing) return;
    this.processing = true;
    
    while (this.queue.length > 0) {
      // Remove timestamps outside current window
      const now = Date.now();
      this.timestamps = this.timestamps.filter(t => now - t < this.windowMs);
      
      // Check if we can make a request
      if (this.timestamps.length >= this.requestsPerWindow) {
        const oldestRequest = this.timestamps[0];
        const waitTime = this.windowMs - (now - oldestRequest);
        
        console.log(`Rate limit reached. Waiting ${waitTime}ms...`);
        await sleep(waitTime);
        continue;
      }
      
      // Process next request
      const { fn, resolve, reject } = this.queue.shift();
      this.timestamps.push(Date.now());
      
      try {
        const result = await fn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
    }
    
    this.processing = false;
  }
}

// Usage
const queue = new RequestQueue(100, 15 * 60 * 1000); // 100 per 15 minutes

// Queue requests
const result1 = await queue.enqueue(() => 
  fetch('https://api.vision.meme/tokens/mint1').then(r => r.json())
);

const result2 = await queue.enqueue(() => 
  fetch('https://api.vision.meme/tokens/mint2').then(r => r.json())
);

---

Best Practices

1. Cache Responses

Cache responses to reduce API calls:

javascript

class CachedAPI {
  constructor(cacheTimeMs = 60000) { // 1 minute default
    this.cache = new Map();
    this.cacheTimeMs = cacheTimeMs;
  }
  
  getCacheKey(url, options) {
    return `${url}:${JSON.stringify(options)}`;
  }
  
  async fetch(url, options = {}) {
    const key = this.getCacheKey(url, options);
    const cached = this.cache.get(key);
    
    if (cached && Date.now() - cached.timestamp < this.cacheTimeMs) {
      console.log('Returning cached response');
      return cached.data;
    }
    
    const response = await fetch(url, options);
    const data = await response.json();
    
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
    
    return data;
  }
}

// Usage
const api = new CachedAPI(5 * 60 * 1000); // 5 minute cache
const tokens = await api.fetch('https://api.vision.meme/tokens');

2. Batch Requests

Where possible, use batch operations instead of individual requests:

javascript

// ❌ Bad: Multiple individual requests
for (const mintAddress of mintAddresses) {
  const token = await fetch(`https://api.vision.meme/tokens/${mintAddress}`);
  // Process token
}

// ✅ Good: Single request with pagination
const tokens = await fetch('https://api.vision.meme/tokens?limit=100');
// Process all tokens

3. Monitor Usage

Track your API usage to stay within limits:

javascript

class UsageMonitor {
  constructor() {
    this.requests = {
      general: { count: 0, limit: 100, window: 15 * 60 * 1000 },
      creation: { count: 0, limit: 5, window: 60 * 60 * 1000 },
      upload: { count: 0, limit: 20, window: 60 * 60 * 1000 }
    };
  }
  
  canMakeRequest(category) {
    const usage = this.requests[category];
    return usage.count < usage.limit;
  }
  
  recordRequest(category) {
    this.requests[category].count++;
    
    // Reset after window
    setTimeout(() => {
      this.requests[category].count = 0;
    }, this.requests[category].window);
  }
  
  getUsage() {
    return Object.entries(this.requests).map(([category, usage]) => ({
      category,
      used: usage.count,
      limit: usage.limit,
      percentage: (usage.count / usage.limit * 100).toFixed(1)
    }));
  }
}

// Usage
const monitor = new UsageMonitor();

if (monitor.canMakeRequest('creation')) {
  await createToken();
  monitor.recordRequest('creation');
} else {
  console.log('Creation limit reached');
}

console.table(monitor.getUsage());

4. Use Webhooks

For real-time updates, consider using webhooks instead of polling:

javascript

// ❌ Bad: Polling for updates
setInterval(async () => {
  const status = await fetch(`https://api.vision.meme/launchpad/${mint}/status`);
  // Check status
}, 5000); // Every 5 seconds = 720 requests per hour!

// ✅ Better: Reasonable polling interval
setInterval(async () => {
  const status = await fetch(`https://api.vision.meme/launchpad/${mint}/status`);
  // Check status
}, 60000); // Every minute = 60 requests per hour

// ✅ Best: Use webhooks (if available) or WebSocket

---

Rate Limit by Use Case

Building a Dashboard

Typical Usage:

• Initial load: 3-5 requests

• Updates: 1 request per minute

• Total: ~65 requests per hour

Strategy:

• Cache token data for 30-60 seconds

• Use pagination for large lists

• Update only visible data

Example:

javascript

// Load dashboard
const [tokens, featured, user] = await Promise.all([
  fetch('https://api.vision.meme/tokens/me'),
  fetch('https://api.vision.meme/featured'),
  fetch('https://api.vision.meme/user')
]);

// Update every minute
setInterval(async () => {
  const updates = await fetch('https://api.vision.meme/tokens/me');
  updateUI(updates);
}, 60000);

Token Creation Bot

Typical Usage:

• Create 1-5 tokens per hour

• Upload images: 1-5 per hour

• Check status: ~10 per hour

• Total: ~20 requests per hour

Strategy:

• Stay within 5 creations per hour limit

• Queue creation requests

• Add delays between operations

Example:

javascript

async function createTokensSequentially(tokensData) {
  const results = [];
  
  for (const data of tokensData) {
    try {
      const token = await createToken(data);
      results.push({ success: true, token });
      
      // Wait 12 minutes between creations (5 per hour)
      await sleep(12 * 60 * 1000);
    } catch (error) {
      results.push({ success: false, error });
    }
  }
  
  return results;
}

Analytics Service

Typical Usage:

• Fetch token data: 50-100 per hour

• Fetch burn stats: 20-30 per hour

• Fetch featured: 10-20 per hour

• Total: ~100-150 requests per hour

Strategy:

• Heavy caching (5-15 minutes)

• Batch operations

• Use pagination efficiently

Example:

javascript

class TokenAnalytics {
  constructor() {
    this.cache = new Map();
    this.cacheTime = 10 * 60 * 1000; // 10 minutes
  }
  
  async getTokenData(mintAddress) {
    const cached = this.cache.get(mintAddress);
    if (cached && Date.now() - cached.timestamp < this.cacheTime) {
      return cached.data;
    }
    
    const data = await fetch(`https://api.vision.meme/tokens/${mintAddress}`);
    this.cache.set(mintAddress, { data, timestamp: Date.now() });
    
    return data;
  }
  
  async analyzeMultipleTokens(mintAddresses) {
    // Process in batches to respect rate limits
    const batchSize = 10;
    const results = [];
    
    for (let i = 0; i < mintAddresses.length; i += batchSize) {
      const batch = mintAddresses.slice(i, i + batchSize);
      const batchResults = await Promise.all(
        batch.map(mint => this.getTokenData(mint))
      );
      results.push(...batchResults);
      
      // Small delay between batches
      if (i + batchSize < mintAddresses.length) {
        await sleep(1000);
      }
    }
    
    return results;
  }
}

---

Increasing Rate Limits

For applications requiring higher rate limits:

Enterprise Plans

Contact us for custom rate limits:

• Higher limits for all endpoints

• Dedicated support for integration

• Custom SLAs available

• Priority access to new features

Contact: [email protected]

Optimization First

Before requesting higher limits, ensure you're optimizing:

1. Caching - Are you caching responses?

2. Batching - Can you batch operations?

3. Polling - Can you reduce polling frequency?

4. Webhooks - Can you use webhooks instead?

---

Rate Limit FAQs

Do rate limits reset at a specific time?

No, rate limits are based on sliding windows. Each request starts a new window.

Example:

• Make request at 12:00 PM

• Limit resets at 12:15 PM (for 15-minute window)

• Not tied to clock hours

Are rate limits per API key or IP address?

Rate limits are per authenticated user (JWT token) for authenticated endpoints, and per IP address for public endpoints.

What happens if I hit the limit?

You receive a 429 Too Many Requests response. Wait for the time specified in Retry-After header.

Can I check my current usage?

Yes, check the X-RateLimit-Remaining header on any response.

Do failed requests count toward the limit?

Yes, all requests (successful or failed) count toward rate limits, except for 500 errors.

---

Next Steps

• Error Handling - Handle rate limit errors properly

• Code Examples - See rate limiting in practice

• Authentication - Understand auth rate limits

---

Need Higher Limits?

📧 Contact [email protected] to discuss custom rate limits for your application.

---

© 2025 Vision.meme. All rights reserved.