Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/alchemy-rate-limits/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill alchemy-rate-limits. Copyright stays with the author (MIT).

Alchemy Rate Limits

Overview

Alchemy uses Compute Units (CU) to measure API usage. Different methods cost different CU amounts. Rate limits are per-second, and exceeding them returns 429 errors.

Compute Unit Costs

Plan Limits

Prerequisites

• Confirm actual plan limits and method costs in the organization’s current account; the reference tables are illustrative and commercial terms change.
• Instrument aggregate request count, latency, queue depth, retry outcome, and dropped-work signals without logging API keys or user-sensitive payloads.
• Define a bounded retry budget and an application-level response for requests that cannot be served within the budget.

Instructions

Step 1: CU-Aware Request Throttler

// src/alchemy/throttler.ts
import Bottleneck from 'bottleneck';

const CU_COSTS: Record<string, number> = {
  'eth_blockNumber': 10,
  'eth_getBalance': 19,
  'eth_call': 26,
  'getTokenBalances': 50,
  'getAssetTransfers': 150,
  'getNftsForOwner': 50,
};

// Free tier: 330 CU/sec = ~16 getBalance calls/sec
const limiter = new Bottleneck({
  reservoir: 330,                    // CU budget per interval
  reservoirRefreshInterval: 1000,    // Refresh every second
  reservoirRefreshAmount: 330,       // Reset to max CU/sec
  maxConcurrent: 10,                 // Max parallel requests
  minTime: 50,                       // Min 50ms between requests
});

limiter.on('depleted', () => {
  console.warn('CU budget depleted — queueing requests');
});

async function throttledAlchemyCall<T>(
  method: string,
  operation: () => Promise<T>,
): Promise<T> {
  const cost = CU_COSTS[method] || 26; // Default to eth_call cost
  return limiter.schedule({ weight: cost }, operation);
}

export { throttledAlchemyCall, limiter };

Step 2: Batch Optimizer

// src/alchemy/batch-optimizer.ts
import { Alchemy } from 'alchemy-sdk';

// Instead of N individual calls, batch when possible
async function batchGetBalances(
  alchemy: Alchemy,
  addresses: string[],
): Promise<Map<string, string>> {
  const results = new Map<string, string>();

  // Process in chunks to stay under rate limit
  const CHUNK_SIZE = 10;
  for (let i = 0; i < addresses.length; i += CHUNK_SIZE) {
    const chunk = addresses.slice(i, i + CHUNK_SIZE);
    const balances = await Promise.all(
      chunk.map(addr => alchemy.core.getBalance(addr))
    );
    chunk.forEach((addr, idx) => {
      results.set(addr, (parseInt(balances[idx].toString()) / 1e18).toFixed(6));
    });

    // Pause between chunks to stay under CU limit
    if (i + CHUNK_SIZE < addresses.length) {
      await new Promise(r => setTimeout(r, 200));
    }
  }

  return results;
}

export { batchGetBalances };

Step 3: 429 Retry Handler

// src/alchemy/retry.ts
async function withAlchemyRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 5,
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err: any) {
      if (err.response?.status !== 429 || attempt === maxRetries) throw err;

      const retryAfter = parseInt(err.response.headers?.['retry-after'] || '1');
      const jitter = Math.random() * 500;
      const delay = retryAfter * 1000 + jitter;

      console.log(`Rate limited — retry ${attempt}/${maxRetries} in ${delay.toFixed(0)}ms`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Output

• CU-aware Bottleneck throttler matching plan limits
• Batch optimizer reducing total CU consumption
• 429 retry handler with Retry-After header support

Examples

In a test environment, configure the limiter below the account’s documented per-second CU allowance and issue enough public-chain balance queries to create a queue. Confirm that work executes in order, a simulated 429 honors Retry-After, and aggregate telemetry shows the queue depth and final outcome. When the retry budget is exhausted, return a controlled unavailable result and let the caller decide whether to retry later; do not spin indefinitely or hide the failed request. If observed limits differ from the configuration, pause the load test and update the limiter from the verified account data.

Error Handling

Resources

• Alchemy Rate Limits
• Alchemy Compute Units
• Bottleneck npm

Next Steps

For security best practices, see alchemy-security-basics.