Alchemy

Skill based on Alchemy SDK JS (alchemy-sdk) docs, generated at 2026-02-09.

The Alchemy SDK is a JavaScript SDK for blockchain access: Ethers.js–compatible provider plus Enhanced APIs (token balances, asset transfers, NFT API, WebSockets, transaction simulation, private tx, Portfolio, Notify, Debug). One client instance per network/API key; namespaces: core, nft, ws, transact, notify, portfolio, prices, debug.

Core References

Features

NFT

Realtime and Transact

Portfolio and Notify

Debug

Generation Info

• Source: sources/alchemy
• Git SHA: 374385c1f2d5b5fb7dd45ea5b13430207fa863a3
• Generated: 2026-02-09

Alchemy Client

The Alchemy SDK client is the main entry point. One instance = one network + one API key. Use new Alchemy(settings?) and access namespaces via alchemy.core, alchemy.nft, alchemy.ws, etc.

Instantiation

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

const alchemy = new Alchemy({
  apiKey: 'your-api-key',  // default: 'demo' (rate-limited)
  network: Network.ETH_MAINNET,
  maxRetries: 5,
  url: undefined,          // override generated URL if set
  authToken: undefined,     // required for notify + portfolio
  batchRequests: false,
  requestTimeout: undefined,
});

Namespaces

Config and Underlying Provider

• alchemy.config — holds settings; use alchemy.config.getProvider() to get the underlying Ethers.js AlchemyProvider when you need low-level methods (e.g. formatter).
• ENS: Address parameters accept ENS names (e.g. vitalik.eth) wherever an EOA address is expected.

Key Points

• One Alchemy instance per network/API key; create a new instance for another network.
• authToken (from Alchemy Dashboard) is required for notify and portfolio.
• Supported networks: Network enum (e.g. ETH_MAINNET, POLYGON_MAINNET, ARBITRUM_MAINNET, many L2s and alt chains).

<!-- Source references:

• https://github.com/alchemyplatform/alchemy-sdk-js
• sources/alchemy/docs-md/README.md
• sources/alchemy/docs-md/classes/Alchemy.md
• sources/alchemy/docs-md/interfaces/AlchemySettings.md

-->

Core Namespace

alchemy.core exposes standard Ethers.js provider methods plus Alchemy Enhanced APIs. It is a drop-in replacement for an Ethers.js provider for common operations.

Standard Provider Methods

Use as you would with Ethers: getBlockNumber, getBalance, getBlock, getTransaction, getTransactionReceipt, getTransactionCount, getCode, getLogs, call, estimateGas, sendTransaction, waitForTransaction, getNetwork, getFeeData, getGasPrice, resolveName, lookupAddress, getStorageAt, ready, send.

Enhanced APIs

• getTokenMetadata(contractAddress) — metadata for a token contract.
• getTokenBalances(ownerAddress, contractAddresses?) — token balances for an owner; omit contract list for all tokens.
• getAssetTransfers(params) / getAssetTransfersWithMetadata(params) — transfers for addresses; params include fromAddress, toAddress, fromBlock, toBlock, category, etc.
• getTransactionReceipts(params) — all receipts for a block (params: blockNumber).
• findContractDeployer(contractAddress) — deployer address and block (binary search; can be slow; beta).
• getTokensForOwner(ownerAddress, options?) — all token balances and metadata for an owner.
• isContractAddress(address) — whether address has code.

Usage

const alchemy = new Alchemy({ apiKey: 'demo', network: Network.ETH_MAINNET });

// Standard
const blockNumber = await alchemy.core.getBlockNumber();
const balance = await alchemy.core.getBalance('vitalik.eth');

// Enhanced
const tokenBalances = await alchemy.core.getTokenBalances('vitalik.eth');
const transfers = await alchemy.core.getAssetTransfers({
  fromAddress: 'vitalik.eth',
  fromBlock: '0x0',
  toBlock: 'latest',
});
const tokensForOwner = await alchemy.core.getTokensForOwner('vitalik.eth');
const deployer = await alchemy.core.findContractDeployer('0x…');

Key Points

• ENS is supported for address parameters.
• For full Ethers provider (e.g. formatter), use alchemy.config.getProvider().
• Pagination for Enhanced APIs often uses pageKey from the previous response.

<!-- Source references:

• sources/alchemy/docs-md/classes/CoreNamespace.md
• sources/alchemy/docs-md/README.md

-->

Debug Namespace

alchemy.debug exposes non-standard RPC methods for inspecting and replaying transactions and blocks: traceCall, traceTransaction, traceBlock. Use for debugging execution and state changes.

Methods

• traceCall(transaction, blockIdentifier, tracer) — run eth_call in the context of the given block; returns trace. tracer: DebugCallTracer or DebugPrestateTracer.
• traceTransaction(transactionHash, tracer) — replay the transaction exactly as executed; returns trace.
• traceBlock(blockIdentifier, tracer) — replay a mined block; returns trace(s). blockIdentifier: block hash, block number hex, or commitment level.

Tracers

• DebugCallTracer — call trace (nested calls, inputs/outputs).
• DebugPrestateTracer — state before execution (slot/value).
• Tracer type and config depend on Alchemy’s debug API; see interfaces DebugCallTracer, DebugPrestateTracer, DebugCallTrace, DebugTransaction.

Usage

const alchemy = new Alchemy();

const callTrace = await alchemy.debug.traceCall(
  { to: '0x…', data: '0x…', from: '0x…' },
  'latest',
  { type: DebugTracerType.CALL_TRACER }
);
const txTrace = await alchemy.debug.traceTransaction(txHash, { type: DebugTracerType.CALL_TRACER });
const blockTrace = await alchemy.debug.traceBlock('0x1234', { type: DebugTracerType.CALL_TRACER });

Key Points

• traceCall uses parent block state; traceTransaction replays in chain order.
• blockIdentifier can be block number (hex), block hash, or commitment (e.g. latest).
• Use for debugging reverts, gas, or state diffs without sending transactions.

<!-- Source references:

• sources/alchemy/docs-md/classes/DebugNamespace.md
• sources/alchemy/docs-md/README.md

-->

NFT Namespace

alchemy.nft provides the Alchemy NFT API: metadata, ownership, transfers, pagination via iterators, spam classification, rarity, and floor price.

Metadata and Ownership

• getNftMetadata(contractAddress, tokenId, options?) — single NFT metadata.
• getNftMetadataBatch(tokens) — batch NFT metadata.
• getContractMetadata(contractAddress) / getContractMetadataBatch(contractAddresses) — contract-level metadata.
• getNftsForOwner(owner, options?) — NFTs owned by address; options: pageKey, pageSize, omitMetadata, excludeFilters (e.g. SPAM), contractAddresses, etc.
• getNftsForOwnerIterator(owner, options?) — async iterator over all NFTs for owner (handles paging).
• getNftsForContract(contractAddress, options?) / getNftsForContractIterator(...) — all NFTs in a contract.
• getOwnersForNft(contractAddress, tokenId, options?) — owners of a token.
• getOwnersForContract(contractAddress, options?) — owners for a contract (with optional token balances).
• getContractsForOwner(owner, options?) — NFT contracts owned by address.
• getMintedNfts(owner, options?) — NFTs minted by owner.
• verifyNftOwnership(owner, contractAddresses) — check ownership for given contracts.

Transfers and Refresh

• getTransfersForOwner(owner, options?) / getTransfersForContract(contractAddress, options?) — transfer history.
• refreshNftMetadata(contractAddress, tokenId) — refresh cached metadata for one token.
• refreshContract(contractAddress) — enqueue full contract metadata refresh.

Spam and Rarity

• isSpamContract(contractAddress) — whether contract is classified as spam.
• getSpamContracts() — list of spam contracts.
• reportSpam(contractAddress) — report contract as spam.
• isAirdropNft(contractAddress, tokenId) — whether token is marked as airdrop.
• computeRarity(contractAddress, tokenId) — rarity per attribute.
• summarizeNftAttributes(contractAddress) — attribute prevalence for contract.

Sales and Floor Price

• getFloorPrice(contractAddress) — floor price by marketplace.
• getNftSales(options) — NFT sales from on-chain marketplaces.
• searchContractMetadata(keyword) — search ERC-721/1155 contract metadata by keyword.

Pagination

Responses return pageKey for the next page. Prefer getNftsForOwnerIterator / getNftsForContractIterator when iterating over all results.

for await (const nft of alchemy.nft.getNftsForOwnerIterator('vitalik.eth', { omitMetadata: false })) {
  console.log(nft.contract.address, nft.tokenId, nft.media);
}

Key Points

• SDK uses omitMetadata (vs REST withMetadata), pageKey (vs nextToken/startToken), and renames "Collection" to "Contract" in method names.
• Token ID is normalized to integer string on BaseNft/Nft.
• Filter spam with excludeFilters: [NftExcludeFilters.SPAM] in get options.

<!-- Source references:

• sources/alchemy/docs-md/classes/NftNamespace.md
• sources/alchemy/docs-md/README.md

-->

Notify Namespace

alchemy.notify provides CRUD for Alchemy Notify webhooks (address activity, NFT activity, mined/dropped transactions, custom GraphQL). Requires authToken in AlchemySettings (from Alchemy Dashboard, Notify tab).

Methods

• getAllWebhooks() — list all webhooks for the team.
• getAddresses(webhookId) — addresses tracked for an Address Activity webhook.
• getNftFilters(webhookId) — NFT filters for an NFT Activity webhook.
• createWebhook(url, type, params) — create webhook; type from WebhookType (e.g. ADDRESS_ACTIVITY, NFT_ACTIVITY, MINED_TRANSACTION, DROPPED_TRANSACTION, GRAPHQL); params type depends on webhook type.
• updateWebhook(webhookId, update) — update active status, addresses, or NFT filters.
• deleteWebhook(webhookId) — delete webhook.
• verifyConfig(config) — verify webhook config.
• getGraphqlQuery(webhookId) — get GraphQL query for a custom webhook.
• sendWebhookRequest(webhookId, ...) — trigger test request.

Usage

const alchemy = new Alchemy({ apiKey: '…', authToken: '…' });

const webhooks = await alchemy.notify.getAllWebhooks();
const addresses = await alchemy.notify.getAddresses(webhookId);

const newWebhook = await alchemy.notify.createWebhook(
  'https://your-server.com/webhook',
  WebhookType.ADDRESS_ACTIVITY,
  { addresses: ['0x…'], network: Network.ETH_MAINNET }
);
await alchemy.notify.updateWebhook(webhookId, { addresses: ['0x…', '0x…'] });
await alchemy.notify.deleteWebhook(webhookId);

Key Points

• authToken is required; Notify tab in Alchemy Dashboard.
• Not all networks are supported for Notify; check Alchemy docs.
• Webhook types: address activity, NFT activity, mined/dropped transactions, custom GraphQL.

<!-- Source references:

• sources/alchemy/docs-md/classes/NotifyNamespace.md
• sources/alchemy/docs-md/README.md

-->

Portfolio Namespace

alchemy.portfolio provides multi-wallet, multi-network views of fungible tokens, NFTs, collections, and transactions. Requires authToken in AlchemySettings (from Alchemy Dashboard).

Methods

• getTokensByWallet(addresses) — fungible tokens (native + ERC-20) for multiple wallet/network pairs. addresses: array of { address, network } (limit 2 pairs, max 15 networks each).
• getTokenBalancesByWallet(addresses, includeNativeTokens?) — token balances by wallet/network.
• getNftsByWallet(addresses, withMetadata?, pageKey?, pageSize?) — NFTs for multiple wallet/network pairs.
• getNftCollectionsByWallet(addresses, withMetadata?, pageKey?, pageSize?) — NFT collections (contracts) per wallet/network.
• getTransactionsByWallet(addresses) — historical transactions (internal and external) for multiple wallet/network pairs.

Usage

const alchemy = new Alchemy({
  apiKey: '…',
  network: Network.ETH_MAINNET,
  authToken: '…',  // from Alchemy Dashboard
});

const tokens = await alchemy.portfolio.getTokensByWallet([
  { address: '0x…', network: Network.ETH_MAINNET },
  { address: '0x…', network: Network.POLYGON_MAINNET },
]);
const nfts = await alchemy.portfolio.getNftsByWallet([
  { address: 'vitalik.eth', network: Network.ETH_MAINNET },
], true, undefined, 50);
const txs = await alchemy.portfolio.getTransactionsByWallet([
  { address: '0x…', network: Network.ETH_MAINNET },
]);

Key Points

• authToken is required; get it from the Alchemy Dashboard.
• addresses is an array of PortfolioAddress (address + network); limits apply (e.g. 2 pairs, 15 networks per pair).
• Use pageKey and pageSize for paginated NFT/collection responses.

<!-- Source references:

• sources/alchemy/docs-md/classes/PortfolioNamespace.md
• sources/alchemy/docs-md/README.md

-->

Transact Namespace

alchemy.transact provides transaction simulation (asset changes or full execution), sending transactions, and private transaction submission (e.g. Flashbots). It also aliases common core methods for convenience.

Simulation

• simulateAssetChanges(transaction) — simulate and return list of asset changes (native/ERC-20/NFT).
• simulateExecution(transaction) — full simulation: internal calls, logs, ABI-decoded results.
• simulateAssetChangesBundle(transactions) — simulate a list of txs in sequence; returns asset changes.
• simulateExecutionBundle(transactions) — same but full execution trace per tx.

Sending and Waiting

• sendTransaction(signedTxHex) — send standard transaction.
• getTransaction(txHash) — get transaction by hash.
• waitForTransaction(txHash, confirmations?, timeout?) — wait until mined and return receipt.
• estimateGas(transaction) — gas estimate (alias of core).

Private Transactions (Flashbots)

• sendPrivateTransaction(signedTxHex, options?) — send private tx (e.g. Flashbots); options can specify inclusion/maxBlock, etc.
• cancelPrivateTransaction(transactionHash) — cancel a private tx (must be signed by same key as submitter). Fast-mode txs cannot be cancelled.
• getMaxPriorityFeePerGas(blockTag?) — get suggested max priority fee.

Usage

const alchemy = new Alchemy();

// Simulate before sending
const changes = await alchemy.transact.simulateAssetChanges({
  to: '0x…',
  data: '0x…',
  from: '0x…',
});
const trace = await alchemy.transact.simulateExecution({ to: '0x…', data: '0x…' });

// Send and wait
const hash = await alchemy.transact.sendTransaction(signedHex);
const receipt = await alchemy.transact.waitForTransaction(hash);

// Private tx
await alchemy.transact.sendPrivateTransaction(signedHex);
await alchemy.transact.cancelPrivateTransaction(hash);

Key Points

• Use simulation to validate state changes or debug before sending.
• Bundle methods run transactions in sequence; useful for multi-step flow checks.
• Private tx cancellation only works for the same signing key and non–fast-mode txs.

<!-- Source references:

• sources/alchemy/docs-md/classes/TransactNamespace.md
• sources/alchemy/docs-md/README.md

-->

WebSocket Namespace

alchemy.ws provides subscription APIs compatible with Ethers.js WebSocketProvider, plus Alchemy-specific subscription types. The SDK handles reconnection and backfills missed events (up to ~120 blocks).

Methods

• on(eventNameOrFilter, listener) — subscribe; returns subscription handle.
• once(eventNameOrFilter, listener) — subscribe for next event only.
• off(eventName, listener?) — remove listener(s) for event.
• removeAllListeners() — remove all listeners.
• listenerCount(eventName?) — count listeners (Promise).
• listeners(eventName?) — array of listeners (Promise).

Event Names

Standard Ethers events: 'block', 'pending', 'error', etc. Alchemy-specific: use AlchemySubscription enum (e.g. PENDING_TRANSACTIONS, MINED_TRANSACTIONS) and pass an object with method and optional filters.

Usage

import { Alchemy, AlchemySubscription } from 'alchemy-sdk';

const alchemy = new Alchemy();

// Standard block events
alchemy.ws.on('block', blockNumber => console.log('block', blockNumber));

// Alchemy pending transactions (optionally filtered)
alchemy.ws.on(
  { method: AlchemySubscription.PENDING_TRANSACTIONS, toAddress: 'vitalik.eth' },
  res => console.log(res)
);

// One-time
alchemy.ws.once(
  { method: AlchemySubscription.PENDING_TRANSACTIONS },
  res => console.log(res)
);

alchemy.ws.removeAllListeners();

Key Points

• Resilient delivery: events that arrive while the socket is down are backfilled after reconnect (within ~120 blocks).
• Outgoing requests over a down socket are retried on reconnect; still implement error handling.
• Use AlchemySubscription for Alchemy-specific subscription types; filter with toAddress, fromAddress, etc. in the options object.

<!-- Source references:

• sources/alchemy/docs-md/classes/WebSocketNamespace.md
• sources/alchemy/docs-md/README.md
• sources/alchemy/docs-md/enums/AlchemySubscription.md

-->