AI + Alchemy API Integration Guide#

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)#

ProductBase URLAuthNotesEthereum RPC (HTTPS)https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLStandard EVM reads and writes.Ethereum RPC (WSS)wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLSubscriptions and realtime.Base RPC (HTTPS)https://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLEVM L2.Base RPC (WSS)wss://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLSubscriptions and realtime.Arbitrum RPC (HTTPS)https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLEVM L2.Arbitrum RPC (WSS)wss://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLSubscriptions and realtime.BNB RPC (HTTPS)https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLEVM L1.BNB RPC (WSS)wss://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLSubscriptions and realtime.Solana RPC (HTTPS)https://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEYAPI key in URLSolana JSON-RPC.Solana Yellowstone gRPChttps://solana-mainnet.g.alchemy.com``X-Token: $ALCHEMY_API_KEYgRPC streaming (Yellowstone).NFT APIhttps://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEYAPI key in URLNFT ownership and metadata.Prices APIhttps://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEYAPI key in URLPrices by symbol or address.Portfolio APIhttps://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEYAPI key in URLMulti-chain wallet views.Notify APIhttps://dashboard.alchemy.com/api``X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_TOKEN>Generate token in dashboard.

Endpoint Selector (Top Tasks)#

You needUse thisSkill / FileEVM read/writeJSON-RPC eth_*``references/node-json-rpc.mdRealtime eventseth_subscribe``references/node-websocket-subscriptions.mdToken balancesalchemy_getTokenBalances``references/data-token-api.mdToken metadataalchemy_getTokenMetadata``references/data-token-api.mdTransfers historyalchemy_getAssetTransfers``references/data-transfers-api.mdNFT ownershipGET /getNFTsForOwner``references/data-nft-api.mdNFT metadataGET /getNFTMetadata``references/data-nft-api.mdPrices (spot)GET /tokens/by-symbol``references/data-prices-api.mdPrices (historical)POST /tokens/historical``references/data-prices-api.mdPortfolio (multi-chain)POST /assets/*/by-address``references/data-portfolio-apis.mdSimulate txalchemy_simulateAssetChanges``references/data-simulation-api.mdCreate webhookPOST /create-webhook``references/webhooks-details.mdSolana NFT datagetAssetsByOwner (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)#

bash

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#

bash

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#

bash

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#

bash

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

Prices (Spot)#

bash

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

Prices (Historical)#

bash

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#

bash

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)#

ts

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)#

EndpointLimitNotesalchemy_getTokenBalances``maxCount <= 100Use pageKey for pagination.alchemy_getAssetTransfers``maxCount default 0x3e8Use pageKey for pagination.Portfolio token balances3 address/network pairs, 20 networks totalpageKey supported.Portfolio NFTs2 address/network pairs, 15 networks eachpageKey supported.Prices by address25 addresses, 3 networksPOST body addresses[].Transactions history (beta)1 address/network pair, 2 networksETH and BASE mainnets only.

Common Token Addresses#

TokenChainAddressETHethereum0x0000000000000000000000000000000000000000WETHethereum0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2USDCethereum0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48USDCbase0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

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#

FileNameShort Descriptionreferences/node-overview.mdnode-apisCore 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 tracingreferences/node-debug-api.mdDebug APIDebug methods provide execution-level traces for a transaction or call. Use these for simulation, gas profiling, and internal call inspectionreferences/node-enhanced-apis.mdEnhanced APIs (Alchemy RPC Extensions)Alchemy provides enhanced JSON-RPC methods (prefixed with alchemy_) that offer indexed, higher-level data without manual log scanningreferences/node-json-rpc.mdJSON-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 integrationreferences/node-trace-api.mdTrace APITrace APIs expose internal call data and state changes for transactions and blocks. Useful for analytics and auditingreferences/node-utility-api.mdUtility APIConvenience RPC methods that reduce round trips for common tasks like bulk transaction receipt retrievalreferences/node-websocket-subscriptions.mdWebSocket SubscriptionsUse WebSockets for real-time blockchain events without polling. Best for pending transactions, new blocks, and logs

Data#

FileNameShort Descriptionreferences/data-overview.mddata-apisHigher-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 simulationreferences/data-nft-api.mdNFT APIQuery NFT ownership, metadata, collections, and contract-level info via Alchemy's NFT REST APIsreferences/data-portfolio-apis.mdPortfolio APIsPortfolio APIs provide consolidated wallet views (tokens, NFTs, and transaction history) across multiple networks in single requestsreferences/data-prices-api.mdPrices APIQuery token prices for current and historical data using Alchemy's Prices APIreferences/data-simulation-api.mdSimulation APISimulate transactions before submitting them on-chain. Use this for safety checks and user previewsreferences/data-token-api.mdToken APIFetch token balances, metadata, and allowances without manual contract calls. Token API methods are exposed as Alchemy JSON-RPC methodsreferences/data-transfers-api.mdTransfers APIQuery historical transfers across ERC-20/721/1155 and native transfers without manual log scanning

Webhooks#

FileNameShort Descriptionreferences/webhooks-overview.mdwebhooksPush-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 filteringreferences/webhooks-address-activity.mdAddress Activity WebhooksAddress activity webhooks notify you when specified addresses send or receive assetsreferences/webhooks-custom-webhooks.mdCustom Webhooks (GraphQL)Custom webhooks allow flexible event filtering using a GraphQL query hosted by Alchemyreferences/webhooks-details.mdWebhooks Overview (Notify)Notify webhooks push blockchain events to your server so you don't need to poll. They are ideal for near real-time pipelinesreferences/webhooks-nft-activity.mdNFT Activity WebhooksReceive notifications for NFT transfers, mints, and burns for specified contracts or collectionsreferences/webhooks-verify-signatures.mdVerify Webhook SignaturesAlways verify webhook signatures to ensure payloads are authentic and untamperedreferences/webhooks-webhook-payloads.mdWebhook PayloadsWebhook payloads include event metadata plus event-specific fields. Treat them as untrusted input and validate carefullyreferences/webhooks-webhook-types.mdWebhook TypesWebhook types determine what events you receive and how they're filtered

Solana#

FileNameShort Descriptionreferences/solana-overview.mdsolanaSolana-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 skillreferences/solana-das-api.mdSolana DAS (Digital Asset Standard) APIDAS provides normalized access to Solana NFT and compressed asset datareferences/solana-grpc-best-practices.mdYellowstone Best PracticesPractical guidance to keep Yellowstone consumers reliable and efficientreferences/solana-grpc-details.mdYellowstone gRPC OverviewYellowstone gRPC provides high-throughput Solana data streams for blocks, transactions, accounts, and slots. Use this for real-time indexing at scalereferences/solana-grpc-examples.mdYellowstone ExamplesMinimal examples for connecting and subscribing. The exact client depends on your gRPC stackreferences/solana-grpc-overview.mdyellowstone-grpcHigh-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 strategiesreferences/solana-grpc-subscribe-accounts.mdSubscribe AccountsAccount streams deliver updates when account state changesreferences/solana-grpc-subscribe-blocks.mdSubscribe BlocksBlock streams provide full block data with transactions and metadatareferences/solana-grpc-subscribe-request.mdSubscribe RequestThe subscribe request configures what streams and filters you want from Yellowstonereferences/solana-grpc-subscribe-slots.mdSubscribe SlotsSlot updates provide heartbeat-style updates and can be used to track chain progressreferences/solana-grpc-subscribe-transactions.mdSubscribe TransactionsTransaction streams deliver raw or decoded transaction data in near real-timereferences/solana-rpc.mdSolana JSON-RPCStandard Solana JSON-RPC endpoints for account, program, and transaction datareferences/solana-wallets.mdSolana Wallet IntegrationHigh-level guidance for integrating Solana wallets and signing transactions

Wallets#

FileNameShort Descriptionreferences/wallets-overview.mdwalletsIntegration 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 applicationreferences/wallets-account-kit.mdAccount KitAccount Kit is Alchemy's wallet SDK for onboarding users and managing wallet UX. Use it for embedded wallet flows or seamless authenticationreferences/wallets-bundler.mdBundlerA bundler aggregates and submits account abstraction user operations. Use this when integrating smart walletsreferences/wallets-details.mdWallets OverviewAlchemy Wallets tooling helps developers embed or integrate wallets with minimal infrastructure. This section is intentionally basic and focuses on integration touchpointsreferences/wallets-gas-manager.mdGas ManagerGas Manager (paymaster) enables gas sponsorship and cost control for smart wallet flowsreferences/wallets-smart-wallets.mdSmart WalletsSmart wallets (account abstraction) enable programmable accounts with features like session keys, batched transactions, and gas sponsorshipreferences/wallets-solana-notes.mdSolana Wallet NotesSolana wallet integration differs from EVM. Use Solana-specific tooling and RPC semanticsreferences/wallets-supported-chains.mdWallet Supported ChainsWallet tooling may support a subset of chains compared to raw RPC. Always confirm chain support before launchreferences/wallets-wallet-apis.mdWallet APIsHigh-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#

FileNameShort Descriptionreferences/rollups-overview.mdrollupsHigh-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 taskreferences/rollups-details.mdRollups OverviewAlchemy 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#

FileNameShort Descriptionreferences/recipes-overview.mdrecipesEnd-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 callreferences/recipes-get-nft-metadata.mdRecipe: Get NFT MetadataFetch NFT metadata for a token or collection using Alchemy NFT endpointsreferences/recipes-get-nft-ownership.mdRecipe: Get NFT OwnershipRetrieve wallet-level NFT ownership with pagination and filteringreferences/recipes-get-portfolio.mdRecipe: Get Full PortfolioBuild a consolidated wallet portfolio view across supported networksreferences/recipes-get-prices-current-historical.mdRecipe: Get Current and Historical PricesQuery spot and historical token prices for analytics and UI displaysreferences/recipes-get-token-balances.mdRecipe: Get Token BalancesGet ERC-20 token balances for a wallet and handle paginated responsesreferences/recipes-get-token-metadata.mdRecipe: Get Token MetadataResolve token metadata (symbol, decimals, logo) for contract addressesreferences/recipes-get-transfers-history.mdRecipe: Get Transfer HistoryPull historical transfer activity with category and block-range filtersreferences/recipes-simulate-transaction.mdRecipe: Simulate a TransactionSimulate transaction effects before submission for risk checks and UX previewsreferences/recipes-subscribe-pending-txs.mdRecipe: Subscribe to Pending TransactionsStream pending transactions in real time via WebSocket subscriptionsreferences/recipes-webhook-address-activity.mdRecipe: Address Activity WebhookConfigure address activity webhooks and verify delivered signatures

Operational#

FileNameShort Descriptionreferences/operational-overview.mdoperationalOperational 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 productionreferences/operational-alerts.mdAlertsSet alerts to catch rate limit issues, spikes in usage, or webhook failuresreferences/operational-allowlists.mdAllowlistsAllowlisting restricts API key usage to approved IPs or domains, reducing key abuse riskreferences/operational-auth-and-keys.mdAuth and API KeysAlchemy uses API keys for most products. Keep keys server-side and scope them to environmentsreferences/operational-best-practices.mdProduction Best PracticesOperational checklist for deploying Alchemy-backed servicesreferences/operational-dashboard-tools.mdDashboard ToolsUse the Alchemy dashboard to create apps, manage keys, track usage, and configure webhooksreferences/operational-jwt-and-header-auth.mdJWT and Header-Based AuthSome 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 controlreferences/operational-pricing-and-plans.mdPricing and PlansAlchemy plans are primarily based on compute units and product access. Choose a plan that matches your expected traffic and data needsreferences/operational-rate-limits-and-compute-units.mdRate Limits and Compute UnitsAlchemy meters usage using compute units (CU) and enforces per-key rate limits. Plan your request patterns accordinglyreferences/operational-request-logs.mdRequest LogsRequest logs help debug failed calls and monitor latencyreferences/operational-roles-and-sso.mdRoles and SSOTeam access control ensures API keys and billing settings are managed safelyreferences/operational-sandbox.mdSandbox / Test EnvironmentUse testnets or a separate Alchemy app for safe development and QAreferences/operational-supported-networks.mdSupported NetworksAlchemy supports multiple EVM and Solana networks. Always verify network availability in the dashboard for each product

Ecosystem#

FileNameShort Descriptionreferences/ecosystem-overview.mdecosystemPopular 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 integrationreferences/ecosystem-anchor.mdAnchorAnchor is a Solana framework for building programs with a higher-level Rust and TypeScript SDKreferences/ecosystem-ethers.mdEthers.jsEthers.js is a widely used Ethereum library for wallets, providers, and contract interactionsreferences/ecosystem-foundry.mdFoundryFoundry is a fast, Rust-based Ethereum toolchain for testing and deploymentreferences/ecosystem-hardhat.mdHardhatHardhat is a popular Ethereum development environment for compiling, testing, and deploying contractsreferences/ecosystem-metaplex.mdMetaplexMetaplex provides NFT standards and tooling on Solana, including metadata and token standardsreferences/ecosystem-rainbowkit.mdRainbowKitRainbowKit is a wallet connection UI kit commonly used with wagmireferences/ecosystem-solana-web3js.md@solana/web3.jsThe primary JavaScript library for Solana RPC, transactions, and accountsreferences/ecosystem-spl-token.mdSPL TokenSPL Token is the standard token program on Solana and includes tools for minting and token account managementreferences/ecosystem-viem.mdViemViem is a modern TypeScript Ethereum client library with strong types and a functional APIreferences/ecosystem-wagmi.mdwagmiwagmi provides React hooks for Ethereum, commonly used with wallet connectors and UI kitsreferences/ecosystem-web3js.mdWeb3.jsWeb3.js is a long-standing Ethereum JavaScript library for providers and contracts

Official Links#

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