alchemy-api

name	alchemy-api
description	Integrates Alchemy blockchain APIs using an API key. Requires $ALCHEMY_API_KEY to be set; if unavailable, use the alchemy-agentic-gateway skill instead. Use when user asks about EVM JSON-RPC calls, token balances, NFT ownership or metadata, transfer history, token prices, portfolio data, transaction simulation, webhooks, Solana RPC, or any Alchemy product integration. Covers base URLs, authentication, endpoint selection, pagination, and common patterns.
tags	["alchemy","blockchain","evm","solana","rpc","nft","api-key","web3"]
license	MIT
compatibility	Requires network access and $ALCHEMY_API_KEY environment variable. Works across Claude.ai, Claude Code, and API.
metadata	{"author":"alchemyplatform","version":"1.0"}

AI + Alchemy API Integration Guide

Prerequisites

1. Create a free API key at https://dashboard.alchemy.com/
2. Export the key: export ALCHEMY_API_KEY=<your-key>
3. If no API key is available, use the alchemy-agentic-gateway skill instead (wallet-based auth).

Mandatory Routing Gate (Hard Requirement)

Before the first network call or implementation step, you MUST ask the user the following question and wait for an explicit answer:

Do you want to use an existing Alchemy API key, or should I use the agentic gateway flow instead?

If the user chooses the API key path, continue with this skill. If the user chooses the agentic gateway path, switch to the alchemy-agentic-gateway skill immediately and follow its existing wallet flow. If the user chooses the API key path but ALCHEMY_API_KEY is unset or empty, tell them they can create a free API key at https://dashboard.alchemy.com/ or switch to the alchemy-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.

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.
Arbitrum RPC (HTTPS)	https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	EVM L2.
BNB RPC (HTTPS)	https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	API key in URL	EVM L1.
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
EVM read/write	JSON-RPC eth_*
Realtime events	eth_subscribe (WebSocket)
Token balances	alchemy_getTokenBalances
Token metadata	alchemy_getTokenMetadata
Transfers history	alchemy_getAssetTransfers
NFT ownership	GET /getNFTsForOwner
NFT metadata	GET /getNFTMetadata
Prices (spot)	GET /tokens/by-symbol
Prices (historical)	POST /tokens/historical
Portfolio (multi-chain)	POST /assets/*/by-address
Simulate tx	alchemy_simulateAssetChanges
Create webhook	POST /create-webhook
Solana NFT data	getAssetsByOwner (DAS)

Full reference: https://www.alchemy.com/docs

One-File Quickstart (Copy/Paste)

No API key? Use the alchemy-agentic-gateway skill instead.

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"]}'

To verify webhook signatures, use HMAC-SHA256 with the webhook signing key from your dashboard. See https://www.alchemy.com/docs/webhooks for details.

Network Naming Rules

• Data APIs and JSON-RPC use lowercase network enums: eth-mainnet, base-mainnet
• Notify API uses uppercase enums: ETH_MAINNET, BASE_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[].

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.

Troubleshooting

API key not working

• Verify: echo $ALCHEMY_API_KEY
• Confirm the key is valid at https://dashboard.alchemy.com/
• Check if allowlists restrict the key to specific IPs/domains

HTTP 429 (Rate Limited)

• Use exponential backoff with jitter before retrying
• Check your compute unit budget in the Alchemy dashboard

Wrong network slug

• Data APIs and JSON-RPC use lowercase: eth-mainnet, base-mainnet
• Notify API uses uppercase: ETH_MAINNET, BASE_MAINNET

JSON-RPC error with HTTP 200

• Alchemy returns JSON-RPC errors inside the error field even with a 200 status code
• Always check response.error in addition to HTTP status

Related Skills

• alchemy-agentic-gateway — Access Alchemy APIs without an API key via x402 or MPP wallet auth

Official Links

• Developer docs
• Create a free API key