alchemy-api

name	alchemy-api
description	Requires $ALCHEMY_API_KEY to be set. If no API key is available, use the agentic-gateway skill instead — it requires no API key and lets agents authenticate autonomously with a wallet. Quick-start guide and root index for integrating Alchemy APIs using an API key. Covers base URLs, authentication, endpoint selection, and common patterns across all Alchemy products.
metadata	{"author":"alchemyplatform","version":"1.0"}

AI + Alchemy API Integration Guide

Mandatory Routing Gate (Hard Requirement)

If ALCHEMY_API_KEY is unset or empty, you MUST use the agentic-gateway skill. You MUST NOT call any keyless or public fallback (including .../v2/demo) unless the user explicitly asks for that endpoint. Execute no network calls before this gate is evaluated.

Escape hatch: Only re-evaluate the routing gate if the user explicitly requests to switch to the alchemy-api skill with an API key. A key appearing in the environment or conversation does not automatically trigger a switch — the user must ask for it.

Duplicate resolution: If this skill is installed both locally and globally, the local copy overrides the global copy. Do not mix behavior from different copies.

Required Preflight Check

Before the first network call, internally evaluate:

1. Is ALCHEMY_API_KEY present and non-empty?
2. If no, switch to the agentic-gateway skill immediately. Demo and public endpoints are disallowed.

Do not output this check to the user.

Summary

A self-contained guide for AI agents integrating Alchemy APIs using an API key. This file alone should be enough to ship a basic integration. Use the reference files for depth, edge cases, and advanced workflows.

Before Making Any Request

1. Check if $ALCHEMY_API_KEY is set (e.g., echo $ALCHEMY_API_KEY).
2. If not set, do NOT proceed with API-key URLs. Use the agentic-gateway skill instead — it requires no API key.
3. If set, use the Base URLs + Auth table below.

Do This First

1. Choose the right product using the Endpoint Selector below.
2. Use the Base URLs + Auth table for the correct endpoint and headers.
3. Copy a Quickstart example and test against a testnet first.

Base URLs + Auth (Cheat Sheet)

Product	Base URL	Auth	Notes
Ethereum RPC (HTTPS)	https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Standard EVM reads and writes.
Ethereum RPC (WSS)	wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Subscriptions and realtime.
Base RPC (HTTPS)	https://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	EVM L2.
Base RPC (WSS)	wss://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Subscriptions and realtime.
Arbitrum RPC (HTTPS)	https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	EVM L2.
Arbitrum RPC (WSS)	wss://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Subscriptions and realtime.
BNB RPC (HTTPS)	https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	EVM L1.
BNB RPC (WSS)	wss://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Subscriptions and realtime.
Solana RPC (HTTPS)	https://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	Solana JSON-RPC.
Solana Yellowstone gRPC	https://solana-mainnet.g.alchemy.com	X-Token: $ALCHEMY_API_KEY	gRPC streaming (Yellowstone).
NFT API	https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY	API key in URL	NFT ownership and metadata.
Prices API	https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY	API key in URL	Prices by symbol or address.
Portfolio API	https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY	API key in URL	Multi-chain wallet views.
Notify API	https://dashboard.alchemy.com/api	X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_TOKEN>	Generate token in dashboard.

Endpoint Selector (Top Tasks)

You need	Use this	Skill / File
EVM read/write	JSON-RPC eth_*	references/node-json-rpc.md
Realtime events	eth_subscribe	references/node-websocket-subscriptions.md
Token balances	alchemy_getTokenBalances	references/data-token-api.md
Token metadata	alchemy_getTokenMetadata	references/data-token-api.md
Transfers history	alchemy_getAssetTransfers	references/data-transfers-api.md
NFT ownership	GET /getNFTsForOwner	references/data-nft-api.md
NFT metadata	GET /getNFTMetadata	references/data-nft-api.md
Prices (spot)	GET /tokens/by-symbol	references/data-prices-api.md
Prices (historical)	POST /tokens/historical	references/data-prices-api.md
Portfolio (multi-chain)	POST /assets/*/by-address	references/data-portfolio-apis.md
Simulate tx	alchemy_simulateAssetChanges	references/data-simulation-api.md
Create webhook	POST /create-webhook	references/webhooks-details.md
Solana NFT data	getAssetsByOwner (DAS)	references/solana-das-api.md

One-File Quickstart (Copy/Paste)

No API key? Use the agentic-gateway skill instead. Replace API-key URLs with https://x402.alchemy.com/rpc/eth-mainnet and add Authorization: SIWE <token>. See the agentic-gateway skill for setup.

EVM JSON-RPC (Read)

curl -s https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Token Balances

curl -s https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"alchemy_getTokenBalances","params":["0x00000000219ab540356cbb839cbe05303d7705fa"]}'

Transfer History

curl -s https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"alchemy_getAssetTransfers","params":[{"fromBlock":"0x0","toBlock":"latest","toAddress":"0x00000000219ab540356cbb839cbe05303d7705fa","category":["erc20"],"withMetadata":true,"maxCount":"0x3e8"}]}'

NFT Ownership

curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0x00000000219ab540356cbb839cbe05303d7705fa"

Prices (Spot)

curl -s "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/by-symbol?symbols=ETH&symbols=USDC"

Prices (Historical)

curl -s -X POST "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/historical" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"ETH","startTime":"2024-01-01T00:00:00Z","endTime":"2024-01-02T00:00:00Z"}'

Create Notify Webhook

curl -s -X POST "https://dashboard.alchemy.com/api/create-webhook" \
  -H "Content-Type: application/json" \
  -H "X-Alchemy-Token: $ALCHEMY_NOTIFY_AUTH_TOKEN" \
  -d '{"network":"ETH_MAINNET","webhook_type":"ADDRESS_ACTIVITY","webhook_url":"https://example.com/webhook","addresses":["0x00000000219ab540356cbb839cbe05303d7705fa"]}'

Verify Webhook Signature (Node)

import crypto from "crypto";

export function verify(rawBody: string, signature: string, secret: string) {
  const hmac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature));
}

Network Naming Rules

• Data APIs and JSON-RPC use lowercase network enums like eth-mainnet.
• Notify API uses uppercase enums like ETH_MAINNET.

Pagination + Limits (Cheat Sheet)

Endpoint	Limit	Notes
alchemy_getTokenBalances	maxCount <= 100	Use pageKey for pagination.
alchemy_getAssetTransfers	maxCount default 0x3e8	Use pageKey for pagination.
Portfolio token balances	3 address/network pairs, 20 networks total	pageKey supported.
Portfolio NFTs	2 address/network pairs, 15 networks each	pageKey supported.
Prices by address	25 addresses, 3 networks	POST body addresses[].
Transactions history (beta)	1 address/network pair, 2 networks	ETH and BASE mainnets only.

Common Token Addresses

Token	Chain	Address
ETH	ethereum	0x0000000000000000000000000000000000000000
WETH	ethereum	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDC	ethereum	0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48
USDC	base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Failure Modes + Retries

• HTTP 429 means rate limit. Use exponential backoff with jitter.
• JSON-RPC errors come in error fields even with HTTP 200.
• Use pageKey to resume pagination after failures.
• De-dupe websocket events on reconnect.

Skill Map

Node

File	Name	Short Description
references/node-overview.md	node-apis	Core JSON-RPC and WebSocket APIs for EVM chains via Alchemy node endpoints, plus Debug/Trace and utility methods. Use when building EVM integrations that need standard RPC calls, real-time subscriptions, enhanced Alchemy methods, or execution-level tracing
references/node-debug-api.md	Debug API	Debug methods provide execution-level traces for a transaction or call. Use these for simulation, gas profiling, and internal call inspection
references/node-enhanced-apis.md	Enhanced APIs (Alchemy RPC Extensions)	Alchemy provides enhanced JSON-RPC methods (prefixed with alchemy_) that offer indexed, higher-level data without manual log scanning
references/node-json-rpc.md	JSON-RPC (EVM)	Use Alchemy's EVM JSON-RPC endpoints for standard blockchain reads and writes (e.g., eth_call, eth_getLogs, eth_sendRawTransaction). This is the baseline for any EVM integration
references/node-trace-api.md	Trace API	Trace APIs expose internal call data and state changes for transactions and blocks. Useful for analytics and auditing
references/node-utility-api.md	Utility API	Convenience RPC methods that reduce round trips for common tasks like bulk transaction receipt retrieval
references/node-websocket-subscriptions.md	WebSocket Subscriptions	Use WebSockets for real-time blockchain events without polling. Best for pending transactions, new blocks, and logs

Data

File	Name	Short Description
references/data-overview.md	data-apis	Higher-level Alchemy APIs for asset discovery, wallet analytics, transfer history, NFT data, and token pricing. Use when you need indexed blockchain data without raw RPC log scanning, including token balances, NFT ownership, portfolio views, price feeds, and transaction simulation
references/data-nft-api.md	NFT API	Query NFT ownership, metadata, collections, and contract-level info via Alchemy's NFT REST APIs
references/data-portfolio-apis.md	Portfolio APIs	Portfolio APIs provide consolidated wallet views (tokens, NFTs, and transaction history) across multiple networks in single requests
references/data-prices-api.md	Prices API	Query token prices for current and historical data using Alchemy's Prices API
references/data-simulation-api.md	Simulation API	Simulate transactions before submitting them on-chain. Use this for safety checks and user previews
references/data-token-api.md	Token API	Fetch token balances, metadata, and allowances without manual contract calls. Token API methods are exposed as Alchemy JSON-RPC methods
references/data-transfers-api.md	Transfers API	Query historical transfers across ERC-20/721/1155 and native transfers without manual log scanning

Webhooks

File	Name	Short Description
references/webhooks-overview.md	webhooks	Push-based delivery of blockchain events via Alchemy Notify API. Use when you need real-time notifications for address activity, NFT transfers, or custom on-chain events instead of polling. Covers webhook creation, payload formats, signature verification, and filtering
references/webhooks-address-activity.md	Address Activity Webhooks	Address activity webhooks notify you when specified addresses send or receive assets
references/webhooks-custom-webhooks.md	Custom Webhooks (GraphQL)	Custom webhooks allow flexible event filtering using a GraphQL query hosted by Alchemy
references/webhooks-details.md	Webhooks Overview (Notify)	Notify webhooks push blockchain events to your server so you don't need to poll. They are ideal for near real-time pipelines
references/webhooks-nft-activity.md	NFT Activity Webhooks	Receive notifications for NFT transfers, mints, and burns for specified contracts or collections
references/webhooks-verify-signatures.md	Verify Webhook Signatures	Always verify webhook signatures to ensure payloads are authentic and untampered
references/webhooks-webhook-payloads.md	Webhook Payloads	Webhook payloads include event metadata plus event-specific fields. Treat them as untrusted input and validate carefully
references/webhooks-webhook-types.md	Webhook Types	Webhook types determine what events you receive and how they're filtered

Solana

File	Name	Short Description
references/solana-overview.md	solana	Solana-specific APIs including standard JSON-RPC, Digital Asset Standard (DAS) for NFTs and compressed assets, and wallet integration. Use when building Solana applications that need RPC access, NFT/asset queries, or Solana wallet tooling. For high-throughput streaming, see the yellowstone-grpc skill
references/solana-das-api.md	Solana DAS (Digital Asset Standard) API	DAS provides normalized access to Solana NFT and compressed asset data
references/solana-grpc-best-practices.md	Yellowstone Best Practices	Practical guidance to keep Yellowstone consumers reliable and efficient
references/solana-grpc-details.md	Yellowstone gRPC Overview	Yellowstone gRPC provides high-throughput Solana data streams for blocks, transactions, accounts, and slots. Use this for real-time indexing at scale
references/solana-grpc-examples.md	Yellowstone Examples	Minimal examples for connecting and subscribing. The exact client depends on your gRPC stack
references/solana-grpc-overview.md	yellowstone-grpc	High-throughput Solana event streaming via Yellowstone gRPC. Use when you need near real-time block, transaction, account, or slot streams at scale. Covers subscription configuration, filtering, backpressure handling, and reconnection strategies
references/solana-grpc-subscribe-accounts.md	Subscribe Accounts	Account streams deliver updates when account state changes
references/solana-grpc-subscribe-blocks.md	Subscribe Blocks	Block streams provide full block data with transactions and metadata
references/solana-grpc-subscribe-request.md	Subscribe Request	The subscribe request configures what streams and filters you want from Yellowstone
references/solana-grpc-subscribe-slots.md	Subscribe Slots	Slot updates provide heartbeat-style updates and can be used to track chain progress
references/solana-grpc-subscribe-transactions.md	Subscribe Transactions	Transaction streams deliver raw or decoded transaction data in near real-time
references/solana-rpc.md	Solana JSON-RPC	Standard Solana JSON-RPC endpoints for account, program, and transaction data
references/solana-wallets.md	Solana Wallet Integration	High-level guidance for integrating Solana wallets and signing transactions

Wallets

File	Name	Short Description
references/wallets-overview.md	wallets	Integration guide for Alchemy Wallets and smart wallet tooling including Account Kit, account abstraction, bundler, gas manager, and paymaster. Use when building wallet onboarding flows, sponsoring gas, or integrating smart wallets into your application
references/wallets-account-kit.md	Account Kit	Account Kit is Alchemy's wallet SDK for onboarding users and managing wallet UX. Use it for embedded wallet flows or seamless authentication
references/wallets-bundler.md	Bundler	A bundler aggregates and submits account abstraction user operations. Use this when integrating smart wallets
references/wallets-details.md	Wallets Overview	Alchemy Wallets tooling helps developers embed or integrate wallets with minimal infrastructure. This section is intentionally basic and focuses on integration touchpoints
references/wallets-gas-manager.md	Gas Manager	Gas Manager (paymaster) enables gas sponsorship and cost control for smart wallet flows
references/wallets-smart-wallets.md	Smart Wallets	Smart wallets (account abstraction) enable programmable accounts with features like session keys, batched transactions, and gas sponsorship
references/wallets-solana-notes.md	Solana Wallet Notes	Solana wallet integration differs from EVM. Use Solana-specific tooling and RPC semantics
references/wallets-supported-chains.md	Wallet Supported Chains	Wallet tooling may support a subset of chains compared to raw RPC. Always confirm chain support before launch
references/wallets-wallet-apis.md	Wallet APIs	High-level wallet APIs enable programmatic wallet operations such as signing, transaction preparation, or account management. This guide stays minimal and focuses on integration awareness

Rollups

File	Name	Short Description
references/rollups-overview.md	rollups	High-level overview of Alchemy Rollups for deploying custom L2/L3 chains. Use when exploring rollup deployment options or understanding what Alchemy Rollups offers. This section is intentionally minimal as rollup deployment is not a typical API integration task
references/rollups-details.md	Rollups Overview	Alchemy Rollups provide infrastructure for teams building their own rollup chains. This section is intentionally high-level because rollup deployment typically requires a sales or solutions process rather than a purely programmatic integration

Recipes

File	Name	Short Description
references/recipes-overview.md	recipes	End-to-end runnable workflows that combine multiple Alchemy APIs to achieve real product goals. Includes token balances, NFT queries, transfer history, portfolio views, price feeds, transaction simulation, pending tx monitoring, and webhook setup. Use when you need a complete integration pattern, not just a single API call
references/recipes-get-nft-metadata.md	Recipe: Get NFT Metadata	Fetch NFT metadata for a token or collection using Alchemy NFT endpoints
references/recipes-get-nft-ownership.md	Recipe: Get NFT Ownership	Retrieve wallet-level NFT ownership with pagination and filtering
references/recipes-get-portfolio.md	Recipe: Get Full Portfolio	Build a consolidated wallet portfolio view across supported networks
references/recipes-get-prices-current-historical.md	Recipe: Get Current and Historical Prices	Query spot and historical token prices for analytics and UI displays
references/recipes-get-token-balances.md	Recipe: Get Token Balances	Get ERC-20 token balances for a wallet and handle paginated responses
references/recipes-get-token-metadata.md	Recipe: Get Token Metadata	Resolve token metadata (symbol, decimals, logo) for contract addresses
references/recipes-get-transfers-history.md	Recipe: Get Transfer History	Pull historical transfer activity with category and block-range filters
references/recipes-simulate-transaction.md	Recipe: Simulate a Transaction	Simulate transaction effects before submission for risk checks and UX previews
references/recipes-subscribe-pending-txs.md	Recipe: Subscribe to Pending Transactions	Stream pending transactions in real time via WebSocket subscriptions
references/recipes-webhook-address-activity.md	Recipe: Address Activity Webhook	Configure address activity webhooks and verify delivered signatures

Operational

File	Name	Short Description
references/operational-overview.md	operational	Operational guidance for securely and reliably integrating Alchemy APIs. Covers API key management, JWT authentication, rate limits, compute unit budgeting, monitoring, alerting, and production readiness. Use before deploying any Alchemy integration to production
references/operational-alerts.md	Alerts	Set alerts to catch rate limit issues, spikes in usage, or webhook failures
references/operational-allowlists.md	Allowlists	Allowlisting restricts API key usage to approved IPs or domains, reducing key abuse risk
references/operational-auth-and-keys.md	Auth and API Keys	Alchemy uses API keys for most products. Keep keys server-side and scope them to environments
references/operational-best-practices.md	Production Best Practices	Operational checklist for deploying Alchemy-backed services
references/operational-dashboard-tools.md	Dashboard Tools	Use the Alchemy dashboard to create apps, manage keys, track usage, and configure webhooks
references/operational-jwt-and-header-auth.md	JWT and Header-Based Auth	Some Alchemy APIs use header-based auth (e.g., JWTs or API tokens) instead of API keys in URLs. Use this for server-side integrations where you need stronger access control
references/operational-pricing-and-plans.md	Pricing and Plans	Alchemy plans are primarily based on compute units and product access. Choose a plan that matches your expected traffic and data needs
references/operational-rate-limits-and-compute-units.md	Rate Limits and Compute Units	Alchemy meters usage using compute units (CU) and enforces per-key rate limits. Plan your request patterns accordingly
references/operational-request-logs.md	Request Logs	Request logs help debug failed calls and monitor latency
references/operational-roles-and-sso.md	Roles and SSO	Team access control ensures API keys and billing settings are managed safely
references/operational-sandbox.md	Sandbox / Test Environment	Use testnets or a separate Alchemy app for safe development and QA
references/operational-supported-networks.md	Supported Networks	Alchemy supports multiple EVM and Solana networks. Always verify network availability in the dashboard for each product

Ecosystem

File	Name	Short Description
references/ecosystem-overview.md	ecosystem	Popular open-source libraries that pair well with Alchemy for building crypto applications. Covers EVM tools (viem, ethers, web3.js, wagmi, RainbowKit, Hardhat, Foundry) and Solana tools (solana/web3.js, spl-token, Anchor, Metaplex). Use when choosing or configuring a client library for your Alchemy integration
references/ecosystem-anchor.md	Anchor	Anchor is a Solana framework for building programs with a higher-level Rust and TypeScript SDK
references/ecosystem-ethers.md	Ethers.js	Ethers.js is a widely used Ethereum library for wallets, providers, and contract interactions
references/ecosystem-foundry.md	Foundry	Foundry is a fast, Rust-based Ethereum toolchain for testing and deployment
references/ecosystem-hardhat.md	Hardhat	Hardhat is a popular Ethereum development environment for compiling, testing, and deploying contracts
references/ecosystem-metaplex.md	Metaplex	Metaplex provides NFT standards and tooling on Solana, including metadata and token standards
references/ecosystem-rainbowkit.md	RainbowKit	RainbowKit is a wallet connection UI kit commonly used with wagmi
references/ecosystem-solana-web3js.md	@solana/web3.js	The primary JavaScript library for Solana RPC, transactions, and accounts
references/ecosystem-spl-token.md	SPL Token	SPL Token is the standard token program on Solana and includes tools for minting and token account management
references/ecosystem-viem.md	Viem	Viem is a modern TypeScript Ethereum client library with strong types and a functional API
references/ecosystem-wagmi.md	wagmi	wagmi provides React hooks for Ethereum, commonly used with wallet connectors and UI kits
references/ecosystem-web3js.md	Web3.js	Web3.js is a long-standing Ethereum JavaScript library for providers and contracts

Official Links

• Developer docs
• Get Started guide
• Create a free API key