alchemy-api

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, to

SKILL.md

GitHub

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

Похожие навыки: other

limits-colimits

Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context polluti...

Автор: parcadei
3,392

ddttom-allaboutv2-claude-skills-block-collection-and-party

The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration p...

Автор: mattnigh
20

nodnarbnitram-claude-code-extensions-claude-skills-esphome-confi

This skill should be used when the user asks to "create an esphome config", "set up an esp32 device", "configure esphome...

Автор: mattnigh
20