Alchemy CI Integration

Overview

CI/CD pipeline for Alchemy-powered dApps with Hardhat mainnet fork testing, Sepolia deployment, and contract verification.

Prerequisites

• A repository secret store containing a least-privilege Alchemy test key and, where deployment is authorized, a testnet-only deployer credential.
• A pinned Hardhat, Solidity, and fork block configuration that has passed locally with synthetic or public-chain fixtures.
• Branch protection that limits testnet deployment to an approved protected branch and preserves the workflow run as a release receipt.

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/web3-ci.yml
name: Web3 CI

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - name: Run Hardhat tests with Alchemy fork
        env:
          ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
        run: npx hardhat test
      - name: Check API key not in build
        run: |
          npm run build
          if grep -r "${{ secrets.ALCHEMY_API_KEY }}" dist/ 2>/dev/null; then
            echo "FAIL: API key found in build output!"
            exit 1
          fi

  deploy-testnet:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - name: Deploy to Sepolia
        env:
          ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
          DEPLOYER_PRIVATE_KEY: ${{ secrets.DEPLOYER_PRIVATE_KEY }}
        run: npx hardhat run scripts/deploy.ts --network sepolia

Step 2: Fork Test Configuration

// hardhat.config.ts — CI-optimized
const config = {
  solidity: '0.8.24',
  networks: {
    hardhat: {
      forking: {
        url: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
        blockNumber: 19000000,  // Pinned for reproducible CI
        enabled: !!process.env.ALCHEMY_API_KEY,
      },
    },
  },
  mocha: {
    timeout: 60000,  // Fork tests are slower
  },
};

Output

• GitHub Actions with fork-based tests and testnet deployment
• API key exposure scanning in build output
• Pinned block number for reproducible CI results

Examples

Open a pull request that changes a contract test and let the test job run with the fork key supplied only through the CI secret context. The expected result is a passing pinned-block fork test, type check, and build scan with no key material in artifacts or log…

Alchemy Common Errors

Overview

Troubleshooting guide for Alchemy SDK errors covering rate limits, RPC failures, invalid parameters, and network-specific issues.

Prerequisites

• A reproducible failing request that records its network, method, sanitized parameters, timestamp, response code, and request/correlation ID where available—never the API key or private key.
• Access to the appropriate Alchemy dashboard and a non-production key when testing a fix.
• A defined retry budget and an application fallback for requests that cannot safely be retried.

Instructions

1. Classify the failure with the error reference and confirm the intended network, RPC method, and parameter shape.
2. Reproduce it with a scoped development key or a public test fixture, then inspect account limits and service status without exposing credentials.
3. Apply the smallest appropriate repair: correct parameters, back off for 429, paginate a large query, or switch to the documented supported API.
4. Verify the corrected request and record the sanitized outcome; escalate persistent provider failures with the correlation or request ID.

Error Reference

Authentication & Rate Limits

Alchemy Rate Limits by Plan

RPC & Query Errors

// Common RPC error handler
import { Alchemy, Network } from 'alchemy-sdk';

async function safeAlchemyCall<T>(
  operation: () => Promise<T>,
  context: string
): Promise<T | null> {
  try {
    return await operation();
  } catch (error: any) {
    const code = error.code || error.response?.status;

    switch (code) {
      case -32602: // Invalid params
        console.error(`[${context}] Invalid parameters: ${error.message}`);
        console.error('Common causes: wrong address format, invalid block number, missing 0x prefix');
        break;

      c…

Alchemy Core Workflow A — Wallet Portfolio Tracker

Overview

Primary workflow: build a wallet portfolio tracker using Alchemy's Enhanced APIs. Combines getTokenBalances, getNftsForOwner, getAssetTransfers, and token metadata to create a complete wallet view across ERC-20, ERC-721, and ERC-1155 assets.

Prerequisites

• Completed alchemy-install-auth setup
• alchemy-sdk installed
• Understanding of Ethereum address format and token standards

Instructions

Step 1: Portfolio Data Fetcher

// src/portfolio/fetcher.ts
import { Alchemy, Network, AssetTransfersCategory } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

interface TokenHolding {
  contractAddress: string;
  symbol: string;
  name: string;
  balance: number;
  decimals: number;
}

interface NftHolding {
  contractAddress: string;
  collectionName: string;
  tokenId: string;
  name: string;
  imageUrl: string | null;
}

interface WalletPortfolio {
  address: string;
  ethBalance: string;
  tokens: TokenHolding[];
  nfts: NftHolding[];
  recentTransactions: any[];
  fetchedAt: string;
}

async function fetchPortfolio(address: string): Promise<WalletPortfolio> {
  // Parallel fetch all portfolio data
  const [ethBalance, tokenBalances, nftResponse, transfers] = await Promise.all([
    alchemy.core.getBalance(address),
    alchemy.core.getTokenBalances(address),
    alchemy.nft.getNftsForOwner(address, { pageSize: 100 }),
    alchemy.core.getAssetTransfers({
      fromAddress: address,
      category: [
        AssetTransfersCategory.EXTERNAL,
        AssetTransfersCategory.ERC20,
        AssetTransfersCategory.ERC721,
      ],
      maxCount: 25,
      order: 'desc',
    }),
  ]);

  // Resolve token metadata
  const tokens: TokenHolding[] = [];
  for (const tb of tokenBalances.tokenBalances) {
    if (tb.tokenBalance && tb.tokenBalance !== '0x0') {
      const metadata = await alchemy.core.getTokenMetadata(tb.contractAddress);
      const balance = parseInt(tb.tokenBalance, 16) / Math.pow(10, metadata.decimals || 18);
      if (balance > 0.001) {  // Filter dust
        tokens.push({
          contractAddress: tb.contractAddress,
          symbol: metadata.symbol || 'UNKNOWN',
          name: metadata.name || 'Unknown Token',
          balance,
          decimals: metadata.decimals || 18,
        });
      }
    }
  }

  // Map NFTs
  const nfts: NftHolding[] = nftResponse.ownedNfts.map(nft => ({
    contractAddress: nft.contract.address,
    collectionName: nft.contract.name || 'Unknown Collection',
    tokenId: nft.tokenId,
    name: nft.name || `#${nft.tokenId}`,
    imageUrl: nft.image?.cachedUrl || null,
  }));

  return {
    address,
    ethBalance…

Alchemy Core Workflow B — NFT & Smart Contract Interaction

Overview

Build NFT collection explorers and smart contract read operations using Alchemy's NFT API and core JSON-RPC methods.

Prerequisites

• Completed alchemy-install-auth setup
• Familiarity with alchemy-core-workflow-a
• Understanding of ERC-721 and ERC-1155 standards

Instructions

Step 1: NFT Collection Explorer

// src/nft/collection-explorer.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async function exploreCollection(contractAddress: string) {
  const metadata = await alchemy.nft.getContractMetadata(contractAddress);

  return {
    address: contractAddress,
    name: metadata.name || 'Unknown',
    symbol: metadata.symbol || '',
    totalSupply: metadata.totalSupply || '0',
    tokenType: metadata.tokenType,
    floorPrice: metadata.openSeaMetadata?.floorPrice || null,
    description: metadata.openSeaMetadata?.description || '',
    imageUrl: metadata.openSeaMetadata?.imageUrl || null,
  };
}

async function getCollectionNfts(contractAddress: string, limit: number = 20) {
  const response = await alchemy.nft.getNftsForContract(contractAddress, { limit });
  return response.nfts.map(nft => ({
    tokenId: nft.tokenId,
    name: nft.name || `#${nft.tokenId}`,
    description: nft.description,
    image: nft.image?.cachedUrl || nft.image?.originalUrl,
    attributes: nft.raw?.metadata?.attributes || [],
  }));
}

// Example: Bored Ape Yacht Club
const BAYC = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D';
exploreCollection(BAYC).then(console.log).catch(console.error);

Step 2: Batch NFT Metadata

// src/nft/batch-metadata.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async function batchGetNftMetadata(
  tokens: Array<{ contractAddress: string; tokenId: string }>
) {
  const results = await alchemy.nft.getNftMetadataBatch(
    tokens.map(t => ({ contractAddress: t.contractAddress, tokenId: t.tokenId }))
  );
  return results.map(nft => ({
    contract: nft.contract.address,
    tokenId: nft.tokenId,
    name: nft.name,
    image: nft.image?.cachedUrl,
    tokenType: nft.tokenType,
    collection: nft.contract.name,
  }));
}

Step 3: Smart Contract Read via Ethers + Alchemy Provider

// src/contracts/read-contract.ts
import { Alchemy, Network } from 'alchemy-sdk';
import { ethers } from 'ethers';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async …

Alchemy Cost Tuning

Overview

Alchemy pricing is based on Compute Units (CU). Different API methods have different CU costs. Optimize by caching, batching, choosing cheaper methods, and right-sizing your plan.

Plan Comparison

CU Cost Reference (Top Methods)

Prerequisites

• An approved observation window with aggregate method counts and latency; do not record end-user wallet data merely to estimate API usage.
• Current plan and compute-unit limits confirmed in the organization’s Alchemy account, since commercial terms and method costs may change.
• A cache-invalidation policy that distinguishes safe metadata caching from time-sensitive balance, block, and transaction data.

Instructions

Step 1: CU Usage Monitor

// src/cost/cu-monitor.ts
const CU_COSTS: Record<string, number> = {
  'eth_blockNumber': 10, 'eth_getBalance': 19, 'eth_call': 26,
  'getTokenBalances': 50, 'getNftsForOwner': 50, 'getTokenMetadata': 50,
  'getAssetTransfers': 150, 'getNftMetadataBatch': 50,
};

class CuMonitor {
  private usage: Array<{ method: string; cu: number; timestamp: number }> = [];

  record(method: string): void {
    this.usage.push({ method, cu: CU_COSTS[method] || 26, timestamp: Date.now() });
  }

  getHourlyReport(): { totalCu: number; byMethod: Record<string, number> } {
    const cutoff = Date.now() - 3600000;
    const recent = this.usage.filter(u => u.timestamp > cutoff);
    const byMethod: Record<string, number> = {};
    let totalCu = 0;

    for (const u of recent) …

Alchemy Debug Bundle

Overview

Collect diagnostic data for Alchemy support tickets: connectivity tests, SDK version, network status, CU usage, and recent error logs.

Prerequisites

• A scoped development or sandbox key supplied through a secret store; never pass the key as a command-line argument or include it in a captured bundle.
• A reproducible issue with the expected network, method, time window, and sanitized request/correlation ID.
• A review path that checks the bundle for credentials, wallet-address privacy concerns, or proprietary application data before it leaves the organization.

Instructions

Step 1: Debug Bundle Generator

// src/debug/alchemy-debug.ts
import { Alchemy, Network } from 'alchemy-sdk';

interface DebugBundle {
  timestamp: string;
  sdkVersion: string;
  environment: Record<string, string>;
  connectivity: Record<string, any>;
  networkStatus: Record<string, any>;
}

async function generateDebugBundle(): Promise<DebugBundle> {
  const alchemy = new Alchemy({
    apiKey: process.env.ALCHEMY_API_KEY,
    network: Network.ETH_MAINNET,
  });

  const bundle: DebugBundle = {
    timestamp: new Date().toISOString(),
    sdkVersion: require('alchemy-sdk/package.json').version,
    environment: {
      nodeVersion: process.version,
      platform: process.platform,
      apiKeySet: process.env.ALCHEMY_API_KEY ? 'yes (redacted)' : 'NO — missing',
      network: process.env.ALCHEMY_NETWORK || 'ETH_MAINNET',
    },
    connectivity: {},
    networkStatus: {},
  };

  // Test core connectivity
  try {
    const start = Date.now();
    const blockNumber = await alchemy.core.getBlockNumber();
    bundle.connectivity.core = {
      status: 'ok',
      latencyMs: Date.now() - start,
      latestBlock: blockNumber,
    };
  } catch (err: any) {
    bundle.connectivity.core = { status: 'failed', error: err.message };
  }

  // Test Enhanced API
  try {
    const start = Date.now();
    await alchemy.core.getTokenBalances('0x0000000000000000000000000000000000000000');
    bundle.connectivity.enhancedApi = { status: 'ok', latencyMs: Date.now() - start };
  } catch (err: any) {
    bundle.connectivity.enhancedApi = { status: 'failed', error: err.message };
  }

  // Test NFT API
  try {
    const start = Date.now();
    await alchemy.nft.getContractMetadata('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D');
    bundle.connectivity.nftApi = { status: 'ok', latencyMs: Date.now() - start };
  } catch (err: any) {
    bundle.connectivity.nftApi = { status: 'failed', error: err.message };
  }

  // Multi-network status
  for (const [name, network] of Object.entries({
    ethereum: Network.ETH_MAINNET,
    polygon: Network.MATIC_MAINNET,
    arbitrum: Network.ARB_MAINNET,
  })) {
    try {
      c…

Alchemy Deploy Integration

Overview

Deploy Alchemy-powered dApps with proper API key security. The API key must stay server-side — never ship it to the browser.

Prerequisites

• A server-side deployment target with a managed secret store and a scoped Alchemy key that is distinct from local development credentials.
• Input validation, rate limiting, and logging rules for any public RPC proxy endpoint so arbitrary callers cannot turn it into an account-exhaustion path.
• A tested rollback target and authenticated operational health check that does not reveal credentials, internal configuration, or user activity.

Instructions

Step 1: Vercel Deployment

# Add Alchemy API key as Vercel secret
vercel secrets add alchemy_api_key "your-api-key"
vercel link
vercel --prod

// vercel.json
{
  "env": { "ALCHEMY_API_KEY": "@alchemy_api_key" },
  "functions": { "api/**/*.ts": { "maxDuration": 30 } }
}

// api/balance/[address].ts — Vercel serverless function
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

export default async function handler(req: any, res: any) {
  const { address } = req.query;
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
    return res.status(400).json({ error: 'Invalid address' });
  }
  const balance = await alchemy.core.getBalance(address);
  res.json({ balance: balance.toString() });
}

Step 2: Cloud Run Deployment

# Build and deploy
gcloud builds submit --tag gcr.io/${PROJECT_ID}/alchemy-dapp
gcloud run deploy alchemy-dapp \
  --image gcr.io/${PROJECT_ID}/alchemy-dapp \
  --region us-central1 \
  --set-secrets=ALCHEMY_API_KEY=alchemy-api-key:latest \
  --allow-unauthenticated

Step 3: Health Check

// api/health.ts
import { Alchemy, Network } from 'alchemy-sdk';

export default async function handler(_req: any, res: any) {
  try {
    const alchemy = new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.ETH_MAINNET });
    const block = await alchemy.core.getBlockNumber();
    res.json({ status: 'healthy', latestBlock: block });
  } catch {
    res.status(503).json({ status: 'unhealthy' });
  }
}

Output

• Vercel deployment with API key in server-side functions
• Cloud Run with GCP Secret Manager
• Health check endpoint verifying Alchemy connectivity

Examples

Deploy a staging serverless balance endpoint with the API key injected only by the platform secret binding, then call it with a public test address. Confirm that invalid addresses …

Alchemy Hello World

Overview

Minimal working examples with the real Alchemy SDK: get ETH balance, fetch NFTs for a wallet, read ERC-20 token balances, and subscribe to pending transactions.

Prerequisites

• Completed alchemy-install-auth setup
• alchemy-sdk installed (npm install alchemy-sdk)
• Valid API key configured

Instructions

Step 1: Get ETH Balance

// src/hello-world/get-balance.ts
import { Alchemy, Network, Utils } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async function getBalance(address: string) {
  const balanceWei = await alchemy.core.getBalance(address);
  const balanceEth = Utils.formatEther(balanceWei);
  console.log(`Balance of ${address}: ${balanceEth} ETH`);
  return balanceEth;
}

// Query Vitalik's address
getBalance('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045').catch(console.error);

Step 2: Fetch NFTs for a Wallet

// src/hello-world/get-nfts.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async function getNftsForOwner(owner: string) {
  const nfts = await alchemy.nft.getNftsForOwner(owner);
  console.log(`Total NFTs: ${nfts.totalCount}`);

  for (const nft of nfts.ownedNfts.slice(0, 5)) {
    console.log(`  ${nft.contract.name} — ${nft.name || nft.tokenId}`);
    console.log(`    Contract: ${nft.contract.address}`);
    console.log(`    Token ID: ${nft.tokenId}`);
    if (nft.image?.cachedUrl) {
      console.log(`    Image: ${nft.image.cachedUrl}`);
    }
  }

  return nfts;
}

getNftsForOwner('vitalik.eth').catch(console.error);

Step 3: Get ERC-20 Token Balances

// src/hello-world/get-tokens.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

async function getTokenBalances(address: string) {
  const balances = await alchemy.core.getTokenBalances(address);

  console.log(`Token balances for ${address}:`);
  for (const token of balances.tokenBalances.slice(0, 10)) {
    if (token.tokenBalance && token.tokenBalance !== '0x0') {
      // Get token metadata for human-readable names
      const metadata = await alchemy.core.getTokenMetadata(token.contractAddress);
      const balance = parseInt(token.tokenBalance, 16) / Math.pow(10, metadata.decimals || 18);
      console.log(`  ${metadata.symbol}: ${balance.toFixed(4)}`);
    }
  }
}

getTokenBalances('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045').catch(console.error);

Step 4: Get Latest Block Info

Alchemy Install & Auth

Overview

Install the alchemy-sdk npm package and configure API authentication. Alchemy provides blockchain infrastructure (RPC nodes, Enhanced APIs, NFT APIs, webhooks) across Ethereum, Polygon, Arbitrum, Optimism, Base, and Solana.

Prerequisites

• Node.js 18+ (or Python 3.10+ for alchemy-sdk Python)
• Free Alchemy account at alchemy.com
• API key from Alchemy Dashboard

Instructions

Step 1: Install the Alchemy SDK

# JavaScript/TypeScript (official SDK)
npm install alchemy-sdk

# Python (community SDK)
pip install alchemy-sdk

Step 2: Create an Alchemy App

1. Go to dashboard.alchemy.com
2. Click "Create new app"
3. Select chain: Ethereum, Polygon, Arbitrum, Optimism, Base, or Solana
4. Select network: Mainnet, Sepolia (testnet), or Mumbai
5. Copy the API key

Step 3: Configure Environment

# Set environment variable
export ALCHEMY_API_KEY="your-api-key-here"

# Or create .env file
cat > .env << 'EOF'
ALCHEMY_API_KEY=your-api-key-here
ALCHEMY_NETWORK=ETH_MAINNET
EOF

echo ".env" >> .gitignore

Step 4: Initialize and Verify

// src/alchemy-client.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

// Verify connection
async function verifyConnection() {
  const blockNumber = await alchemy.core.getBlockNumber();
  console.log(`Connected! Latest block: ${blockNumber}`);
  return blockNumber;
}

verifyConnection().catch(console.error);

Step 5: Multi-Chain Configuration

// src/config/chains.ts
import { Alchemy, Network } from 'alchemy-sdk';

// Create clients for multiple chains
const chains = {
  ethereum: new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.ETH_MAINNET }),
  polygon: new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.MATIC_MAINNET }),
  arbitrum: new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.ARB_MAINNET }),
  optimism: new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.OPT_MAINNET }),
  base: new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.BASE_MAINNET }),
};

export default chains;

Supported Networks

Alchemy Local Dev Loop

Overview

Local Web3 development workflow using Alchemy as the RPC provider with Hardhat for local testing, Sepolia testnet for staging, and hot-reload for rapid iteration.

Prerequisites

• Completed alchemy-install-auth setup
• Node.js 18+
• Alchemy API key with Sepolia testnet app

Instructions

Step 1: Initialize Hardhat Project with Alchemy

mkdir web3-project && cd web3-project
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npm install alchemy-sdk dotenv
npx hardhat init  # Select TypeScript project

Step 2: Configure Hardhat with Alchemy RPC

// hardhat.config.ts
import { HardhatUserConfig } from 'hardhat/config';
import '@nomicfoundation/hardhat-toolbox';
import 'dotenv/config';

const config: HardhatUserConfig = {
  solidity: '0.8.24',
  networks: {
    hardhat: {
      forking: {
        url: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
        blockNumber: 19000000,  // Pin block for reproducible tests
      },
    },
    sepolia: {
      url: `https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
      accounts: process.env.DEPLOYER_PRIVATE_KEY ? [process.env.DEPLOYER_PRIVATE_KEY] : [],
    },
  },
};

export default config;

Step 3: Alchemy-Powered Test Helper

// test/helpers/alchemy-helper.ts
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_SEPOLIA,
});

export async function getTestnetBalance(address: string): Promise<string> {
  const balance = await alchemy.core.getBalance(address);
  return (parseInt(balance.toString()) / 1e18).toFixed(4);
}

export async function waitForTransaction(txHash: string): Promise<any> {
  return alchemy.core.waitForTransaction(txHash, 1, 60000);
}

export { alchemy };

Step 4: Development Scripts

{
  "scripts": {
    "dev": "npx hardhat node --fork https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
    "test": "npx hardhat test",
    "test:watch": "npx hardhat test --watch",
    "deploy:sepolia": "npx hardhat run scripts/deploy.ts --network sepolia",
    "verify": "npx hardhat verify --network sepolia"
  }
}

Step 5: Mainnet Fork Testing

// test/fork-test.ts
import { expect } from 'chai';
import { ethers } from 'hardhat';

describe('Mainnet Fork Tests', () => {
  it('should read USDC balance on forked mainnet', async () => {
    const USDC = '0xA0b86991c62…

Alchemy Performance Tuning

Overview

Optimize a Web3 application's response time and provider use through freshness-aware caching, bounded parallelism, batching, and real-time subscriptions. Measure improvements against an approved baseline rather than assuming fewer calls always preserves correct chain state.

Performance Targets

Prerequisites

• A representative, non-sensitive benchmark workload with baseline latency, cache-hit, error-rate, and compute-unit measurements.
• An explicit freshness policy for balances, blocks, transfers, ownership, and metadata, approved by the product owner.
• Monitoring and a rollback flag that can disable cache, batching, or WebSocket changes if correctness or provider behavior regresses.

Instructions

Step 1: Response Caching with TTL

// src/performance/cache.ts
import { Alchemy, Network } from 'alchemy-sdk';

class BlockchainCache {
  private store = new Map<string, { data: any; expiry: number }>();

  // Different TTLs for different data freshness needs
  private TTL: Record<string, number> = {
    blockNumber: 12000,     // 12s (~1 block)
    balance: 30000,         // 30s
    tokenBalances: 60000,   // 60s
    nftOwnership: 300000,   // 5 min (NFTs transfer less frequently)
    contractMetadata: 3600000, // 1 hour (rarely changes)
    tokenMetadata: 86400000,   // 24 hours (almost never changes)
  };

  async cached<T>(category: string, key: string, fetcher: () => Promise<T>): Promise<T> {
    const cacheKey = `${category}:${key}`;
    const entry = this.store.get(cacheKey);
    if (entry && entry.expiry > Date.now()) return entry.data;

    const data = await fetcher();
    this.store.set(cacheKey, { data, expiry: Date.now() + (this.TTL[category] || 30000) });
    return data;
  }

  invalidate(category: string): void {
    for (const key of this.store.keys()) {
      if (key.startsWith(`${category}:`)) this.store.delete(key);
    }
  }
}

const cache = new BlockchainCache();
export { cache };

Step 2: Parallel Multi-Chain Fetching

// src/performance/parallel-fetch.ts
import { Alchemy, Network } from 'alchemy-sdk';
import { cache } from './cache';

const CHAINS = …

Alchemy Production Checklist

Overview

Use this checklist to make a deliberate go/no-go decision for an Alchemy-powered application. It covers provider isolation, key custody, application security, contract controls, performance, monitoring, and a reversible launch path.

Prerequisites

• Named engineering, security, product, and operations owners who can block a release, plus an approved deployment window and rollback target.
• Separate production application and managed-secret bindings that have been tested in staging without reusing local or testnet credentials.
• A documented user-impact fallback for provider outages, contract incidents, and unsafe chain-data results.

Instructions

1. Assign an owner and evidence link to each pre-launch item, treating an unchecked security, provider, or contract control as a release blocker.
2. Run the readiness script using the production deployment identity and inspect only its redacted results.
3. Exercise the rollback or disable flag in staging, verify operator alerts, and record the owner who will make the launch decision.
4. Enable traffic progressively and stop expansion when any listed threshold or safety invariant fails.

Pre-Launch Checklist

API & Infrastructure

• [ ] API key restricted to production domains in Alchemy Dashboard
• [ ] Separate Alchemy apps for dev/staging/prod environments
• [ ] Rate limit headroom verified (< 70% of CU/sec budget)
• [ ] Retry logic with exponential backoff implemented
• [ ] Error monitoring configured (Sentry, Datadog, etc.)
• [ ] Webhook endpoints HTTPS-only with signature verification

Security

• [ ] API key NOT in frontend code — proxied through backend
• [ ] Private keys in secret manager (not env files)
• [ ] All user-supplied addresses validated and checksummed
• [ ] No console.log of sensitive data in production builds
• [ ] npm audit clean — no critical vulnerabilities

Smart Contracts (if applicable)

• [ ] Contracts audited by reputable firm
• [ ] Deployed and verified on Etherscan/Polygonscan
• [ ] Admin keys secured in multi-sig wallet
• [ ] Emergency pause function tested

Performance

• [ ] Response caching for frequently-queried data (balances, metadata)
• [ ] Connection pooling for provider instances
• [ ] Batch requests where possible (NFT metadata, balances)
• [ ] WebSocket reconnection logic for real-time subscriptions

Validation Script

// src/prod/readiness.ts
import { Alchemy, Network } from 'alchemy-sdk';

async function checkReadiness(): Promise<void> {
  const checks: Array<{ name: string; pass: boolean; detail: string }> = [];

…

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: () => Pr…

Alchemy Reference Architecture

Overview

This reference architecture separates wallet-facing UI from server-side provider access so API keys, rate limits, validation, caching, and webhook verification are consistently controlled across supported chains.

Prerequisites

• A written data-flow and threat model covering wallet addresses, signed messages, provider credentials, public API routes, and webhook events.
• A server-side deployment target with managed secrets, input validation, rate limiting, and observability before any frontend endpoint is exposed.
• Public-chain or testnet fixtures and a rollback mechanism for each feature that affects external users or contract interactions.

Instructions

1. Begin with a single chain and server-side client factory, keeping the provider key out of browser bundles and public response payloads.
2. Add validated, rate-limited API routes for each use case and define the cache freshness rule before implementing UI data fetching.
3. Treat a wallet address as an identifier, not authentication; use a signed challenge when ownership must be proved.
4. Verify webhook signatures and idempotency before routing any external event, then test the complete path against public or testnet fixtures.

System Architecture

┌─────────────────────────────────────────────────────────┐
│                     Frontend (React/Next.js)              │
│  - Wallet connection (MetaMask, WalletConnect)           │
│  - Portfolio dashboard                                    │
│  - NFT gallery                                           │
│  - Transaction history                                    │
└────────────────────────┬────────────────────────────────┘
                         │ HTTPS (no API key exposed)
┌────────────────────────▼────────────────────────────────┐
│                     API Layer (Next.js/Express)           │
│  - /api/balance/:address                                 │
│  - /api/nfts/:owner                                      │
│  - /api/tokens/:address                                  │
│  - /api/transactions/:address                            │
│  - /webhooks/alchemy          (webhook receiver)         │
└───────┬──────────┬──────────┬───────────────────────────┘
        │          │          │
   ┌────▼───┐ ┌───▼────┐ ┌──▼──────┐
   │Alchemy │ │Alchemy │ │Alchemy  │
   │Core API│ │NFT API │ │Notify   │
   │(RPC)   │ │        │ │(Webhooks│
   └────────┘ └────────┘ └─────────┘
   ETH/Polygon/ARB/OP/Base

Project Structure

web3-dapp/
├── src/
│   ├── alchemy/
│   │   ├── client-factory.ts    # Multi-chain Alchemy client factory
│   │   ├── cache.ts             # Response caching with TTL
│   │   ├── throttler.ts         # CU-aware rate limiter
│   │   └── errors.ts            # Error classification
│   ├── portfolio/
│   │   ├── fetcher.ts         …

Alchemy SDK Patterns

Overview

Production patterns for the alchemy-sdk package: singleton clients, multi-chain factories, response caching, and type-safe contract wrappers.

Prerequisites

• A server-side environment with a managed provider key and a typed list of supported chains; do not create browser-side clients with the key.
• A freshness policy for each cached response type and a test fixture for both successful and failed provider calls.
• Input validation at the application boundary before an address, collection, or network value reaches the client factory or query builder.

Instructions

Step 1: Multi-Chain Client Factory

// src/alchemy/client-factory.ts
import { Alchemy, Network } from 'alchemy-sdk';

type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'base';

const NETWORK_MAP: Record<ChainName, Network> = {
  ethereum: Network.ETH_MAINNET,
  polygon: Network.MATIC_MAINNET,
  arbitrum: Network.ARB_MAINNET,
  optimism: Network.OPT_MAINNET,
  base: Network.BASE_MAINNET,
};

class AlchemyClientFactory {
  private static clients = new Map<string, Alchemy>();

  static getClient(chain: ChainName): Alchemy {
    if (!this.clients.has(chain)) {
      this.clients.set(chain, new Alchemy({
        apiKey: process.env.ALCHEMY_API_KEY,
        network: NETWORK_MAP[chain],
        maxRetries: 3,
      }));
    }
    return this.clients.get(chain)!;
  }

  static getAllClients(): Map<ChainName, Alchemy> {
    for (const chain of Object.keys(NETWORK_MAP) as ChainName[]) {
      this.getClient(chain);
    }
    return this.clients as Map<ChainName, Alchemy>;
  }
}

export { AlchemyClientFactory, ChainName };

Step 2: Response Caching Layer

// src/alchemy/cache.ts
interface CacheEntry<T> { data: T; expiresAt: number; }

class AlchemyCache {
  private cache = new Map<string, CacheEntry<any>>();
  private defaultTtlMs: number;

  constructor(defaultTtlMs: number = 30000) { // 30s default
    this.defaultTtlMs = defaultTtlMs;
  }

  async getOrFetch<T>(key: string, fetcher: () => Promise<T>, ttlMs?: number): Promise<T> {
    const cached = this.cache.get(key);
    if (cached && cached.expiresAt > Date.now()) return cached.data;

    const data = await fetcher();
    this.cache.set(key, { data, expiresAt: Date.now() + (ttlMs || this.defaultTtlMs) });
    return data;
  }

  invalidate(keyPrefix: string): void {
    for (const key of this.cache.keys()) {
      if (key.startsWith(keyPrefix)) this.cache.delete(key);
    }
  }
}

// Usage with Alchemy
const cache = new AlchemyCache();

async function getCachedBalance(alchemy: Alchemy, address: string): Promise<string> {
  return cache.getOrFetch(
    `balance:${address}`,
…

Alchemy Security Basics

Overview

Web3 security practices for Alchemy-powered applications: API key protection, private key management, input validation, and smart contract interaction safety.

Security Checklist

Prerequisites

• A threat model that names provider-key, deployer-key, webhook, public-route, and user-input trust boundaries.
• Managed secret storage and a revocation owner for every provider or signing credential; do not rely on a developer workstation environment file in production.
• Security tests using synthetic inputs and a reviewed incident path for suspected key exposure, invalid signatures, or unsafe contract operations.

Instructions

Step 1: API Key Protection

// WRONG — API key in frontend code
// const alchemy = new Alchemy({ apiKey: 'demo123' }); // NEVER DO THIS

// RIGHT — API key in backend proxy
// src/api/proxy.ts
import express from 'express';
import { Alchemy, Network } from 'alchemy-sdk';

const app = express();
const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY, // Server-side only
  network: Network.ETH_MAINNET,
});

// Proxy endpoint — frontend calls this instead of Alchemy directly
app.get('/api/balance/:address', async (req, res) => {
  const { address } = req.params;
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
    return res.status(400).json({ error: 'Invalid address format' });
  }
  const balance = await alchemy.core.getBalance(address);
  res.json({ balance: balance.toString() });
});

// Alchemy Dashboard: restrict API key to specific domains/IPs
// Dashboard > App > Settings > Allowed Domains

Step 2: Input Validation for Blockchain Queries

// src/security/validators.ts
import { ethers } from 'ethers';

function validateAddress(input: string): string {
  if (!ethers.isAddress(input)) throw new Error(`Invalid address: ${input}`);
  return ethers.getAddress(input); // Returns checksummed address
}

function validateBlockNumber(input: string | number): string {
  if (input === 'latest' || input === 'pending' || input === 'earliest') return input;
  const num = typeof input === …

Alchemy Upgrade & Migration

Overview

Migration guide for Alchemy SDK upgrades and deprecated package transitions. The alchemy-web3 package is deprecated — migrate to alchemy-sdk.

Migration Paths

Prerequisites

• A version-pinned dependency baseline, lockfile, and inventory of every current provider, WebSocket, NFT, and notification call.
• A testnet or public-chain fixture suite that proves the existing behavior without exposing production keys or user data.
• A reversible deployment plan that can route traffic to the prior artifact if namespace, type, or provider behavior changes unexpectedly.

Instructions

Step 1: Migrate from alchemy-web3 to alchemy-sdk

// BEFORE: alchemy-web3 (DEPRECATED)
// import { createAlchemyWeb3 } from '@alch/alchemy-web3';
// const web3 = createAlchemyWeb3(`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`);
// const balance = await web3.eth.getBalance(address);
// const nfts = await web3.alchemy.getNfts({ owner });

// AFTER: alchemy-sdk
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

// Core methods — same JSON-RPC, different API
const balance = await alchemy.core.getBalance(address);

// Enhanced APIs — reorganized under namespaces
const nfts = await alchemy.nft.getNftsForOwner(owner);

// WebSockets — now under alchemy.ws
alchemy.ws.on({ method: 'eth_subscribe', params: ['newHeads'] }, (block) => {
  console.log('New block:', block);
});

Step 2: API Surface Changes

// Key namespace changes in alchemy-sdk:

// Core (JSON-RPC wrapper)
alchemy.core.getBlockNumber();
alchemy.core.getBalance(address);
alchemy.core.getTokenBalances(address);
alchemy.core.getTokenMetadata(contractAddress);
alchemy.core.getAssetTransfers({ fromAddress, category });

// NFT (dedicated namespace)
alchemy.nft.getNftsForOwner(owner);
alchemy.nft.getNftsForContract(contract);
alchemy.nft.getContractMetadata(contract);
alchemy.nft.getNftMetadataBatch(tokens);
alchemy.nft.getOwnersForNft(contract, tokenId);

// WebSocket (real-time)
alchemy.ws.on(filter, callback);
alchemy.ws.once(filter, callback);
alchemy.ws.removeAllListeners();

// Notify (webhooks — requires authToken)
alchemy.notify.getAllWebhooks();
alchemy.notify.create…

Alchemy Webhooks & Events (Notify API)

Overview

Alchemy Notify provides real-time push notifications for on-chain events. Instead of polling, receive webhook callbacks for wallet activity, mined transactions, dropped transactions, and smart contract events.

Webhook Types

Prerequisites

• A TLS-protected callback URL, signing key in managed storage, and a handler that receives the raw body before JSON parsing for signature verification.
• Persistent idempotency storage, validated address/filter configuration, and a least-privilege workflow token for webhook management.
• A product decision for reorganization, duplicate delivery, unavailable callbacks, and event types that require user-visible confirmation.

Instructions

Step 1: Create Webhook via Dashboard or API

# Create Address Activity webhook via Alchemy API
curl -X POST "https://dashboard.alchemy.com/api/create-webhook" \
  -H "X-Alchemy-Token: ${ALCHEMY_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "ETH_MAINNET",
    "webhook_type": "ADDRESS_ACTIVITY",
    "webhook_url": "https://your-app.com/webhooks/alchemy",
    "addresses": [
      "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    ]
  }'

Step 2: Webhook Handler with Signature Verification

// src/webhooks/alchemy-handler.ts
import express from 'express';
import crypto from 'crypto';

const router = express.Router();

router.post('/webhooks/alchemy',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // Verify webhook signature
    const signature = req.headers['x-alchemy-signature'] as string;
    if (!verifySignature(req.body.toString(), signature)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await processAlchemyEvent(event);
    res.status(200).json({ ok: true });
  }
);

function verifySignature(body: string, signature: string): boolean {
  const signingKey = process.env.ALCHEMY_WEBHOOK_SIGNING_KEY!;
  const hmac = crypto…