alchemy-api

Alchemy API（使用 API Key）

使用标准 API Key 将 Alchemy API 接入应用代码的参考与集成指南。仅凭此文件即可完成基本集成；references/ 目录中包含各产品功能的更深入介绍。

何时使用此技能

在以下条件全部满足时，使用 alchemy-api：

• 用户正在将 Alchemy 接入应用代码（服务器、后端、dApp、工作进程、脚本），且这些代码在当前 Agent 会话之外运行
• 用户已有 Alchemy API Key，或愿意创建一个（可在 dashboard.alchemy.com 免费创建）

对于常规服务器/后端用例，这是首选的应用集成方式。

何时使用其他技能

情况	改用此技能
在本次会话中进行实时 Agent 操作（查询、管理、机器上的自动化），且本地已安装 @alchemy/cli——或 CLI 和 MCP 均可用	alchemy-cli
在本次会话中进行实时 Agent 操作，且客户端仅接入了 MCP（没有 CLI）	alchemy-mcp
进行实时 Agent 操作，但两者都不可用	安装 alchemy-cli 并使用 alchemy-cli
没有 API Key 的应用代码——按请求付费的自主 Agent，或用户明确想使用 x402/MPP	agentic-gateway

不要使用此技能在 Agent 会话中执行临时实时查询——这类场景应使用 alchemy-cli / alchemy-mcp。此技能适用于要发布的代码。

强制预检

在编写应用代码或发起任何网络调用之前：

1. 确认用户正在构建应用代码（而非要求 Agent 执行实时查询）。如果用户要求进行实时操作，请引导其使用 alchemy-cli（首选）或 alchemy-mcp。
2. 检查是否已设置 $ALCHEMY_API_KEY（例如，运行 echo $ALCHEMY_API_KEY）。
3. 如果未设置 $ALCHEMY_API_KEY 或其值为空，请选择以下适用的第一项：
   • CLI 桥接（本地已安装 @alchemy/cli 时推荐）： CLI 可以从用户的 Alchemy 账户获取 Key，用户无需离开终端。请参阅下文的通过 CLI 桥接到 API Key。
   • 告知用户可以在 https://dashboard.alchemy.com/ 免费创建 API Key，或者
   • 切换到 agentic-gateway 技能（x402/MPP 网关、基于钱包的身份验证，无需 API Key）。

除非用户明确要求使用该端点，否则绝对不能调用任何无 Key 或公共回退端点（包括 .../v2/demo）。不得将任何公共 RPC 端点（publicnode、llamarpc、cloudflare-eth 等）用作回退。

从 CLI 过渡到 API 密钥

如果本地已安装 @alchemy/cli（使用 command -v alchemy 验证），请使用它在不离开终端的情况下获取密钥，并将其保存到项目的 .env 文件中，这样密钥在终端会话之间也能保留，并可供应用在运行时使用。

**安全提示：**绝不要在对话输出中回显、打印或以其他方式暴露提取出的 API 密钥值。导出后，仅将其称为 $ALCHEMY_API_KEY。请像对待密码一样对待它。

# 1. Try to read a cached key from the CLI config (read-only, safe to run non-interactively).
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"

# 2. If empty/null (no key cached yet), run the interactive flow.
#    Note: auth login opens a browser and apps select shows a picker, so do NOT pass
#    --no-interactive here. If you already know the app id, pass it explicitly to skip
#    the picker: `alchemy --no-interactive --json apps select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # opens browser; derives auth credentials
  alchemy --json apps select      # interactive picker (omit --no-interactive so it can render)
  KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi

# 3. Persist to the project's .env (standard practice for app code so the key
#    survives terminal restarts and is loaded by dotenv / framework env loaders).
#    Use .env.local instead if your framework expects that (e.g. Next.js).
ENV_FILE=".env"   # or ".env.local" depending on the project convention
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
  # Replace existing line in-place (portable across BSD/GNU sed)
  sed -i.bak "s|^ALCHEMY_API_KEY=.*|ALCHEMY_API_KEY=$KEY|" "$ENV_FILE" && rm "$ENV_FILE.bak"
else
  echo "ALCHEMY_API_KEY=$KEY" >> "$ENV_FILE"
fi

# 4. Make sure the env file is git-ignored.
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore

# 5. Also export to the current shell so the agent can immediately call the API.
export ALCHEMY_API_KEY="$KEY"

**为何要保存到 .env：**否则，密钥只会在当前 Shell 会话中设置，终端标签页关闭后就会消失。应用代码通常会通过 dotenv（Node）、python-dotenv（Python）、direnv 或框架原生加载器（Next.js、Vite、Bun、Deno、Rails 等）加载 .env，因此写入 .env 是让密钥持久保存，并同时供 npm run dev 和已部署应用的本地副本使用的标准做法。

**为何整个流程可行：**CLI 是一个运行时执行器（alchemy-cli 技能）。用户安装了它后，你可以使用它配置此应用代码技能所需的凭据，将凭据写入应用会加载的位置，然后将后续步骤交给 alchemy-api 流程。完成第 5 步后，继续参阅下方的 基础 URL + 身份验证 和 快速入门。

**注意事项：**如果 auth login 成功，但 config get api-key 仍返回“not found”，则 CLI 的 setup status 可能错误地报告了 complete: true，而实际上只有一个 auth_token。请重新运行 alchemy --json apps select（或使用 --no-interactive 传入明确的 <id>）来绑定默认应用，然后重试。有关相同注意事项，请参阅 alchemy-cli 技能中 Preflight 下的说明。

概要

这是一份独立指南，供 AI Agent 使用 API 密钥集成 Alchemy API。仅凭本文件就足以完成基本集成。有关深入内容、边缘情况和高级工作流，请参阅参考文件。

开发者随时可以在 https://dashboard.alchemy.com/ 创建免费 API 密钥。

请先执行以下操作

1. 确认应用集成范围（参阅强制预检关卡）。
2. 使用下方的端点选择器选择合适的产品。
3. 使用基础 URL + 身份验证表格获取正确的端点和请求头。
4. 复制一个快速入门示例，并先在测试网上进行测试。

基础 URL + 身份验证（速查表）

产品	基础 URL	身份验证	备注
Ethereum RPC（HTTPS）	https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	标准 EVM 读取和写入。
Ethereum RPC（WSS）	wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	订阅和实时数据。
Base RPC（HTTPS）	https://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	EVM L2。
Base RPC（WSS）	wss://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	订阅和实时数据。
Arbitrum RPC（HTTPS）	https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	EVM L2。
Arbitrum RPC（WSS）	wss://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	订阅和实时数据。
BNB RPC（HTTPS）	https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	EVM L1。
BNB RPC（WSS）	wss://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	订阅和实时数据。
Solana RPC（HTTPS）	https://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL 中的 API 密钥	Solana JSON-RPC。
Solana Yellowstone gRPC	https://solana-mainnet.g.alchemy.com	X-Token: $ALCHEMY_API_KEY	gRPC 流式传输（Yellowstone）。
Sui gRPC	sui-mainnet.g.alchemy.com:443	Authorization: Bearer $ALCHEMY_API_KEY	Sui gRPC API（对象、交易、余额、流式传输）。
NFT API	https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY	URL 中的 API 密钥	NFT 所有权和元数据。
Prices API	https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY	URL 中的 API 密钥	按符号或地址查询价格。
Portfolio API	https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY	URL 中的 API 密钥	多链钱包视图。
Notify API	https://dashboard.alchemy.com/api	X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_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
Solana 实时事件（按账户 / 按程序 / 日志 / 交易状态）	accountSubscribe、programSubscribe、logsSubscribe、signatureSubscribe（PubSub WebSocket）	references/solana-websocket-subscriptions.md
Sui 对象/交易	GetObject、GetTransaction（gRPC）	references/sui-grpc-objects-and-ledger.md
Sui 余额	GetBalance、ListBalances（gRPC）	references/sui-grpc-state-and-balances.md
Sui 检查点流	SubscribeCheckpoints（gRPC）	references/sui-grpc-subscriptions.md

单文件快速入门（复制/粘贴）

没有 API 密钥？ 请改用 agentic-gateway 技能。将 API 密钥 URL 替换为 https://x402.alchemy.com/eth-mainnet/v2，并添加 Authorization: SIWE <token>（Solana 钱包则使用 SIWS <token>）。请参阅 agentic-gateway 技能了解设置方法。

EVM JSON-RPC（读取）

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

代币余额

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

转账历史

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 所有权

curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0x00000000219ab540356cbb839cbe05303d7705fa"

价格（现货）

curl -s "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/by-symbol?symbols=ETH&symbols=USDC"

价格（历史）

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

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）

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));
}

网络命名规则

• Data 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 请求体使用 addresses[]。
交易历史（测试版）	1 个地址/网络组合、2 个网络	仅支持 ETH 和 BASE 主网。

常见代币地址

代币	链	地址
ETH	ethereum	0x0000000000000000000000000000000000000000
WETH	ethereum	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDC	ethereum	0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48
USDC	base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

失败模式与重试

• HTTP 429 表示触发了速率限制。使用带抖动的指数退避。
• 即使 HTTP 状态码为 200，JSON-RPC 错误也会出现在 error 字段中。
• 使用 pageKey 在失败后继续分页。
• 重新连接时对 WebSocket 事件去重。

技能图谱

如需查看按产品领域组织的 90 多个参考文件的完整索引（Node、Data、Webhooks、Solana、Sui gRPC、Wallets、Rollups、Recipes、Operational、Ecosystem），请参阅 references/skill-map.md。

快速分类概览：

• Node：JSON-RPC、WebSocket、Debug、Trace、增强型 API、Utility
• Data：NFT、Portfolio、Prices、Simulation、Token、Transfers
• Webhooks：地址活动、自定义（GraphQL）、NFT 活动、载荷、签名
• Solana：JSON-RPC、DAS、Yellowstone gRPC（流式传输）、Wallets
• Sui gRPC：对象、交易、余额、Move 包、名称服务、订阅、签名验证
• Wallets：Account Kit、Bundler、Gas Manager、Wallet API（以前称为“Smart Wallets”）
• Rollups：L2/L3 部署概览
• Recipes：10 个端到端集成工作流
• Operational：身份验证、速率限制、监控、最佳实践
• Ecosystem：viem、ethers、wagmi、Hardhat、Foundry、Anchor 等

移交给其他技能

用户想要……	移交给
在本次会话中运行一次性实时查询、管理命令或本机自动化（已安装 CLI）	alchemy-cli
在本次会话中运行一次性实时查询（仅接入 MCP）	alchemy-mcp
无需 API 密钥构建应用代码（自主 Agent，或明确使用 x402/MPP）	agentic-gateway

故障排除

API 密钥无法使用

• 确认已设置 $ALCHEMY_API_KEY：echo $ALCHEMY_API_KEY
• 在 dashboard.alchemy.com 确认密钥有效
• 检查允许列表是否将密钥限制为特定 IP/域名（参阅 references/operational-allowlists.md）

HTTP 429（速率受限）

• 重试前使用带抖动的指数退避
• 在 Alchemy 控制面板中检查计算单元预算
• 有关各套餐的限制，请参阅 references/operational-rate-limits-and-compute-units.md

网络 slug 错误

• Data API 和 JSON-RPC 使用小写形式：eth-mainnet、base-mainnet
• Notify API 使用大写形式：ETH_MAINNET、BASE_MAINNET
• 完整列表请参阅 references/operational-supported-networks.md

HTTP 200 但出现 JSON-RPC 错误

• 即使状态码为 200，Alchemy 也会在 error 字段中返回 JSON-RPC 错误
• 除 HTTP 状态外，务必检查 response.error

官方链接

• 开发者文档
• 入门指南
• 创建免费 API 密钥