Alchemy API (APIキー付き)

API キーを使用して Alchemy APIs をアプリケーションコードに統合するためのリファレンスおよび統合ガイド。このファイルだけで基本的な統合をデプロイするのに十分です。references/ ディレクトリには、すべてのプロダクト領域のより詳しい情報があります。

このスキルを使用する場合

以下の条件がすべて満たされる場合、alchemy-api を使用します:

• ユーザーが Alchemy を、現在のエージェントセッション 外で実行される アプリケーションコード (サーバー、バックエンド、dApp、ワーカー、スクリプト) に統合している
• Alchemy API キーを持っているか、作成する意思がある (dashboard.alchemy.com で無料作成可能)

これは、通常のサーバー/バックエンド使用にための 推奨されるアプリ統合パス です。

別のスキルを使用する場合

状況	代わりにこのスキルを使用
このセッションでのライブエージェント作業 (クエリ、管理、マシン上の自動化) で、ローカルに @alchemy/cli がインストールされている、または CLI と MCP の両方が利用可能	alchemy-cli
このセッションでのライブエージェント作業で、クライアントに MCP のみが統合されている (CLI なし)	alchemy-mcp
ライブエージェント作業で、どちらも利用不可	alchemy-cli をインストールして使用
API キーなしのアプリケーションコード — 自律型エージェントが従量制で支払う、またはユーザーが明示的に x402/MPP を希望	agentic-gateway

エージェントセッション内からのアドホッククエリを実行するためにこのスキルを使用しないでください — それは alchemy-cli / alchemy-mcp パスです。このスキルはデプロイするコード用です。

必須のプレフライトゲート

アプリケーションコードを作成したり、ネットワーク呼び出しを行う前に:

1. ユーザーが アプリケーションコード を構築していることを確認します (エージェントにライブクエリの実行を依頼していない)。ユーザーがライブ作業を依頼している場合は、alchemy-cli (推奨) または alchemy-mcp にリダイレクトします。
2. $ALCHEMY_API_KEY が設定されていることを確認します (echo $ALCHEMY_API_KEY など)。
3. $ALCHEMY_API_KEY が設定されていない、または空の場合、以下の最初に該当するものを選択します:
   • CLI ブリッジ (ローカルに @alchemy/cli がインストールされている場合は推奨): CLI はユーザーの Alchemy アカウントからキーを取得できるため、ターミナルを離れる必要はありません。以下の CLI からの API キーへのブリッジング を参照してください。
   • https://dashboard.alchemy.com/ で無料の API キーを作成できることをユーザーに伝える、または
   • agentic-gateway スキルに切り替える (x402/MPP ゲートウェイ、ウォレットベースの認証、API キー不要)。

API キーなしの、またはパブリックフォールバック (.../v2/demo を含む) を呼び出す場合、ユーザーが明示的にそのエンドポイントを要求しない限り、呼び出し してはいけません。フォールバックとしてパブリック RPC エンドポイント (publicnode、llamarpc、cloudflare-eth など) を使用しないでください。

CLI からの API キーへのブリッジング

ローカルに @alchemy/cli がインストールされている場合 (command -v alchemy で確認)、これを使用してターミナルを離れずにキーを取得し、プロジェクトの .env ファイルに 永続化 して、ターミナルセッション全体で生き続け、実行時にアプリで利用可能になるようにします。

セキュリティ: 抽出された API キー値を決してエコー、出力、またはその他の方法で会話出力に表示しないでください。エクスポート後は、$ALCHEMY_API_KEY としてのみ参照してください。パスワードと同じように扱ってください。

# 1. CLI 設定からキャッシュされたキーを読み込みます (読み取り専用、非対話的に安全に実行可能)。
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"

# 2. 空/null の場合 (まだキーがキャッシュされていない)、対話的フローを実行します。
#    注: auth login はブラウザを開き、apps select はピッカーを表示するため、
#    ここで --no-interactive を渡さないでください。アプリ ID がわかっている場合は、
#    ピッカーをスキップするために明示的に渡してください: `alchemy --no-interactive --json apps select <id>`。
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # ブラウザを開く; 認証資格を導出
  alchemy --json apps select      # 対話的ピッカー (ピッカーを レンダリングできるように --no-interactive を省略)
  KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi

# 3. プロジェクトの .env に永続化します (キーがターミナルの再起動後も生き残り、
#    dotenv / フレームワークの環境ローダーで読み込まれるようにするアプリコードの標準的な慣行)。
#    フレームワークが予想する場合は、".env.local" を代わりに使用します (例: Next.js)。
ENV_FILE=".env"   # またはプロジェクトの慣例に応じて ".env.local"
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
  # インプレースで既存行を置換 (BSD/GNU sed 全体で移植可能)
  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

# 4. 環境ファイルが git で無視されていることを確認します。
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore

# 5. 現在のシェルにもエクスポートして、エージェントが直ちに API を呼び出せるようにします。
export ALCHEMY_API_KEY="$KEY"

なぜ .env に永続化するのか: なしでは、キーは現在のシェルセッションに対してのみ設定され、ターミナルタブが閉じられると消えます。アプリケーションコードは通常、dotenv (Node)、python-dotenv (Python)、direnv、またはフレームワークネイティブローダー (Next.js、Vite、Bun、Deno、Rails など) で .env を読み込むため、.env に書き込むことが、npm run dev とデプロイされたアプリのローカルコピーの両方でキーを永続的にする標準的な方法です。

このフロー全体が機能する理由: CLI はランタイム実行エージェント (alchemy-cli スキル) です。ユーザーがこれをインストールしている場合、これを使用してこのアプリコードスキルが必要な認証情報をプロビジョニングし、アプリケーションが読み込む場所に書き込み、次に alchemy-api フロー全体に渡すことができます。ステップ 5 の後、以下の Base URL + 認証 と クイックスタート を続行します。

落とし穴: auth login が成功しても config get api-key が「見つかりません」を返す場合、CLI の setup status は、auth_token のみで誤って complete: true を報告している可能性があります。alchemy --json apps select を再実行 (または --no-interactive で明示的な <id> を渡す) してデフォルトアプリをバインドし、次に再試行します。alchemy-cli スキルで、プレフライトの下に同じ落とし穴が記載されています。

要約

Alchemy APIs を API キーを使用して統合する AI エージェント向けの自己完結型ガイド。このファイルだけで基本的な統合をデプロイするのに十分です。詳細、エッジケース、高度なワークフローについては、リファレンスファイルを使用します。

開発者は、いつでも https://dashboard.alchemy.com/ で無料 API キーを作成できます。

まずこれを行う

1. アプリ統合スコープを確認します (必須プレフライトゲート を参照)。
2. 以下の エンドポイントセレクター を使用して適切なプロダクトを選択します。
3. Base URL + 認証 テーブルを使用して、正しいエンドポイントとヘッダーを取得します。
4. クイックスタート例 をコピーして、テストネットに対してテストします。

Base URL + 認証 (チートシート)

プロダクト	Base URL	認証	注記
Ethereum RPC (HTTPS)	https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	標準 EVM 読み書き。
Ethereum RPC (WSS)	wss://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	サブスクリプションとリアルタイム。
Base RPC (HTTPS)	https://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	EVM L2。
Base RPC (WSS)	wss://base-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	サブスクリプションとリアルタイム。
Arbitrum RPC (HTTPS)	https://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	EVM L2。
Arbitrum RPC (WSS)	wss://arb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	サブスクリプションとリアルタイム。
BNB RPC (HTTPS)	https://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	EVM L1。
BNB RPC (WSS)	wss://bnb-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	サブスクリプションとリアルタイム。
Solana RPC (HTTPS)	https://solana-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY	URL の API キー	Solana JSON-RPC。
Solana Yellowstone gRPC	https://solana-mainnet.g.alchemy.com	X-Token: $ALCHEMY_API_KEY	gRPC ストリーミング (Yellowstone)。
Sui gRPC	sui-mainnet.g.alchemy.com:443	Authorization: Bearer $ALCHEMY_API_KEY	Sui gRPC API (オブジェクト、Tx、残高、ストリーミング)。
NFT API	https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY	URL の API キー	NFT 所有権とメタデータ。
Prices API	https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY	URL の API キー	シンボルまたはアドレスによる価格。
Portfolio API	https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY	URL の API キー	マルチチェーンウォレットビュー。
Notify API	https://dashboard.alchemy.com/api	X-Alchemy-Token: <ALCHEMY_NOTIFY_AUTH_TOKEN>	ダッシュボードでトークンを生成します。

エンドポイントセレクター (主なタスク)

必要な機能	使用対象	スキル / ファイル
EVM 読み書き	JSON-RPC eth_*	references/node-json-rpc.md
リアルタイムイベント	eth_subscribe	references/node-websocket-subscriptions.md
トークン残高	alchemy_getTokenBalances	references/data-token-api.md
トークンメタデータ	alchemy_getTokenMetadata	references/data-token-api.md
転送履歴	alchemy_getAssetTransfers	references/data-transfers-api.md
NFT 所有権	GET /getNFTsForOwner	references/data-nft-api.md
NFT メタデータ	GET /getNFTMetadata	references/data-nft-api.md
価格 (スポット)	GET /tokens/by-symbol	references/data-prices-api.md
価格 (履歴)	POST /tokens/historical	references/data-prices-api.md
ポートフォリオ (マルチチェーン)	POST /assets/*/by-address	references/data-portfolio-apis.md
Tx シミュレート	alchemy_simulateAssetChanges	references/data-simulation-api.md
ウェブフック作成	POST /create-webhook	references/webhooks-details.md
Solana NFT データ	getAssetsByOwner (DAS)	references/solana-das-api.md
Sui オブジェクト/Tx	GetObject、GetTransaction (gRPC)	references/sui-grpc-objects-and-ledger.md
Sui 残高	GetBalance、ListBalances (gRPC)	references/sui-grpc-state-and-balances.md
Sui チェックポイントストリーム	SubscribeCheckpoints (gRPC)	references/sui-grpc-subscriptions.md

1 ファイルのクイックスタート (コピー/ペースト)

API キーなし? 代わりに agentic-gateway スキルを使用します。API キー URL を https://x402.alchemy.com/eth-mainnet/v2 に置き換え、Authorization: SIWE <token> (または Solana ウォレット用 SIWS <token>) を追加します。セットアップについては agentic-gateway スキルを参照してください。

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":[]}'

トークン残高

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"]}'

転送履歴

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"}]}'

NFT 所有権

curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0x00000000219ab540356cbb839cbe05303d7705fa"

価格 (スポット)

curl -s "https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/tokens/by-symbol?symbols=ETH&symbols=USDC"

価格 (履歴)

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"}'

Notify ウェブフック作成

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"]}'

ウェブフック署名を検証 (Node)

import crypto from "crypto";

export function verify(rawBody: string, signature: string, secret: string) {
  const hmac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature));
}

ネットワーク命名規則

• Data API と JSON-RPC は eth-mainnet のような小文字のネットワーク列挙を使用します。
• Notify API は ETH_MAINNET のような大文字の列挙を使用します。

ページネーション + 制限 (チートシート)

エンドポイント	制限	注記
alchemy_getTokenBalances	maxCount <= 100	ページネーションに pageKey を使用します。
alchemy_getAssetTransfers	maxCount デフォルト 0x3e8	ページネーションに pageKey を使用します。
Portfolio トークン残高	3 つのアドレス/ネットワークペア、合計 20 ネットワーク	pageKey サポート。
Portfolio NFT	2 つのアドレス/ネットワークペア、各ネットワーク 15 個	pageKey サポート。
アドレス別価格	25 個のアドレス、3 ネットワーク	POST ボディ addresses[]。
トランザクション履歴 (ベータ)	1 アドレス/ネットワークペア、2 ネットワーク	ETH および BASE メインネットのみ。

共通トークンアドレス

トークン	チェーン	アドレス
ETH	ethereum	0x0000000000000000000000000000000000000000
WETH	ethereum	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDC	ethereum	0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48
USDC	base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

失敗モード + リトライ

• HTTP 429 はレート制限を意味します。ジッターを含む指数バックオフを使用します。
• JSON-RPC エラーは HTTP 200 でも error フィールドで返されます。
• 失敗後のページネーション再開には pageKey を使用します。
• Websocket イベントを再接続時に重複排除します。

スキルマップ

プロダクト領域 (Node、Data、Webhooks、Solana、Sui gRPC、Wallets、Rollups、Recipes、Operational、Ecosystem) で整理されたすべての 90+ リファレンスファイルの完全なインデックスについては、references/skill-map.md を参照してください。

クイックカテゴリー概要:

• Node: JSON-RPC、WebSocket、Debug、Trace、Enhanced API、Utility
• Data: NFT、Portfolio、Prices、Simulation、Token、Transfers
• Webhooks: Address Activity、Custom (GraphQL)、NFT Activity、Payloads、Signatures
• Solana: JSON-RPC、DAS、Yellowstone gRPC (ストリーミング)、Wallets
• Sui gRPC: Objects、Transactions、Balances、Move Packages、Name Service、Subscriptions、Signature Verification
• Wallets: Account Kit、Bundler、Gas Manager、Wallet API (formerly "Smart Wallets")
• Rollups: L2/L3 デプロイ概要
• Recipes: 10 のエンドツーエンド統合ワークフロー
• Operational: Auth、Rate Limits、Monitoring、Best Practices
• Ecosystem: viem、ethers、wagmi、Hardhat、Foundry、Anchor など

他のスキルへのハンドオフ

ユーザーが次のことを望む場合	ハンドオフ先
このセッションでワンオフのライブクエリ、管理コマンド、またはオンマシン自動化を実行する (CLI がインストールされている)	alchemy-cli
このセッションでワンオフのライブクエリを実行する (MCP のみが統合されている)	alchemy-mcp
API キーなしでアプリコードを構築する (自律型エージェント、または明示的な x402/MPP)	agentic-gateway

トラブルシューティング

API キーが機能しない

• $ALCHEMY_API_KEY が設定されていることを確認: echo $ALCHEMY_API_KEY
• キーが dashboard.alchemy.com で有効であることを確認
• 許可リストがキーを特定の IP/ドメインに制限しているかを確認 (references/operational-allowlists.md を参照)

HTTP 429 (レート制限)

• リトライ前に、ジッターを含む指数バックオフを使用します
• Alchemy ダッシュボードでコンピューティングユニット予算を確認
• references/operational-rate-limits-and-compute-units.md でプランごとの制限を参照

誤ったネットワークスラッグ

• Data API と JSON-RPC は小文字を使用: eth-mainnet、base-mainnet
• Notify API は大文字を使用: ETH_MAINNET、BASE_MAINNET
• 完全なリストについては references/operational-supported-networks.md を参照

HTTP 200 の JSON-RPC エラー

• Alchemy は 200 ステータスコードでも JSON-RPC エラーを error フィールド内で返します
• HTTP ステータスに加えて、常に response.error を確認してください

公式リンク

• Developer docs
• Get Started guide
• Create a free API key