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

From	To	Complexity
`alchemy-web3`	`alchemy-sdk`	High (different API surface)
`alchemy-sdk` v2 → v3	`alchemy-sdk` v3	Medium (some breaking changes)
Direct JSON-RPC	`alchemy-sdk`	Low (SDK wraps same methods)

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

Failure	Response
Dependency install or lockfile changes unexpectedly	Stop the upgrade, inspect the resolved graph, and restore the approved lockfile.
Replacement call differs from the baseline	Keep traffic on the prior artifact and correct the adapter or fixture expectation.
Deprecated import remains after migration	Treat it as incomplete, remove or replace it, and rerun the repository scan.
Testnet/provider validation fails	Do not promote the version; retain sanitized evidence and investigate before retrying.

Resources

Next Steps

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