在应用代码中接入 Alchemy API：有/可创建…

当需要在当前 agent 会话之外的应用代码（服务端、后端、dApp、worker、脚本）中集成 Alchemy API，并且可提供或创建 Alchemy API key 时使用。

适用场景

解决思路

1. 确认用户是在编写运行于当前 agent 会话之外的应用代码（server、backend、dApp、worker、script）；若只是实时查询/管理/本地自动化，改用 `alchemy-cli`（首选）或 `alchemy-mcp`，不要用本技能。
2. 检查环境变量：执行 `echo $ALCHEMY_API_KEY`，确认 key 已设置且非空。
3. 若 `$ALCHEMY_API_KEY` 未设置或为空，按顺序尝试：优先使用 CLI bridge（本地安装了 `@alchemy/cli` 时）；否则告知用户可在 https://dashboard.alchemy.com/ 创建免费 API key；或切换到 `agentic-gateway` 技能（x402/MPP 网关、钱包认证、无需 API key）。
4. 禁止调用任何无 key 或公共 fallback 端点（包括 `.../v2/demo`），除非用户明确要求该端点；也禁止用 publicnode、llamarpc、cloudflare-eth 等公共 RPC 作为 fallback。
5. 若本地有 `@alchemy/cli`，用 `command -v alchemy` 验证；用它获取 key 并持久化到项目 `.env`，使 key 跨终端会话存在且应用运行时可用。
6. CLI bridge 第 1 步：尝试从 CLI 配置读取缓存 key（只读、可非交互）：`KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"`。
7. 若 `$KEY` 为空或 `null`，运行交互流程：`alchemy auth login`（打开浏览器）；`alchemy --json apps select`（交互选择，不要加 `--no-interactive`；已知 app id 时用 `alchemy --no-interactive --json apps select <id>` 跳过选择器）；然后 `KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"`。
8. 将 key 持久化到项目 `.env`（若框架要求如 Next.js 则用 `.env.local`）：`ENV_FILE=".env"`；`touch "$ENV_FILE"`；若文件已有 `^ALCHEMY_API_KEY=` 行，用 `sed -i.bak "s|^ALCHEMY_API_KEY=.*|ALCHEMY_API_KEY=$KEY|" "$ENV_FILE" && rm "$ENV_FILE.bak"` 原地替换；否则 `echo "ALCHEMY_API_KEY=$KEY" >> "$ENV_FILE"`。
9. 确保 env 文件被 git 忽略：`grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore`。
10. 同时导出到当前 shell，方便 agent 立即调用 API：`export ALCHEMY_API_KEY="$KEY"`。
11. 安全要求：绝不在对话输出中 echo、print 或泄露提取出的 API key 值；导出后只以 `$ALCHEMY_API_KEY` 引用；按密码同等对待。
12. 若 `auth login` 成功但 `config get api-key` 仍返回 not found，可能是 CLI 的 `setup status` 错误报告 `complete: true` 且只有 `auth_token`；重新运行 `alchemy --json apps select`（或显式传 `<id>` 配合 `--no-interactive`）绑定默认 app，再重试。
13. 使用 Endpoint selector 选择产品：EVM 读写用 JSON-RPC `eth_*`；实时事件用 `eth_subscribe`；token 余额用 `alchemy_getTokenBalances`；token 元数据用 `alchemy_getTokenMetadata`；转账历史用 `alchemy_getAssetTransfers`；NFT 所有权用 `GET /getNFTsForOwner`；NFT 元数据用 `GET /getNFTMetadata`；现货价格用 `GET /tokens/by-symbol`；历史价格用 `POST /tokens/historical`；多链 Portfolio 用 `POST /assets/*/by-address`；模拟交易用 `alchemy_simulateAssetChanges`；创建 webhook 用 `POST /create-webhook`；Solana NFT 数据用 `getAssetsByOwner`（DAS）；Solana 实时事件用 `accountSubscribe`、`programSubscribe`、`logsSubscribe`、`signatureSubscribe`（PubSub WebSocket）；Sui 对象/交易用 `GetObject`、`GetTransaction`（gRPC）；Sui 余额用 `GetBalance`、`ListBalances`（gRPC）；Sui checkpoint 流用 `SubscribeCheckpoints`（gRPC）。
14. 按 Base URLs + auth 表构造请求：Ethereum RPC HTTPS 用 `https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`，API key 在 URL；Ethereum RPC WSS 用 `wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`；Base RPC HTTPS/WSS 用 `https://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` 和 `wss://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`；Arbitrum RPC HTTPS/WSS 用 `https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` 和 `wss://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`；BNB RPC HTTPS/WSS 用 `https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY` 和 `wss://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`；Solana RPC HTTPS 用 `https://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`；Solana Yellowstone gRPC 用 `https://solana-mainnet.g.alchemy.com` 加 `X-Token: $ALCHEMY_API_KEY`；Sui gRPC 用 `sui-mainnet.g.alchemy.com:443` 加 `Authorization: Bearer $ALCHEMY_API_KEY`；NFT API 用 `https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY`；Prices API 用 `https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY`；Portfolio API 用 `https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY`；Notify API 用 `https://dashboard.alchemy.com/api` 加 `X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_TOKEN>`（在 dashboard 生成 token）。
15. 复制 Quickstart 示例并先在 testnet 测试；例如 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":[]}'`。
16. Token balances quickstart：`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"]}'`。
17. Transfer history quickstart：`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"}]}'`。
18. NFT ownership quickstart：`curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0x00000000219ab540356cbb839cbe05303d7705fa"`。
19. 现货价格 quickstart：`curl -s "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/by-symbol?symbols=ETH&symbols=USDC"`。
20. 历史价格 quickstart：`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"}'`。
21. 创建 Notify webhook quickstart：`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"]}'`。
22. 验证 webhook 签名（Node）：使用 `crypto.createHmac("sha256", secret).update(rawBody).digest("hex")`，再用 `crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature))` 比较。
23. 遵守网络命名规则：Data APIs 和 JSON-RPC 用小写 network enum，如 `eth-mainnet`；Notify API 用大写 enum，如 `ETH_MAINNET`。
24. 遵守分页和限制：`alchemy_getTokenBalances` 的 `maxCount` <= 100，用 `pageKey` 分页；`alchemy_getAssetTransfers` 的 `maxCount` 默认 `0x3e8`，用 `pageKey` 分页；Portfolio token balances 每次 3 个 address/network 对，最多 20 个网络，支持 `pageKey`；Portfolio NFTs 每次 2 个 address/network 对，每对最多 15 个网络，支持 `pageKey`；Prices by address 最多 25 个地址、3 个网络，POST body 用 `addresses[]`；Transactions history（beta）每次 1 个 address/network 对、2 个网络，仅 ETH 和 BASE mainnets。
25. 需要常用代币地址时使用：ETH(ethereum) `0x0000000000000000000000000000000000000000`；WETH(ethereum) `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`；USDC(ethereum) `0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48`；USDC(base) `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`。
26. 处理失败与重试：HTTP `429` 表示限流，使用带 jitter 的指数退避；JSON-RPC 即使 HTTP 200 也可能在 `error` 字段返回错误；用 `pageKey` 在失败后恢复分页；websocket 重连时对事件去重。
27. 排查 API key 不工作：确认 `$ALCHEMY_API_KEY` 已设置（`echo $ALCHEMY_API_KEY`）；在 dashboard.alchemy.com 确认 key 有效；检查 allowlists 是否限制 key 到特定 IP/域名（见 `references/operational-allowlists.md`）。
28. 排查 HTTP 429：重试前使用带 jitter 的指数退避；在 Alchemy dashboard 检查 compute unit 预算；见 `references/operational-rate-limits-and-compute-units.md`。
29. 排查网络 slug 错误：Data APIs 和 JSON-RPC 用小写如 `eth-mainnet`、`base-mainnet`；Notify API 用大写如 `ETH_MAINNET`、`BASE_MAINNET`；完整列表见 `references/operational-supported-networks.md`。
30. 排查 HTTP 200 的 JSON-RPC 错误：始终同时检查 `response.error` 和 HTTP 状态。
31. 按技能交接：当前会话一次性实时查询/管理/本地自动化 → `alchemy-cli`（CLI 已安装）；仅 MCP 接入 → `alchemy-mcp`；无 API key 构建应用代码（自主 agent 或显式 x402/MPP）→ `agentic-gateway`。
32. 需要更深覆盖时查阅 `references/` 目录和 `references/skill-map.md` 中的 90+ 参考文件；快速类别包括 Node、Data、Webhooks、Solana、Sui gRPC、Wallets、Rollups、Recipes、Operational、Ecosystem。

适用边界 · 注意事项

• 当前 agent 会话中的实时查询、管理命令或本地自动化：应使用 `alchemy-cli`（首选）或 `alchemy-mcp`，不要用本技能。
• 应用代码但没有 API key，或自主 agent 按请求付费/显式使用 x402/MPP：应使用 `agentic-gateway`。
• 不要用无 key/public fallback 端点（如 `.../v2/demo`、publicnode、llamarpc、cloudflare-eth）替代，除非用户明确要求。