alchemy-cli

What this skill does

# Alchemy CLI

Use the [Alchemy CLI](https://www.npmjs.com/package/@alchemy/cli) (`@alchemy/cli`) for live blockchain queries, admin work, and local automation from the terminal. The CLI maps every Alchemy product (Node JSON-RPC, Token, NFT, Transfers, Prices, Portfolio, Simulation, Solana, Webhooks, Apps) to `alchemy <command>` invocations 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
```

## 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

## Preflight

Before the first command, run **both** of these checks:

```bash
alchemy --json --no-interactive setup status
alchemy --json --no-interactive gas
```

`setup status` returns `{"complete": true, "satisfiedBy": "<source>"}` if any auth is configured. **Do not rely on `complete: true` alone** — there is a known false positive where `setup status` reports `complete: true` with `satisfiedBy: "auth_token"`, but RPC commands still fail with `AUTH_REQUIRED` because no API key has been derived from the auth token.

`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 `gas` to confirm.

If `setup status` reports `complete: false`, follow the `nextCommands` in the response first, then run `gas` to verify.

## Auth setup

The fastest way to authenticate is via browser login:

```bash
alchemy auth login
```

This opens a browser to authenticate with your Alchemy account and automatically configures the CLI with your credentials.

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` | -- | All commands (derives API key + access key from your account) |
| API key | `alchemy config set api-key <key>` | `ALCHEMY_API_KEY` | `balance`, `tx`, `receipt`, `block`, `gas`, `logs`, `rpc`, `trace`, `debug`, `tokens`, `nfts`, `transfers`, `prices`, `portfolio`, `simulate`, `bundler`, `gas-manager`, `solana` |
| Access key | `alchemy config set access-key <key>` | `ALCHEMY_ACCESS_KEY` | `apps` (all subcommands incl. `configured-networks`) |
| Webhook key | `alchemy config set webhook-api-key <key>` | `ALCHEMY_WEBHOOK_API_KEY` | `webhooks` |
| x402 wallet | `alchemy wallet generate` then `alchemy config set x402 true` | `ALCHEMY_WALLET_KEY` | `balance`, `tx`, `block`, `rpc`, `trace`, `debug`, `tokens`, `nfts`, `transfers` |

`alchemy network list` and `alchemy version` / `update-check` need no auth.

### Selecting a default app

Many `apps` subcommands (and the access-key gated flows) operate on a "default app." If you see `APP_REQUIRED` in an error response, set one:

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

Get API/access keys at [dashboard.alchemy.com](https://dashboard.alchemy.com/).

## Task-to-command map

### Node (EVM)

| Task | Command |
|------|---------|
| ETH balance | `alchemy balance <address>` |
| Transaction details | `alchemy tx <hash>` |
| Transaction receipt | `alchemy receipt <hash>` |
| Block details | `alchemy block <number\|latest>` |
| Gas prices | `alchemy gas` |
| Event logs | `alchemy logs --address <addr> --from-block <n> --to-block <n>` |
| Raw JSON-RPC | `alchemy rpc <method> [params...]` |
| Trace methods | `alchemy trace <method> [params...]` |
| Debug methods | `alchemy debug <method> [params...]` |

### Data

| Task | Command |
|------|---------|
| ERC-20 balances | `alchemy tokens balances <address>` |
| ERC-20 balances (formatted) | `alchemy tokens balances <address> --metadata` |
| Token metadata | `alchemy tokens metadata <contract>` |
| Token allowance | `alchemy tokens allowance --owner <addr> --spender <addr> --contract <addr>` |
| List owned NFTs | `alchemy nfts <address> [--limit <n>] [--page-key <key>]` |
| NFT metadata | `alchemy nfts metadata --contract <addr> --token-id <id>` |
| NFT contract metadata | `alchemy nfts contract <address>` |
| Transfer history | `alchemy transfers <address> --category erc20,erc721,erc1155,external,internal,specialnft [--from-block <n>] [--to-block <n>] [--max-count <n>] [--page-key <key>]` |
| Spot prices by symbol | `alchemy prices symbol ETH,USDC` |
| Spot prices by address | `alchemy prices address --addresses '<json>'` |
| Historical prices | `alchemy prices historical --body '<json>'` |
| Cross-network token portfolio | `alchemy portfolio tokens --body '<json>'` |
| Token balances by address/network pairs | `alchemy portfolio token-balances --body '<json>'` |
| Cross-network NFT portfolio | `alchemy portfolio nfts --body '<json>'` |
| NFT contracts by address/network pairs | `alchemy portfolio nft-contracts --body '<json>'` |
| Simulate single tx (asset deltas) | `alchemy simulate asset-changes --tx '<json>' [--block-tag <tag>]` |
| Simulate single tx (execution trace) | `alchemy simulate execution --tx '<json>' [--block-tag <tag>]` |
| Simulate bundle (asset deltas) | `alchemy simulate asset-changes-bundle --txs '<json-array>' [--block-tag <tag>]` |
| Simulate bundle (execution trace) | `alchemy simulate execution-bundle --txs '<json-array>' [--block-tag <tag>]` |

### Solana

| Task | Command |
|------|---------|
| Solana JSON-RPC | `alchemy solana rpc <method> [params...]` |
| Solana DAS (NFTs/assets) | `alchemy solana das <method> '<json>'` |

### Webhooks

| Task | Command |
|------|---------|
| List webhooks | `alchemy webhooks list` |
| Create webhook | `alchemy webhooks create --body '<json>' [--dry-run]` |
| Update webhook | `alchemy webhooks update --body '<json>' [--dry-run]` |
| Delete webhook | `alchemy webhooks delete <id> [--yes] [--dry-run]` |
| Get address-activity webhook addresses | `alchemy webhooks addresses <id>` |
| Get NFT-activity webhook filters | `alchemy webhooks nft-filters <i