Alchemy API

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)

Endpoint Selector (Top Tasks)

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)

Common Token Addresses

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

For the complete index of all 82+ reference files organized by product area (Node, Data, Webhooks, Solana, Wallets, Rollups, Recipes, Operational, Ecosystem), see references/skill-map.md.

Quick category overview:

• Node: JSON-RPC, WebSocket, Debug, Trace, Enhanced APIs, Utility
• Data: NFT, Portfolio, Prices, Simulation, Token, Transfers
• Webhooks: Address Activity, Custom (GraphQL), NFT Activity, Payloads, Signatures
• Solana: JSON-RPC, DAS, Yellowstone gRPC (streaming), Wallets
• Wallets: Account Kit, Bundler, Gas Manager, Smart Wallets
• Rollups: L2/L3 deployment overview
• Recipes: 10 end-to-end integration workflows
• Operational: Auth, Rate Limits, Monitoring, Best Practices
• Ecosystem: viem, ethers, wagmi, Hardhat, Foundry, Anchor, and more

Troubleshooting

API key not working

• Verify $ALCHEMY_API_KEY is set: echo $ALCHEMY_API_KEY
• Confirm the key is valid at dashboard.alchemy.com
• Check if allowlists restrict the key to specific IPs/domains (see references/operational-allowlists.md)

HTTP 429 (Rate Limited)

• Use exponential backoff with jitter before retrying
• Check your compute unit budget in the Alchemy dashboard
• See references/operational-rate-limits-and-compute-units.md for limits per plan

Wrong network slug

• Data APIs and JSON-RPC use lowercase: eth-mainnet, base-mainnet
• Notify API uses uppercase: ETH_MAINNET, BASE_MAINNET
• See references/operational-supported-networks.md for the full list

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

Official Links

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