alchemy-api

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