Moonpay Official Alchemy Api

---
name: alchemy-api
description: 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, token balances, NFT ownership or metadata, transfer history, token prices, portfolio data, transaction simulation, webhooks, Solana RPC, or any Alchemy product integration. Covers base URLs, authentication, endpoint selection, pagination, and common patterns.
tags: [alchemy, blockchain, evm, solana, rpc, nft, api-key, web3]
license: MIT
compatibility: Requires network access and $ALCHEMY_API_KEY environment variable. Works across Claude.ai, Claude Code, and API.
metadata:
  author: alchemyplatform
  version: "1.0"
---
# 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)

```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"]}'
```

> 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](https://www.alchemy.com/docs)
- [Create a free API key](https://dashboard.alchemy.com)