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

Method	CU Cost	Category
eth_blockNumber	10	Core
eth_getBalance	19	Core
eth_call	26	Core
eth_getTransactionReceipt	15	Core
getTokenBalances	50	Enhanced
getTokenMetadata	50	Enhanced
getAssetTransfers	150	Enhanced
getNftsForOwner	50	NFT
getNftMetadataBatch	50	NFT
getContractMetadata	50	NFT

Plan Limits

Plan	CU/sec	Monthly CU	Price
Free	330	300M	$0
Growth	660	1.2B	$49/mo
Scale	Custom	Custom	Custom

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

Failure	Response
Limiter queue grows beyond the service threshold	Shed noncritical work, alert the operator, and preserve interactive request fairness.
429 persists after bounded retries	Surface unavailable state and defer work instead of retrying indefinitely.
Batch request is partially unsuccessful	Keep valid results, retry eligible failures only, and report unavailable items explicitly.
Account limit changes	Reconfigure from verified account information and rerun the capacity check before production use.

Resources

• Alchemy Rate Limits
• Alchemy Compute Units
• Bottleneck npm

Next Steps

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