alchemy-api

Alchemy API（API キーを使用）

標準 API キーを使って Alchemy API をアプリケーションコードに組み込むためのリファレンスと統合ガイドです。このファイルだけで基本的な統合を実装できます。references/ ディレクトリには、各製品領域をさらに詳しく解説しています。

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

以下の条件をすべて満たす場合は、alchemy-api を使用してください。

• ユーザーが、現在のエージェントセッションの外部で実行されるアプリケーションコード（サーバー、バックエンド、dApp、ワーカー、スクリプト）に Alchemy を組み込んでいる
• Alchemy API キーをすでに持っているか、作成する意思がある（dashboard.alchemy.com で無料作成できます）

通常のサーバー／バックエンドでの利用では、これがアプリケーション統合の推奨方法です。

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

状況	代わりに使用するスキル
このセッションでのライブエージェント作業（クエリ、管理、マシン上での自動化）で、@alchemy/cli がローカルにインストールされている場合 — または CLI と MCP の両方を利用できる場合	alchemy-cli
このセッションでのライブエージェント作業で、クライアントに MCP のみが接続されている場合（CLI なし）	alchemy-mcp
ライブエージェント作業で、どちらも利用できない場合	alchemy-cli をインストールして 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 キー不要）。

ユーザーがそのエンドポイントを明示的に要求しない限り、キー不要のフォールバックや公開フォールバック（.../v2/demo を含む）を呼び出してはいけません。フォールバックとして、公開 RPC エンドポイント（publicnode、llamarpc、cloudflare-eth など）を使用してはなりません。

CLI から API キーを取得する

@alchemy/cli がローカルにインストールされている場合（command -v alchemy で確認できます）、ターミナルを離れずにキーを取得し、プロジェクトの .env ファイルに保存してください。これにより、ターミナルのセッションをまたいで保持され、実行時にアプリから利用できるようになります。

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

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

# 2. If empty/null (no key cached yet), run the interactive flow.
#    Note: auth login opens a browser and apps 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 apps select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # opens browser; derives auth credentials
  alchemy --json apps 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 for app code so the key
#    survives terminal restarts and is loaded by dotenv / framework env loaders).
#    Use .env.local instead if your framework expects that (e.g. Next.js).
ENV_FILE=".env"   # or ".env.local" depending on the project convention
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
  # Replace existing line in-place (portable across 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. Make sure the env file is git-ignored.
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore

# 5. Also export to the current shell so the agent can immediately call the 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 の後は、以下のベース URL と認証およびクイックスタートに進んでください。

注意点： auth login が成功したにもかかわらず、config get api-key が「not found」を返す場合、CLI の setup status が auth_token だけで complete: true と誤って報告している可能性があります。alchemy --json apps select を再実行するか、--no-interactive と明示的な <id> を渡して、デフォルトのアプリを紐付けてから再試行してください。同じ注意点については、alchemy-cli スキルの Preflight に記載されています。

概要

API キーを使って Alchemy API を統合する AI エージェント向けの、自己完結型ガイドです。基本的な統合を実装するには、このファイルだけで十分です。詳しい情報、エッジケース、高度なワークフローについては、リファレンスファイルを参照してください。

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

まず行うこと

1. アプリ統合の対象範囲を確認します（必須の事前確認ゲートを参照）。
2. 以下のエンドポイントセレクターを使って適切な製品を選びます。
3. 正しいエンドポイントとヘッダーについては、ベース URL と認証の表を使用します。
4. クイックスタートの例をコピーし、まずテストネットに対して動作を確認します。

ベース URL と認証（早見表）

製品	ベース 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（オブジェクト、トランザクション、残高、ストリーミング）です。
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_simulateAssetChanges	references/data-simulation-api.md
Webhook の作成	POST /create-webhook	references/webhooks-details.md
Solana DAS	getAssetsByOwner（DAS）	references/solana-das-api.md
Sui オブジェクト／トランザクション	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":[]}'

Notify webhook の作成

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

Webhook 署名の検証（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));
}

ネットワークの命名規則

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

一般的なトークンアドレス

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

障害モードと再試行

• HTTP 429 はレート制限を意味します。ジッターを加えた指数バックオフを使用してください。
• JSON-RPC エラーは、HTTP 200 が返された場合でも error フィールドに含まれます。
• 障害後にページネーションを再開するには、pageKey を使用してください。
• 再接続時には、WebSocket イベントの重複を除去してください。

スキルマップ

製品分野ごとに整理された完全なリファレンス索引については、references/skill-map.md をご覧ください。

カテゴリの概要：

• Node：JSON-RPC、WebSocket、デバッグ、トレース、拡張 API、ユーティリティ
• Webhooks：アドレスアクティビティ、カスタム（GraphQL）、NFT アクティビティ、ペイロード、署名
• Solana：JSON-RPC、DAS、Yellowstone gRPC（ストリーミング）、ウォレット
• Sui gRPC：オブジェクト、トランザクション、残高、Move パッケージ、ネームサービス、サブスクリプション、署名検証
• Wallets：Account Kit、Bundler、Gas Manager、ウォレット API（旧称「Smart Wallets」）
• Rollups：L2/L3 のデプロイ概要
• Recipes：シミュレーション、保留中のトランザクションのサブスクリプション、Webhook のフロー
• Operational：認証、レート制限、ベストプラクティス

他のスキルへの引き継ぎ

ユーザーの要望	引き継ぎ先
このセッションで単発のライブクエリ、管理コマンド、またはマシン上の自動化を実行する（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 を参照してください

ネットワークスラッグが正しくない

• JSON-RPC とほとんどの API では小文字を使用します：eth-mainnet、base-mainnet
• Notify API では大文字を使用します：ETH_MAINNET、BASE_MAINNET
• 全一覧については、references/operational-supported-networks.md を参照してください

HTTP 200 での JSON-RPC エラー

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

公式リンク

• 開発者向けドキュメント
• スタートガイド
• 無料の API キーを作成