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