Alchemy Upgrade Migration

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.createWebhook(config);

Step 3: Dependency Cleanup

# Remove deprecated packages
npm uninstall @alch/alchemy-web3 alchemy-web3

# Install current SDK
npm install alchemy-sdk

# Check for leftover imports
grep -rn "alchemy-web3\|@alch/alchemy" src/ --include='*.ts' --include='*.js'

# Update ethers if needed (alchemy-sdk works with ethers v5 and v6)
npm install ethers@6

Step 4: Test Migration

// tests/migration.test.ts
import { describe, it, expect } from 'vitest';
import { Alchemy, Network } from 'alchemy-sdk';

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

  it('should get block number via core namespace', async () => {
    const block = await alchemy.core.getBlockNumber();
    expect(block).toBeGreaterThan(0);
  });

  it('should get NFTs via nft namespace', async () => {
    const nfts = await alchemy.nft.getNftsForOwner('0x0000000000000000000000000000000000000000');
    expect(nfts.totalCount).toBeDefined();
  });
});

Output

• Migrated from alchemy-web3 to alchemy-sdk
• All namespace changes applied (core, nft, ws, notify)
• Deprecated packages removed
• Migration tests passing

Examples

Create a migration branch, pin the target SDK version, and replace one read-only Sepolia block-number call with its alchemy.core equivalent. Run the existing fixture suite plus a negative test for an invalid address, then compare the normalized output and sanitized error classification with the prior implementation. Remove deprecated imports only after the replacement tests pass. If a namespace change, type mismatch, or provider response differs from the approved behavior, keep the old release artifact available, revert the canary, and document the incompatibility before attempting a wider migration.

Error Handling

Resources

• Alchemy SDK Migration Guide
• alchemy-sdk npm
• alchemy-sdk GitHub

Next Steps

For CI/CD setup, see alchemy-ci-integration.