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（オブジェクト、トランザクション、残高、ストリーミング）。
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
トランザクションのシミュレーション	alchemy_simulateAssetChanges	references/data-simulation-api.md
Webhook の作成	POST /create-webhook	references/webhooks-details.md
Solana NFT データ	getAssetsByOwner（DAS）	references/solana-das-api.md
Solana リアルタイムイベント（アカウント別／プログラム別／ログ／トランザクションステータス）	accountSubscribe、programSubscribe、logsSubscribe、signatureSubscribe（PubSub WebSocket）	references/solana-websocket-subscriptions.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":[]}'

トークン残高

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 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));
}

ネットワークの命名規則

• 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 APIs、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 APIs（旧称「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 を確認してください

公式リンク

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