alchemy-api

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From moonpay/skills, MIT.

More from moonpay/skills