alchemy-cli

Alchemy CLI

在终端中使用 Alchemy CLI（@alchemy/cli）进行实时区块链查询、管理操作、交易签名和本地自动化。CLI 按链（evm、solana、xchain）和产品领域（wallet、app、webhook、auth、config）对命令进行分组，并且每个命令都提供结构化的 JSON 输出。

何时使用此技能

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

• 用户需要实时 Agent 操作——由 Agent 在当前会话中即时执行实时查询、分析、管理操作或本地自动化
• 本地已安装 @alchemy/cli，或者 CLI 和 MCP 服务均可用，或者两者都不可用（此时请安装 CLI——参见安装）

对于实时 Agent 操作，CLI 是首选的本地备用运行路径。不确定该使用 CLI 还是 MCP 时，优先选择 CLI。

何时使用其他技能

情况	改用此技能
MCP 已接入客户端，且本地未安装 CLI	alchemy-mcp
使用 Alchemy API 密钥构建在此 Agent 会话之外运行的应用代码	alchemy-api
构建不使用 API 密钥的应用代码，或构建需要自给自足的自主 Agent，或你明确想使用 x402/MPP	agentic-gateway

不要使用此技能编写生产应用代码——CLI 命令用于实时 Agent 操作，不用于嵌入已发布的软件。

安装

npm i -g @alchemy/cli

如果尚未安装 CLI，且用户需要实时 Agent 操作，请安装 CLI。不要退而使用原始 curl/HTTP 调用——这是 alchemy-api 所涵盖的 API 密钥路径。

初始化

在任何会话开始时运行此命令，以获取完整的命令规范（包括所有命令、标志、身份验证方法、错误代码和示例）：

alchemy --json --no-interactive agent-prompt

对于限定钱包范围的 Agent 操作，请使用范围更窄的规范，其中仅列出钱包、EVM、Solana 和跨链命令，以及会话签名器的能力集：

alchemy --json --no-interactive agent-prompt --scope wallet

CLI 尚未安装，但 Agent 需要获取相同规范时，可以使用无需身份验证的 npx 变体：

npx -y @alchemy/cli@latest --json --no-interactive agent-prompt --scope wallet

执行规则

• 每条命令都必须传入 --json --no-interactive
• 退出代码为 0 时，将 stdout 解析为 JSON
• 退出代码非零时，将 stderr 解析为 JSON
• 绝不要在不带 --json --no-interactive 的情况下直接运行 alchemy
• 如果存在可完成任务的 alchemy CLI 命令，绝不要使用 curl 或原始 HTTP——这属于 alchemy-api（API 密钥）路径，而非此技能
• 绝不要使用 CLI 生成生产应用代码；对于已发布的代码，请交由 alchemy-api 或 agentic-gateway 处理
• 对于链上操作（evm send、evm contract call、evm approve、evm swap、xchain bridge、solana send），先运行 alchemy --json --no-interactive wallet status --verify，确认会话仍有效，然后优先在广播前使用 --dry-run。将赞助策略（--gas-policy-id、--fee-policy-id）视为费用控制项，而非钱包支出限额。

预检

运行第一条命令前，先完成以下两项检查：

alchemy --json --no-interactive doctor
alchemy --json --no-interactive evm gas

doctor（别名：alchemy config status）会报告已配置的内容以及包含补救步骤的 nextCommands 列表。不要只根据其顶层 OK 状态作判断——目前存在一个已知的误报问题：它会显示会话已设置，但由于尚未从身份验证令牌派生 API 密钥，RPC 命令仍会失败并返回 AUTH_REQUIRED。

evm gas 是一项轻量级 RPC 冒烟测试，可检测此问题。如果返回 {"gasPrice": "0x...", ...}，则说明 RPC 已正确接通。如果返回 {"error": {"code": "AUTH_REQUIRED", ...}}，请运行 alchemy auth login（该命令会获取并保存 API 密钥）或 alchemy config set api-key <key>，然后重新运行 evm gas 进行确认。

如果 doctor 报告缺少配置，请先按其 nextCommands 处理，然后运行 evm gas 进行验证。

身份验证设置

最快的身份验证方式是通过浏览器登录：

alchemy auth login

对于无头环境（SSH、GitHub Codespaces、CI、沙盒），如果浏览器无法访问 CLI 的 localhost 回调，请强制使用 OAuth 2.0 设备授权授权流程：

alchemy auth login --device-code

普通的 alchemy auth 会自动检测非交互式会话，并自动切换到设备码模式。需要 @alchemy/cli 0.18.0 或更高版本。

此操作会打开浏览器、完成 OAuth 流程，并在内部配置 API 密钥（用于 RPC/Data）和 Admin API 访问权限。现在无需单独设置访问密钥——执行 alchemy auth login 后，管理命令（alchemy app ...）即可直接使用。

查看身份验证状态：alchemy auth status 退出登录：alchemy auth logout

其他身份验证方式

方法	配置命令	环境变量	用于
浏览器登录	alchemy auth login（无头环境下添加 --device-code）	--	所有命令（同时适用于 RPC/Data 和 Admin）
API 密钥	alchemy config set api-key <key>	ALCHEMY_API_KEY	RPC/Data 命令（evm rpc、evm data、evm tx、solana rpc 等）
Webhook 密钥	alchemy config set webhook-api-key <key>	ALCHEMY_WEBHOOK_API_KEY	webhook
Agent 钱包会话	alchemy wallet connect --mode session --instance-name <label>（在控制面板中批准）	--	evm send、evm contract call、evm approve、evm swap、xchain bridge、evm status、solana send、solana status、solana delegate
本地钱包	alchemy wallet connect --mode local（EVM 密钥使用 --import <path>）	--	与会话相同的由钱包签名的命令，可使用 --signer local 覆盖
x402 网关身份验证（Alchemy API 路径）	先执行 alchemy wallet connect --mode local --chain evm，再执行 alchemy config set x402 true	ALCHEMY_WALLET_KEY	启用 --x402 时的 RPC 和 Data 命令。这是通过钱包进行的 Alchemy API 身份验证，与 alchemy x402 request 不同（见下文）。
x402 支付（第三方 API）	alchemy wallet connect --mode local — 配置用于 x402 支付的签名者	--	alchemy x402 request <url>、alchemy x402 balance（根据 RFC 402，以 USDC 支付第三方 API）

alchemy evm network list / alchemy solana network list 和 alchemy version / update-check 无需身份验证。

选择默认应用

许多 app 子命令会对“默认应用”进行操作。如果错误响应中出现 APP_REQUIRED，请设置一个默认应用：

alchemy --json --no-interactive app select <id>
# or equivalently
alchemy --json --no-interactive config set app <id>

在 dashboard.alchemy.com 创建 Alchemy 账户。

任务与命令对照表

EVM — 链上读取

任务	命令
原生代币余额（ETH、MATIC……）	alchemy evm data balance <address>
交易详情	alchemy evm tx <hash>
交易回执	alchemy evm receipt <hash>
区块详情	alchemy evm block <number|latest>
Gas 价格	alchemy evm gas
事件日志	alchemy evm logs --address <addr> --from-block <n> --to-block <n>
原始 JSON-RPC	alchemy evm rpc <method> [params...]
Trace 方法	alchemy evm trace <method> [params...]
Debug 方法	alchemy evm debug <method> [params...]
合约 view/pure 调用	alchemy evm contract read <address> <function> [--args ...] [--abi-file <path>]

EVM — 数据 API

任务	命令
ERC-20 余额	alchemy evm data tokens balances <address>
ERC-20 余额（格式化）	alchemy evm data tokens balances <address> --metadata
代币元数据	alchemy evm data tokens metadata <contract>
代币授权额度	alchemy evm data tokens allowance --owner <addr> --spender <addr> --contract <addr>
列出持有的 NFT	alchemy evm data nfts <address> [--limit <n>] [--page-key <key>]
NFT 元数据	alchemy evm data nfts metadata --contract <addr> --token-id <id>
NFT 合约元数据	alchemy evm data nfts contract <address>
资产转移历史	alchemy evm data history <address> [--from-block <n>] [--to-block <n>] [--max-count <n>] [--page-key <key>]
按符号查询现货价格	alchemy evm data price symbol ETH,USDC
按地址查询现货价格	alchemy evm data price address --addresses '<json>'
历史价格	alchemy evm data price historical --body '<json>'
跨网络代币投资组合	alchemy evm data portfolio tokens --body '<json>'
按地址/网络组合查询代币余额	alchemy evm data portfolio token-balances --body '<json>'
跨网络 NFT 投资组合	alchemy evm data portfolio nfts --body '<json>'
按地址/网络组合查询 NFT 合约	alchemy evm data portfolio nft-contracts --body '<json>'

EVM — 模拟

任务	命令
模拟单笔交易（资产变动）	alchemy evm simulate asset-changes --tx '<json>' [--block-tag <tag>]
模拟单笔交易（执行跟踪）	alchemy evm simulate execution --tx '<json>' [--block-tag <tag>]
模拟交易捆绑包（资产变动）	alchemy evm simulate asset-changes-bundle --txs '<json-array>' [--block-tag <tag>]
模拟交易捆绑包（执行跟踪）	alchemy evm simulate execution-bundle --txs '<json-array>' [--block-tag <tag>]

EVM — 钱包签名交易

钱包签名的 EVM 操作会返回智能钱包 调用 ID。使用 alchemy evm status <call-id-or-tx-hash> 可查询调用 ID 或交易哈希的状态。对于受支持的操作，可使用 --gas-sponsored 和 --gas-policy-id <id> 请求 Gas 赞助；使用 alchemy config set evm-gas-sponsored true 和 alchemy config set evm-gas-policy-id <id> 设置默认值。

任务	命令
发送原生代币	alchemy evm send <to> <amount> [-n <network>]
发送 ERC-20	alchemy evm send <to> <amount> --token <token-address>
执行合约函数	alchemy evm contract call <address> <function> [--args ...] [--abi-file <path>|--abi '<json>'] [--value <wei>]
授权 / 撤销 / 重置 ERC-20 授权额度	alchemy evm approve <spender-address> --token-address <addr> [--amount <n>|--unlimited|--revoke]
获取同链兑换报价	alchemy evm swap quote --from <token> --to <token> --amount <n>
执行同链兑换	alchemy evm swap execute --from <token> --to <token> --amount <n>
查询调用 / 交易状态	alchemy evm status <call-id-or-tx-hash>

兑换时原生代币的地址：0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE。

大多数钱包签名的 EVM 命令都接受 --signer session|local，可为本次调用覆盖当前签名者。如果两个签名者均已配置但未选择当前签名者，CLI 默认使用 session 并显示警告。

Solana

Solana 交易命令使用本地 Solana 钱包（alchemy wallet connect --mode local --chain solana）。在支持的操作中使用 --fee-sponsored 和 --fee-policy-id <id> 请求手续费赞助；使用 alchemy config set solana-fee-sponsored true / alchemy config set solana-fee-policy-id <id> 持久化默认设置。

任务	命令
Solana JSON-RPC	alchemy solana rpc <method> [params...]
Solana DAS（NFT/资产）	alchemy solana das <method> '<json>'
发送原生 SOL	alchemy solana send <to> <amount> [-n solana-mainnet]
批准 SPL 代币委托	alchemy solana delegate approve --token-account <addr> --mint <addr> --delegate <addr> --amount <n> --decimals <n>
撤销 SPL 代币委托	alchemy solana delegate revoke --token-account <addr>
检查 Solana 交易状态	alchemy solana status <signature>
列出程序账户	alchemy solana program accounts <program-id> [--filters '<json>'] [--encoding <enc>] [--limit <n>]
显示 Solana 账户	alchemy solana program account <address>
显示 Solana 程序元数据	alchemy solana program show <program-id>
列出 Solana 网络 ID	alchemy solana network list

alchemy solana swap 为未来支持预留，目前尚未实现。

跨链

Bridge 支持 EVM 主网。对于同链代币兑换，请使用 alchemy evm swap。

任务	命令
获取桥接报价	alchemy xchain bridge quote --from <token> --to <token> --amount <n> --to-network <network>
执行桥接	alchemy xchain bridge execute --from <token> --to <token> --amount <n> --to-network <network>

源网络由 -n, --network 指定。

钱包和签名

钱包会话是与 CLI 绑定的签名器，用户可在 Agent Wallets 控制面板中批准。Agent 无法查看私钥。会话会自动过期，也可以通过 CLI 或控制面板撤销。服务端可能授予会话的签名能力：evm.signMessage、evm.signTypedData、evm.signAuthorization、evm.prepareCalls、evm.sendCalls、solana.signTransaction。会话签名器不支持原始 EVM 交易签名——请使用操作命令（evm send、evm contract call、evm approve、evm swap、xchain bridge、solana send），这些命令通过 Alchemy 智能钱包调用执行。

在执行任何会更改状态的钱包操作前，先运行 alchemy --json --no-interactive wallet status --verify——该命令会返回当前活动的签名器、过期时间、链特定的会话元数据、后端状态以及已启用的签名器能力。

任务	命令
连接钱包（会话）	alchemy wallet connect --mode session --instance-name <label>
连接本地 EVM 钱包（导入私钥文件）	alchemy wallet connect --mode local --chain evm --import <path>
连接本地 Solana 钱包	alchemy wallet connect --mode local --chain solana
显示钱包状态	alchemy wallet status [--verify]
显示已配置的钱包地址	alchemy wallet address
将地址生成为二维码	alchemy wallet qr
选择用于 EVM 交易的活动签名器	alchemy wallet use <session|local>
断开连接／撤销钱包	alchemy wallet disconnect
按命令覆盖签名器	在命令后追加 --signer session|local

Webhook（Notify）

任务	命令
列出 Webhook	alchemy webhook list
创建 Webhook	alchemy webhook create --body '<json>' [--dry-run]
更新 Webhook	alchemy webhook update --body '<json>' [--dry-run]
删除 Webhook	alchemy webhook delete <id> [--yes] [--dry-run]
获取地址活动 Webhook 地址	alchemy webhook addresses <id>
获取 NFT 活动 Webhook 筛选条件	alchemy webhook nft-filters <id>

应用管理（Admin API）

任务	命令
列出应用	alchemy app list [--cursor <c>] [--limit <n>] [--all] [--search <q>] [--id <appId>]
获取应用详情	alchemy app get <id>
创建应用	alchemy app create --name "My App" --networks eth-mainnet [--description <desc>] [--products <ids>] [--dry-run]
更新应用元数据	alchemy app update <id> --name "New Name" [--description <desc>] [--dry-run]
更新应用网络允许列表	alchemy app networks <id> --networks eth-mainnet,base-mainnet [--dry-run]
更新应用地址允许列表	alchemy app address-allowlist <id> --addresses 0xAA,0xBB [--dry-run]
更新应用来源允许列表	alchemy app origin-allowlist <id> --origins https://a.com,https://b.com [--dry-run]
更新应用 IP 允许列表	alchemy app ip-allowlist <id> --ips 1.2.3.4,5.6.7.8 [--dry-run]
删除应用	alchemy app delete <id> [--yes] [--dry-run]
选择默认应用	alchemy app select <id>（等同于 alchemy config set app <id>）
列出为应用配置的网络	alchemy app configured-networks [--app-id <id>]
列出 Admin API 链标识符（用于 app create/update）	alchemy app chains
列出 EVM RPC 网络标识（用于 --network）	alchemy evm network list [--mainnet-only] [--testnet-only] [--search <term>]

CLI 的 app 和 usage 命令是 Alchemy 公共 Admin API（api.g.alchemy.com/admin-api/v1/...）的轻量封装。Apps 和 Chains 端点为公共端点，可自助使用；Usage 端点也支持针对应用的查询自助使用。有关 REST 接口、身份验证模型（x-alchemy-token bearer 或 CLI 浏览器会话）以及端点列表，请参阅 references/operational-admin-api.md。

用量和计量

任务	命令
查询一段时间内的用量汇总	alchemy usage summary --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> [--app-ids <ids>] [--networks <slugs>] [--metrics amount,usd]
查询一段时间内的用量时间序列	alchemy usage timeseries --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> [--granularity minute|hour|day|month] [--products <ids>] [--metrics amount] [--app-ids <ids>] [--networks <slugs>] [--methods <names>] [--request-types <types>] [--group-by <field>]
时间序列（别名）	alchemy usage time-series ...

时间序列查询的范围限制（截至 2026-07-02）：

• 免费计划：最多回溯 7 天。
• 按使用量付费：最多回溯 30 天。
• 更长的时间范围：请联系销售团队。

如果请求的时间范围超出计划限制，CLI 不会报错，而是返回允许的时间范围，并在响应中同时显示请求范围和返回范围，以便你识别截断情况。

--metrics 的语义因端点而异：

• alchemy usage timeseries 只接受 amount。时间序列响应不支持 usd 指标（根据 API 端变更于 2026-08-13 移除）；请传入 --metrics amount 或省略该标志。
• alchemy usage summary 的汇总响应接受 amount 和 usd（以逗号分隔）。

身份验证：与 alchemy app 使用相同的浏览器会话（Admin API 访问权限）。

x402 支付（第三方 API）

alchemy x402 request 和 alchemy x402 balance 会根据 RFC 402，以 USDC 支付第三方 API 的费用。这与 --x402 / alchemy config set x402 true 是不同的功能，后者用于 Alchemy 自有网关的 Alchemy API 身份验证。需要 @alchemy/cli 0.22.0 或更高版本。

任务	命令
发起 x402 付费请求	alchemy x402 request <url> [--dry-run] [--estimate] [--max-payment <usdc>] [--yes]
查看当前 x402 钱包余额	alchemy x402 balance

• 在非交互模式下传入 --max-payment <usdc>；未传入时，CLI 会以 9 退出（非交互模式下未设置上限）。
• 将 --yes 与未设置 --max-payment 结合使用时，会以 2 退出（使用 yes 但未设置上限）。
• 根据第三方服务的情况，使用 Circle Gateway 批量纳米支付或直接通过 EIP-3009 结算。
• 在线示例端点：https://nano.blockrun.ai（首次请求时返回 HTTP 402，客户端签署支付后请求才会完成）。

CLI 管理和实用工具

任务	命令
检查 CLI 更新	alchemy update-check
查看配置	alchemy config list
重置配置	alchemy config reset --yes
CLI 版本	alchemy version
为客户端安装 MCP / Skills	alchemy install mcp / alchemy install skills
Shell 补全	alchemy completions <bash|zsh|fish>

全局标志

标志	说明
--json	强制输出 JSON（通过管道传输时自动启用）
--no-interactive	禁用提示和 REPL
-n, --network <network>	目标网络（默认值：eth-mainnet，环境变量：ALCHEMY_NETWORK）
--api-key <key>	覆盖当前命令使用的 API 密钥（环境变量：ALCHEMY_API_KEY）
--x402	为此命令使用基于 x402 钱包的网关身份验证
--wallet-key-file <path>	EVM 钱包私钥文件路径（用于 x402）
--solana-wallet-key-file <path>	Solana 钱包密钥文件路径
--timeout <ms>	请求超时（毫秒）
-q, --quiet	隐藏非必要输出
--verbose	将请求 / 响应详情记录到 stderr
--debug	启用调试诊断
--no-color	禁用彩色输出
--reveal	以纯文本显示机密信息（请谨慎使用；适用于明确要求显示的流程）

错误处理

错误会以结构化 JSON 格式返回到 stderr。每个错误都包含 code、exitCode（1–9）、retryable 布尔值和 recovery 提示。主要错误代码（来自 agent-prompt）：

代码	退出码	可重试	恢复方法
AUTH_REQUIRED	3	否	运行 alchemy auth login，或设置 ALCHEMY_API_KEY / alchemy config set api-key <key>
INVALID_API_KEY	3	否	检查 API 密钥；使用 alchemy config set api-key <key> 设置有效密钥
APP_REQUIRED	3	否	选择默认应用：alchemy app select <id>（或 alchemy config set app <id>）
NETWORK_NOT_ENABLED	3	否	在 dashboard.alchemy.com 为你的应用启用目标网络
SETUP_REQUIRED	3	否	运行 alchemy --json doctor 并按照 nextCommands 操作
PAYMENT_REQUIRED	9	否	为 x402 钱包充值，或切换为 API 密钥身份验证
RATE_LIMITED	5	是	等待后使用退避策略重试；考虑升级套餐
NETWORK_ERROR	6	是	检查连接并重试
RPC_ERROR	7	否	检查方法、参数和网络；确认 API 密钥具有访问权限
ADMIN_API_ERROR	8	否	查看错误消息；管理命令需要经过身份验证的浏览器会话
NOT_FOUND	4	否	确认资源标识符（地址、哈希、ID）正确
INVALID_ARGS	2	否	通过 alchemy --json help <command> 查看命令用法
INTERNAL_ERROR	1	否	发生意外错误；请重试或报告问题

随时运行 alchemy --json --no-interactive agent-prompt 获取完整的规范列表。

移交给其他技能

用户想要……	移交给
将 Alchemy 接入要发布到生产环境的应用代码，并使用 API key	alchemy-api
将 Alchemy 接入应用代码而不使用 API key，或作为自主 Agent 按请求付费	agentic-gateway
运行实时任务，但未安装 CLI 且不想安装（已接入 MCP）	alchemy-mcp

接入 alchemy-api 流程（提取 API key）

如果用户正在启动一个应用代码项目，且其 shell 中未设置 $ALCHEMY_API_KEY，请使用 CLI 从其 Alchemy 账户获取密钥，将其保存到项目的 .env 文件中，使其在不同终端会话间保留，并导出该密钥供 Agent 在当前 shell 中立即使用。

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

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

# 2. If empty/null, run the interactive flow.
#    Note: auth login opens a browser and app 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 app select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # opens browser; sets up account credentials
  alchemy --json app 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 — survives terminal restarts
#    and gets loaded by dotenv / framework env loaders at runtime).
#    Use .env.local if the project's framework expects that (e.g. Next.js).
ENV_FILE=".env"
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
  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
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore

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

在 .env 中保存密钥并导出 ALCHEMY_API_KEY 后，将任务移交给 alchemy-api 技能。

官方链接

• npm 上的 CLI
• Alchemy 文档
• 获取 API key