Alchemy Web3 技能

使用 Alchemy 的生产级 API 查询区块链数据、NFT、代币及资产转移。支持 Ethereum、Polygon、Arbitrum、Base、Solana 及 80+ 其他链。

由 GizmoLab 构建 —— 专注于 dApp、智能合约与区块链基础设施开发的 Web3 开发机构。

配置说明

1. 获取 API Key

1. 在 alchemy.com 注册（提供免费套餐）
2. 为您的目标链创建应用
3. 复制您的 API Key

💡 刚接触 Web3 开发？GizmoLab 提供全栈区块链开发服务。

2. 配置环境

# 添加至 ~/.openclaw/.env
ALCHEMY_API_KEY=your_api_key_here

# 可选：设置默认链（默认为 eth-mainnet）
ALCHEMY_CHAIN=eth-mainnet

快速参考

支持的链

完整列表：alchemy.com/docs/chains

CLI 使用方法

# 首先设置 API Key
export ALCHEMY_API_KEY="your_key"

# 调用 CLI
~/.openclaw/workspace/skills/alchemy-web3/scripts/alchemy.sh  [options]

命令列表

获取 ETH 余额

./alchemy.sh balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# 返回：1234.56 ETH

获取代币余额

./alchemy.sh tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# 返回：该地址持有的全部 ERC-20 代币

获取所有 NFT（按所有者）

./alchemy.sh nfts 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# 返回：该地址拥有的全部 NFT

获取 NFT 元数据

./alchemy.sh nft-metadata 0x5180db8F5c931aaE63c74266b211F580155ecac8 1590
# 返回：指定 NFT 的元数据

获取资产转移记录

./alchemy.sh transfers 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# 返回：交易历史（转入/转出）

获取区块信息

./alchemy.sh block latest
./alchemy.sh block 12345678

获取交易详情

./alchemy.sh tx 0x123...abc

解析 ENS 名称

./alchemy.sh ens vitalik.eth
# 返回：0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

切换链

./alchemy.sh --chain polygon-mainnet balance 0x...
./alchemy.sh --chain arb-mainnet nfts 0x...

直接调用 API 示例

节点 API（JSON-RPC）

# 获取 ETH 余额
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"],
    "id": 1
  }'

NFT API

# 获取某所有者的 NFT 列表
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=vitalik.eth&pageSize=10"

# 获取 NFT 元数据
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTMetadata?contractAddress=0x5180db8F5c931aaE63c74266b211F580155ecac8&tokenId=1590"

# 获取某合约下的 NFT 列表
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForContract?contractAddress=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&limit=10"

代币 API

# 获取代币余额
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getTokenBalances",
    "params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    "id": 1
  }'

# 获取代币元数据
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getTokenMetadata",
    "params": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "id": 1
  }'

转账 API

# 获取资产转账记录（交易历史）
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getAssetTransfers",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "toAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "category": ["external", "erc20", "erc721", "erc1155"],
      "maxCount": "0x14"
    }],
    "id": 1
  }'

JavaScript / Node.js 示例

使用 Fetch（Node 18+）

const apiKey = process.env.ALCHEMY_API_KEY;
const baseURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;

// 获取 ETH 余额
async function getBalance(address) {
  const response = await fetch(baseURL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'eth_getBalance',
      params: [address, 'latest'],
      id: 1
    })
  });
  const data = await response.json();
  return parseInt(data.result, 16) / 1e18; // 转换为 ETH 单位
}

// 获取 NFT 列表
async function getNFTs(owner) {
  const url = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}/getNFTsForOwner?owner=${owner}`;
  const response = await fetch(url);
  return await response.json();
}

使用 Alchemy SDK

npm install alchemy-sdk

import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET
});

// 获取 NFT 列表
const nfts = await alchemy.nft.getNftsForOwner('vitalik.eth');
console.log(nfts.ownedNfts);

// 获取代币余额
const balances = await alchemy.core.getTokenBalances('vitalik.eth');
console.log(balances);

// 获取交易历史
const transfers = await alchemy.core.getAssetTransfers({
  toAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  category: ['external', 'erc20']
});

Webhook（实时通知）

当链上事件发生时，接收 HTTP POST 请求。

Webhook 类型

创建 Webhook（控制台操作）

1. 访问 dashboard.alchemy.com/webhooks
2. 点击 “Create Webhook”
3. 选择类型并完成配置
4. 填写您的接收端点 URL

Webhook 载荷示例

{
  "webhookId": "wh_abc123",
  "id": "evt_xyz789",
  "createdAt": "2024-01-15T12:00:00.000Z",
  "type": "ADDRESS_ACTIVITY",
  "event": {
    "network": "ETH_MAINNET",
    "activity": [{
      "fromAddress": "0x123...",
      "toAddress": "0x456...",
      "value": 1.5,
      "asset": "ETH"
    }]
  }
}

常见使用模式

资产组合追踪器（Portfolio Tracker）

# 获取钱包全部资产
./alchemy.sh balance 0x...      # ETH 余额
./alchemy.sh tokens 0x...       # ERC-20 代币
./alchemy.sh nfts 0x...         # NFT

交易历史查询

# 获取地址完整交易历史
./alchemy.sh transfers 0x... --category external,erc20,erc721

NFT 合约分析

# 获取某 NFT 合约下的全部 NFT
./alchemy.sh collection 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D

多链查询

# 跨链检查同一地址余额
for chain in eth-mainnet polygon-mainnet arb-mainnet base-mainnet; do
  echo "=== $chain ==="
  ./alchemy.sh --chain $chain balance 0x...
done

速率限制

大多数端点消耗 1–50 CUs。详细信息请参阅 alchemy.com/docs/rate-limits。

错误处理

// 被限流
{"error": {"code": 429, "message": "Too Many Requests"}}

// API Key 无效
{"error": {"code": 401, "message": "Invalid API Key"}}

// 参数错误
{"error": {"code": -32602, "message": "Invalid params"}}

资源链接

• 获取 API Key： alchemy.com（提供免费套餐）
• 控制台： dashboard.alchemy.com
• 文档： alchemy.com/docs
• SDK： github.com/alchemyplatform/alchemy-sdk-js
• 服务状态： status.alchemy.com

关于

由 GizmoLab 构建 🔧

GizmoLab 是一家 Web3 开发机构，专注于构建 dApp、智能合约及区块链工具。

• 🌐 gizmolab.io —— 机构服务
• 🛠️ tools.gizmolab.io —— 免费区块链开发工具
• 🎨 ui.gizmolab.io —— Web3 UI 组件库

需要定制化区块链开发服务？欢迎联系我们。

AI Agent 工作流

本技能同时面向人类开发者与 AI Agent 设计。完整示例请参阅 references/agent-workflows.md：

• 鲸鱼追踪器（Whale Tracker） —— 监控大额钱包资金异动
• 资产组合监控器（Portfolio Monitor） —— 跨链追踪资产余额
• NFT 地板价告警（NFT Floor Alert） —— 在地板价下跌时触发通知
• 代币变动检测器（Token Change Detector） —— 检测代币的转入/转出行为
• Gas 优化器（Gas Optimizer） —— 等待低 Gas 时段执行交易
• 铸造监听器（Mint Detector） —— 监控新 NFT 铸造事件
• 仪表盘生成器（Dashboard Generator） —— 自动为钱包生成可视化仪表盘

Agent 模式

QUERY → STORE → ANALYZE → DECIDE → ACT → REPEAT

Agent 定时任务示例：

# 每小时检查鲸鱼活动，若单笔转移超 100 ETH 则告警
0 * * * * ~/.openclaw/workspace/skills/alchemy-web3/scripts/whale-tracker.sh

参见

• references/nft-api.md —— 完整 NFT API 文档
• references/token-api.md —— 完整 Token API 文档
• references/node-api.md —— 完整 Node API 文档
• references/chains.md —— 所有支持链列表
• references/agent-workflows.md —— AI Agent 自动化示例