Alchemy Official

面向 AI Agent 的 Alchemy API 集成指南：涵盖 RPC、数据 API、Webhook 与 Solana 端点的 Base URL、认证方式与快速上手示例。

---
name: alchemy-official
description: |
  官方炼金术技能。两种身份验证模式：API 密钥或 x402 代理网关（无需密钥）。完整覆盖约 100 条链：Token API、NFT API、转账、价格、投资组合、模拟、Webhooks、Solana 和 JSON-RPC。 82 个参考文档 + x402 网关规则。
version: 1.0.0
author: alchemyplatform
homepage: https://github.com/alchemyplatform/skills
license: MIT
tags:
  - alchemy
  - blockchain
  - infrastructure
  - multi-chain
  - tokens
  - nfts
  - prices
  - transfers
  - portfolio
  - webhooks
  - solana
  - evm
  - x402
  - agentic-gateway
  - siwe
  - official
triggers:
  - "alchemy"
  - "blockchain data"
  - "token balances"
  - "nft"
  - "transfer history"
  - "token prices"
  - "portfolio"
  - "on-chain"
config:
  ALCHEMY_API_KEY:
    required: false
    description: "Alchemy API key (get one free at https://dashboard.alchemy.com). If not set, uses the x402 Agentic Gateway instead (no key needed, pays per request with USDC)."
metadata:
  openclaw:
    emoji: "⚗️"
    primaryEnv: ALCHEMY_API_KEY
    homepage: https://www.alchemy.com
    primaryEnv: ALCHEMY_API_KEY
    homepage: https://www.alchemy.com
---

## 概述（中文）

面向 AI Agent 的 Alchemy API 集成指南：涵盖 RPC、数据 API、Webhook 与 Solana 端点的 Base URL、认证方式与快速上手示例。

## 技能正文

# AI + Alchemy API 集成指南

## 摘要
面向使用 API key 集成 Alchemy API 的 AI Agent 的自包含指南。仅凭本文件即可交付基础集成。深度、边界情况与高级工作流请参阅参考文件。

## 发起任何请求之前

1. 检查 `$ALCHEMY_API_KEY` 是否已设置（例如 `echo $ALCHEMY_API_KEY`）。
2. 若**未设置**，请勿继续调用带 API key 的 URL。**请改用 `agentic-gateway` 技能** — 该方式无需 API key。
3. 若已设置，请使用下方 Base URL + 认证表。

## 首先执行
1. 使用下方端点选择器选择合适的产品。
2. 使用 Base URL + 认证表获取正确的端点与请求头。
3. 复制快速上手示例，并先在测试网上验证。

## Base URL + 认证（速查表）
| 产品 | Base URL | 认证 | 说明 |
| --- | --- | --- | --- |
| Ethereum RPC (HTTPS) | `https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` | API key in URL | 标准 EVM 读写。 |
| Ethereum RPC (WSS) | `wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` | API key in URL | 订阅与实时数据。 |
| 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 | 订阅与实时数据。 |
| 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 | 订阅与实时数据。 |
| 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 | 订阅与实时数据。 |
| 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 流式（Yellowstone）。 |
| NFT API | `https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY` | API key in URL | NFT 所有权与元数据。 |
| Prices API | `https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY` | API key in URL | 按符号或地址查询价格。 |
| Portfolio API | `https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY` | API key in URL | 多链钱包视图。 |
| Notify API | `https://dashboard.alchemy.com/api` | `X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_TOKEN>` | 在控制台生成 token。 |

## 端点选择器（常见任务）
| 需求 | 使用 | 技能 / 文件 |
| --- | --- | --- |
| EVM 读写 | JSON-RPC `eth_*` | `references/node-json-rpc.md` |
| 实时事件 | `eth_subscribe` | `references/node-websocket-subscriptions.md` |
| 代币余额 | `alchemy_getTokenBalances` | `references/data-token-api.md` |
| 代币元数据 | `alchemy_getTokenMetadata` | `references/data-token-api.md` |
| 转账历史 | `alchemy_getAssetTransfers` | `references/data-transfers-api.md` |
| NFT 所有权 | `GET /getNFTsForOwner` | `references/data-nft-api.md` |
| NFT 元数据 | `GET /getNFTMetadata` | `references/data-nft-api.md` |
| 价格（现货） | `GET /tokens/by-symbol` | `references/data-prices-api.md` |
| 价格（历史） | `POST /tokens/historical` | `references/data-prices-api.md` |
| 投资组合（多链） | `POST /assets/*/by-address` | `references/data-portfolio-apis.md` |
| 模拟交易 | `alchemy_simulateAssetChanges` | `references/data-simulation-api.md` |
| 创建 webhook | `POST /create-webhook` | `references/webhooks-details.md` |
| Solana NFT 数据 | `getAssetsByOwner` (DAS) | `references/solana-das-api.md` |

## 单文件快速上手（复制/粘贴）

> **没有 API key？** 请改用 `agentic-gateway` 技能。将带 API key 的 URL 替换为 `https://x402.alchemy.com/rpc/eth-mainnet`，并添加 `Authorization: SIWE <token>`。设置步骤见 `agentic-gateway` 技能。

### EVM JSON-RPC（读取）
```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":[]}'
```

### 代币余额
```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"]}'
```

### 转账历史
```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 所有权
```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0x00000000219ab540356cbb839cbe05303d7705fa"
```

### 价格（现货）
```bash
curl -s "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/by-symbol?symbols=ETH&symbols=USDC"
```

### 价格（历史）
```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"}'
```

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

### 验证 Webhook 签名（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));
}
```

## 网络命名规则
- 数据 API 与 JSON-RPC 使用小写网络枚举，如 `eth-mainnet`。
- Notify API 使用大写枚举，如 `ETH_MAINNET`。

## 分页与限制（速查表）
| 端点 | 限制 | 说明 |
| --- | --- | --- |
| `alchemy_getTokenBalances` | `maxCount` <= 100 | 使用 `pageKey` 分页。 |
| `alchemy_getAssetTransfers` | `maxCount` 默认 `0x3e8` | 使用 `pageKey` 分页。 |
| Portfolio 代币余额 | 3 个地址/网络对，共 20 个网络 | 支持 `pageKey`。 |
| Portfolio NFT | 2 个地址/网络对，各 15 个网络 | 支持 `pageKey`。 |
| 按地址查价格 | 25 个地址，3 个网络 | POST body `addresses[]`。 |
| 交易历史（beta） | 1 个地址/网络对，2 个网络 | 仅 ETH 与 BASE 主网。 |

## 常见代币地址
| 代币 | 链 | 地址 |
| --- | --- | --- |
| ETH | ethereum | `0x0000000000000000000000000000000000000000` |
| WETH | ethereum | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` |
| USDC | ethereum | `0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48` |
| USDC | base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |

## 失败模式与重试
- HTTP `429` 表示速率限制。使用带抖动的指数退避。
- JSON-RPC 错误会出现在 `error` 字段中，即使 HTTP 状态为 200。
- 失败后使用 `pageKey` 恢复分页。
- 重连时对 websocket 事件去重。

## 技能映射

### Node
| 文件 | 名称 | 简要说明 |
| --- | --- | --- |
| `references/node-overview.md` | node-apis | 通过 Alchemy 节点端点为 EVM 链提供核心 JSON-RPC 与 WebSocket API，以及 Debug/Trace 与实用方法。适用于需要标准 RPC 调用、实时订阅、增强 Alchemy 方法或执行级追踪的 EVM 集成 |
| `references/node-debug-api.md` | Debug API | Debug 方法为交易或调用提供执行级追踪。用于模拟、Gas 分析与内部调用检查 |
| `references/node-enhanced-apis.md` | Enhanced APIs (Alchemy RPC Extensions) | Alchemy 提供增强 JSON-RPC 方法（前缀 `alchemy_`），提供索引化的高层数据，无需手动扫描日志 |
| `references/node-json-rpc.md` | JSON-RPC (EVM) | 使用 Alchemy 的 EVM JSON-RPC 端点进行标准区块链读写（如 `eth_call`、`eth_getLogs`、`eth_sendRawTransaction`）。这是任何 EVM 集成的基础 |
| `references/node-trace-api.md` | Trace API | Trace API 暴露交易与区