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=
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://.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: | 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: moonpay
• Source: moonpay/skills
• License: MIT
• Homepage: https://www.moonpay.com/agents

Install and usage instructions live in the source repository linked above.