alchemy-cli

# Alchemy CLI Use the [Alchemy CLI](https://www.npmjs.com/package/@alchemy/cli) (`@alchemy/cli`) for live blockchain queries, admin work, transaction signing, and local automation from the terminal. The CLI groups commands by chain (`evm`, `solana`, `xchain`) and by product area (`wallet`, `app`, `webhook`, `auth`, `config`), each with structured JSON output. ## When to use this skill Use `alchemy-cli` when **all** of the following are true: - The user wants **live agent work** — live querying, analysis, admin work, or local automation that the agent runs now in this session - `@alchemy/cli` is installed locally, **or** both the CLI and an MCP server are available, **or** neither is available (in which case install the CLI — see [Install](#install)) The CLI is the **preferred local fallback runtime path** for live agent work. When in doubt about CLI vs MCP, prefer the CLI. ## When to use a different skill | Situation | Use this skill instead | | --- | --- | | MCP is already wired into your client and the CLI is **not** installed locally | `alchemy-mcp` | | Building application code that runs outside this agent session, with an Alchemy API key | `alchemy-api` | | Building application code without an API key, or as an autonomous agent that needs to pay for itself, or you explicitly want x402/MPP | `agentic-gateway` | Do **not** use this skill to write production application code — CLI commands are for live agent work, not for embedding into shipped software. ## Install ```bash npm i -g @alchemy/cli ``` If the CLI is not installed and the user wants live agent work, install it. Do not fall back to raw curl/HTTP calls — those are the API-key path covered by `alchemy-api`. ## Bootstrap Run this at the start of any session to get the full command contract (every command, flag, auth method, error code, and example): ```bash alchemy --json --no-interactive agent-prompt ``` For wallet-scoped agent work, use the narrower contract that lists only wallet, EVM, Solana, and cross-chain commands plus the session-signer capability set: ```bash alchemy --json --no-interactive agent-prompt --scope wallet ``` When the CLI is not installed yet but the agent needs the same contract, the unauthenticated `npx` variant works: ```bash npx -y @alchemy/cli@latest --json --no-interactive agent-prompt --scope wallet ``` ## Execution rules - ALWAYS pass `--json --no-interactive` on every command - Parse stdout as JSON on exit code 0 - Parse stderr as JSON on nonzero exit code - NEVER run bare `alchemy` without `--json --no-interactive` - NEVER use curl or raw HTTP when an `alchemy` CLI command exists for the task — that's the `alchemy-api` (API-key) path, not this skill - NEVER use the CLI to generate production application code; hand off to `alchemy-api` or `agentic-gateway` for shipped code - For onchain actions (`evm send`, `evm contract call`, `evm approve`, `evm swap`, `xchain bridge`, `solana send`), run `alchemy --json --no-interactive wallet status --verify` first to confirm the session is still valid, then prefer `--dry-run` before broadcast. Treat sponsorship policies (`--gas-policy-id`, `--fee-policy-id`) as fee controls, not wallet spend limits. ## Preflight Before the first command, run **both** of these checks: ```bash alchemy --json --no-interactive doctor alchemy --json --no-interactive evm gas ``` `doctor` (alias: `alchemy config status`) reports what's configured plus a `nextCommands` list of remediation steps. **Do not rely on its top-level OK alone** — there is a known false positive where it reports the session is set up but RPC commands still fail with `AUTH_REQUIRED` because no API key has been derived from the auth token. `evm gas` is a lightweight RPC smoke test that catches this. If it returns `{"gasPrice": "0x...", ...}`, RPC is wired up correctly. If it returns `{"error": {"code": "AUTH_REQUIRED", ...}}`, run `alchemy auth login` (which fetches and saves the API key) or `alchemy config set api-key <key>`, then re-run `evm gas` to confirm. If `doctor` reports missing config, follow its `nextCommands` first, then run `evm gas` to verify. ## Auth setup The fastest way to authenticate is via browser login: ```bash alchemy auth login ``` For headless environments (SSH, GitHub Codespaces, CI, sandboxes) where the browser can't reach the CLI's localhost callback, force the OAuth 2.0 Device Authorization Grant flow: ```bash alchemy auth login --device-code ``` Plain `alchemy auth` auto-detects non-interactive sessions and switches to device-code mode automatically. Requires `@alchemy/cli` 0.18.0 or later. This opens a browser, completes the OAuth flow, and configures both the API key (for RPC/Data) and the Admin API access internally. There is no separate access key step anymore — admin commands (`alchemy app ...`) work straight after `alchemy auth login`. To check auth status: `alchemy auth status` To log out: `alchemy auth logout` ### Alternative auth methods | Method | Config command | Env var | Used by | |--------|---------------|---------|---------| | Browser login | `alchemy auth login` (add `--device-code` for headless) | -- | All commands (covers both RPC/Data and Admin) | | API key | `alchemy config set api-key <key>` | `ALCHEMY_API_KEY` | RPC/Data commands (`evm rpc`, `evm data`, `evm tx`, `solana rpc`, etc.) | | Webhook key | `alchemy config set webhook-api-key <key>` | `ALCHEMY_WEBHOOK_API_KEY` | `webhook` | | Agent wallet session | `alchemy wallet connect --mode session --instance-name <label>` (approve in dashboard) | -- | `evm send`, `evm contract call`, `evm approve`, `evm swap`, `xchain bridge`, `evm status`, `solana send`, `solana status`, `solana delegate` | | Local wallet | `alchemy wallet connect --mode local` (`--import <path>` for EVM key) | -- | Same wallet-signed commands as session, with `--signer local` override | | x402 gateway auth (Alchemy API path) | `alchemy wallet connect --mode local --chain evm` then `alchemy config set x402 true` | `ALCHEMY_WALLET_KEY` | RPC and Data commands when `--x402` is active. This is Alchemy API auth via wallet, distinct from `alchemy x402 request` (see below). | | x402 payments (third-party APIs) | `alchemy wallet connect --mode local` — a signer configured for x402 payments | -- | `alchemy x402 request <url>`, `alchemy x402 balance` (pays third-party APIs in USDC per RFC 402) | `alchemy evm network list` / `alchemy solana network list` and `alchemy version` / `update-check` need no auth. ### Selecting a default app Many `app` subcommands operate on a "default app." If you see `APP_REQUIRED` in an error response, select one: ```bash alchemy --json --no-interactive app select <id> # or equivalently alchemy --json --no-interactive config set app <id> ``` Get an Alchemy account at [dashboard.alchemy.com](https://dashboard.alchemy.com/). ## Task-to-command map ### EVM — onchain reads | Task | Command | |------|---------| | Native balance (ETH, MATIC, ...) | `alchemy evm data balance <address>` | | Transaction details | `alchemy evm tx <hash>` | | Transaction receipt | `alchemy evm receipt <hash>` | | Block details | `alchemy evm block <number\|latest>` | | Gas prices | `alchemy evm gas` | | Event logs | `alchemy evm logs --address <addr> --from-block <n> --to-block <n>` | | Raw JSON-RPC | `alchemy evm rpc <method> [params...]` | | Trace methods | `alchemy evm trace <method> [params...]` | | Debug methods | `alchemy evm debug <method> [params...]` | | Contract view/pure call | `alchemy evm contract read <address> <function> [--args ...] [--abi-file <path>]` | ### EVM — Data API | Task | Command | |------|---------| | ERC-20 balances | `alchemy evm data tokens balances <address>` | | ERC-20 balances (formatted) | `alchemy evm data tokens balances <address> --metadata` | | Token metadata | `alchemy evm data tokens metadata <contract>` | | Token allowance | `alchemy evm data tokens allowance --owner <addr> --spender <addr> --contract <addr>` | | List owned NFTs | `alchemy evm data nfts <address> [--limit <n>] [--page-key <key>]` | | NFT metadata | `alchemy evm data nfts metadata --contract <addr> --token-id <id>` | | NFT contract metadata | `alchemy evm data nfts contract <address>` | | Asset transfer history | `alchemy evm data history <address> [--from-block <n>] [--to-block <n>] [--max-count <n>] [--page-key <key>]` | | Spot prices by symbol | `alchemy evm data price symbol ETH,USDC` | | Spot prices by address | `alchemy evm data price address --addresses '<json>'` | | Historical prices | `alchemy evm data price historical --body '<json>'` | | Cross-network token portfolio | `alchemy evm data portfolio tokens --body '<json>'` | | Token balances by address/network pairs | `alchemy evm data portfolio token-balances --body '<json>'` | | Cross-network NFT portfolio | `alchemy evm data portfolio nfts --body '<json>'` | | NFT contracts by address/network pairs | `alchemy evm data portfolio nft-contracts --body '<json>'` | ### EVM — Simulation | Task | Command | |------|---------| | Simulate single tx (asset deltas) | `alchemy evm simulate asset-changes --tx '<json>' [--block-tag <tag>]` | | Simulate single tx (execution trace) | `alchemy evm simulate execution --tx '<json>' [--block-tag <tag>]` | | Simulate bundle (asset deltas) | `alchemy evm simulate asset-changes-bundle --txs '<json-array>' [--block-tag <tag>]` | | Simulate bundle (execution trace) | `alchemy evm simulate execution-bundle --txs '<json-array>' [--block-tag <tag>]` | ### EVM — wallet-signed transactions Wallet-signed EVM actions return a smart wallet **call ID**. Use `alchemy evm status <call-id-or-tx-hash>` to check either value. Use `--gas-sponsored` and `--gas-policy-id <id>` on supported actions to request gas sponsorship; set defaults with `alchemy config set evm-gas-sponsored true` and `alchemy config set evm-gas-policy-id <id>`. | Task | Command | |------|---------| | Send native token | `alchemy evm send <to> <amount> [-n <network>]` | | Send ERC-20 | `alchemy evm send <to> <amount> --token <token-address>` | | Execute a contract function | `alchemy evm contract call <address> <function> [--args ...] [--abi-file <path>\|--abi '<json>'] [--value <wei>]` | | Approve / revoke / reset ERC-20 allowance | `alchemy evm approve <spender-address> --token-address <addr> [--amount <n>\|--unlimited\|--revoke]` | | Quote same-chain swap | `alchemy evm swap quote --from <token> --to <token> --amount <n>` | | Execute same-chain swap | `alchemy evm swap execute --from <token> --to <token> --amount <n>` | | Check call / tx status | `alchemy evm status <call-id-or-tx-hash>` | Native token address for swaps: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. Most wallet-signed EVM commands accept `--signer session|local` to override the active signer for that invocation. When both signers are configured and no active one is chosen, the CLI defaults to `session` and prints a warning. ### Solana Solana transaction commands use a local Solana wallet (`alchemy wallet connect --mode local --chain solana`). Use `--fee-sponsored` and `--fee-policy-id <id>` on supported actions to request fee sponsorship; persist defaults with `alchemy config set solana-fee-sponsored true` / `alchemy config set solana-fee-policy-id <id>`. | Task | Command | |------|---------| | Solana JSON-RPC | `alchemy solana rpc <method> [params...]` | | Solana DAS (NFTs/assets) | `alchemy solana das <method> '<json>'` | | Send native SOL | `alchemy solana send <to> <amount> [-n solana-mainnet]` | | Approve SPL token delegate | `alchemy solana delegate approve --token-account <addr> --mint <addr> --delegate <addr> --amount <n> --decimals <n>` | | Revoke SPL token delegate | `alchemy solana delegate revoke --token-account <addr>` | | Check Solana tx status | `alchemy solana status <signature>` | | List program accounts | `alchemy solana program accounts <program-id> [--filters '<json>'] [--encoding <enc>] [--limit <n>]` | | Show Solana account | `alchemy solana program account <address>` | | Show Solana program metadata | `alchemy solana program show <program-id>` | | List Solana network IDs | `alchemy solana network list` | `alchemy solana swap` is reserved for future support and is not implemented. ### Cross-chain Bridge supports EVM mainnets. For same-chain token exchanges, use `alchemy evm swap`. | Task | Command | |------|---------| | Quote a bridge | `alchemy xchain bridge quote --from <token> --to <token> --amount <n> --to-network <network>` | | Execute a bridge | `alchemy xchain bridge execute --from <token> --to <token> --amount <n> --to-network <network>` | Source network comes from `-n, --network`.