Alchemy API (avec clé API)

Guide de référence et d'intégration pour intégrer les APIs Alchemy dans le code d'application en utilisant une clé API standard. Ce fichier seul suffit pour déployer une intégration basique ; le répertoire references/ offre une couverture approfondie de chaque surface produit.

Quand utiliser cette skill (scope_in)

Utilisez alchemy-api quand tous les points suivants sont vrais :

• L'utilisateur intègre Alchemy dans du code d'application (serveur, backend, dApp, worker, script) qui s'exécute en dehors de la session agent actuelle
• Il dispose, ou est disposé à créer, une clé API Alchemy (gratuite sur dashboard.alchemy.com)

C'est le chemin d'intégration app préféré pour une utilisation serveur/backend standard.

Quand NE PAS utiliser cette skill (scope_out, handoff)

Ne pas utiliser cette skill pour exécuter des requêtes live ad-hoc depuis la session agent — c'est le chemin alchemy-cli / alchemy-mcp. Cette skill est pour le code qu'on déploie.

Vérification préalable obligatoire

Avant de rédiger du code d'application ou d'effectuer tout appel réseau :

1. Confirmer que l'utilisateur construit du code d'application (ne demande pas à l'agent d'exécuter une requête live). Si l'utilisateur demande du travail live, rediriger vers alchemy-cli (préféré) ou alchemy-mcp.
2. Vérifier que $ALCHEMY_API_KEY est définie (ex. echo $ALCHEMY_API_KEY).
3. Si $ALCHEMY_API_KEY est non définie ou vide, appliquer le premier qui s'applique :
   • Pont CLI (recommandé si @alchemy/cli est installé localement) : la CLI peut récupérer une clé depuis le compte Alchemy de l'utilisateur sans jamais quitter le terminal. Voir Bridging from the CLI to an API key ci-dessous.
   • Dire à l'utilisateur qu'il peut créer une clé API gratuite sur https://dashboard.alchemy.com/, ou
   • Basculer vers la skill alchemy-agentic-gateway (gateway x402/MPP, auth basée wallet, pas de clé API nécessaire).

Vous NE DEVEZ PAS appeler de fallback sans clé ou public (incluant .../v2/demo) sauf si l'utilisateur demande explicitement cet endpoint. Pas d'endpoints RPC publics (publicnode, llamarpc, cloudflare-eth, etc.) comme fallback.

Bridging from the CLI to an API key

Si @alchemy/cli est installé localement (vérifier avec command -v alchemy), utilisez-le pour obtenir une clé sans quitter le terminal et persistez-la dans le fichier .env du projet pour qu'elle survive aux redémarrages de terminal et soit disponible à l'app au runtime.

Sécurité : NE JAMAIS afficher, imprimer ou exposer la valeur de clé API extraite dans la sortie de conversation. Référencez-la seulement en tant que $ALCHEMY_API_KEY après export. Traitez-la comme un mot de passe.

# 1. Essayer de lire une clé en cache depuis la config CLI (lecture seule, sûr d'exécuter non-interactivement).
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"

# 2. Si vide/null (aucune clé en cache encore), exécuter le flux interactif.
#    Note: auth login ouvre un navigateur et apps select affiche un picker, donc NE PAS passer
#    --no-interactive ici. Si vous connaissez déjà l'id de l'app, passez-le explicitement pour sauter
#    le picker: `alchemy --no-interactive --json apps select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # ouvre le navigateur; dérive les credentials d'auth
  alchemy --json apps select      # picker interactif (omettez --no-interactive pour qu'il puisse s'afficher)
  KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi

# 3. Persister dans le .env du projet (pratique standard pour le code app pour que la clé
#    survive aux redémarrages de terminal et soit chargée par dotenv / chargeurs d'env de framework).
#    Utilisez .env.local à la place si votre framework l'attend (ex. Next.js).
ENV_FILE=".env"   # ou ".env.local" selon la convention du projet
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
  # Remplacer la ligne existante en place (portable entre sed BSD/GNU)
  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. S'assurer que le fichier env est git-ignoré.
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore

# 5. Exporter aussi pour le shell courant pour que l'agent puisse immédiatement appeler l'API.
export ALCHEMY_API_KEY="$KEY"

Pourquoi on persiste dans .env : sans cela, la clé n'est définie que pour la session shell courant et disparaît quand l'onglet terminal se ferme. Le code d'application charge généralement .env via dotenv (Node), python-dotenv (Python), direnv, ou chargeurs natifs de framework (Next.js, Vite, Bun, Deno, Rails, etc.), donc écrire dans .env est le moyen canonique de rendre la clé durable à la fois pour npm run dev et pour la copie locale de l'app déployée.

Pourquoi ce flux entier fonctionne : la CLI est un exécuteur runtime (skill alchemy-cli). Quand l'utilisateur l'a installée, vous pouvez l'utiliser pour provisionner la credential que cette skill de code d'app a besoin, l'écrire dans un endroit que l'application chargera, puis passer à la suite du flux alchemy-api. Après l'étape 5, continuer avec Base URLs + auth et Quickstart ci-dessous.

Piège : si auth login a réussi mais config get api-key retourne toujours "not found," le setup status de la CLI a peut-être faussement rapporté complete: true avec seulement un auth_token. Ré-exécuter alchemy --json apps select (ou passer un <id> explicite avec --no-interactive) pour lier une app par défaut, puis réessayer. Voir la skill alchemy-cli pour le même piège documenté sous Preflight.

Résumé

Un guide autonome pour que les agents IA intègrent les APIs Alchemy en utilisant une clé API. Ce fichier seul devrait suffire à déployer une intégration basique. Utilisez les fichiers de référence pour la profondeur, les cas limites, et les workflows avancés.

Les développeurs peuvent toujours créer une clé API gratuite sur https://dashboard.alchemy.com/.

Faire ceci en premier

1. Confirmer la portée d'intégration app (voir Mandatory preflight gate).
2. Choisir le bon produit en utilisant Endpoint selector ci-dessous.
3. Utiliser la table Base URLs + auth pour l'endpoint et les headers corrects.
4. Copier un exemple Quickstart et tester contre un testnet d'abord.

Base URLs + auth (cheat sheet)

Endpoint selector (top tasks)

One-file quickstart (copy/paste)

Pas de clé API ? Utilisez la skill alchemy-agentic-gateway à la place. Remplacez les URLs avec clé API par https://x402.alchemy.com/eth-mainnet/v2 et ajoutez Authorization: SIWE <token> (ou SIWS <token> pour un wallet Solana). Voir la skill alchemy-agentic-gateway pour la setup.

EVM JSON-RPC (read)

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

Token balances

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

Transfer history

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 ownership

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

Prices (spot)

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

Prices (historical)

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

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

Verify webhook signature (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));
}

Network naming rules

• Les Data APIs et JSON-RPC utilisent des enums de réseau en minuscules comme eth-mainnet.
• L'API Notify utilise des enums en majuscules comme ETH_MAINNET.

Pagination + limits (cheat sheet)

Common token addresses

Failure modes + retries

• HTTP 429 signifie rate limit. Utiliser exponential backoff avec jitter.
• Les erreurs JSON-RPC arrivent dans les champs error même avec HTTP 200.
• Utiliser pageKey pour reprendre la pagination après les défaillances.
• Dédupliquer les événements websocket lors de la reconnexion.

Skill map

Pour l'index complet de tous les 90+ fichiers de référence organisés par domaine produit (Node, Data, Webhooks, Solana, Sui gRPC, Wallets, Rollups, Recipes, Operational, Ecosystem), voir references/skill-map.md.

Aperçu rapide des catégories :

• 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 (streaming), Wallets
• Sui gRPC : Objects, Transactions, Balances, Move Packages, Name Service, Subscriptions, Signature Verification
• Wallets : Account Kit, Bundler, Gas Manager, Wallet APIs (anciennement « Smart Wallets »)
• Rollups : Aperçu déploiement L2/L3
• Recipes : 10 workflows d'intégration bout en bout
• Operational : Auth, Rate Limits, Monitoring, Best Practices
• Ecosystem : viem, ethers, wagmi, Hardhat, Foundry, Anchor, et plus

Handing off to other skills

Troubleshooting

API key not working

• Vérifier que $ALCHEMY_API_KEY est définie : echo $ALCHEMY_API_KEY
• Confirmer que la clé est valide sur dashboard.alchemy.com
• Vérifier si des allowlists restreignent la clé à des IPs/domaines spécifiques (voir references/operational-allowlists.md)

HTTP 429 (rate limited)

• Utiliser exponential backoff avec jitter avant de réessayer
• Vérifier votre budget d'unités de calcul dans le dashboard Alchemy
• Voir references/operational-rate-limits-and-compute-units.md pour les limites par plan

Wrong network slug

• Data APIs et JSON-RPC utilisent minuscules : eth-mainnet, base-mainnet
• Notify API utilise majuscules : ETH_MAINNET, BASE_MAINNET
• Voir references/operational-supported-networks.md pour la liste complète

JSON-RPC error with HTTP 200

• Alchemy retourne les erreurs JSON-RPC dans le champ error même avec un statut 200
• Toujours vérifier response.error en plus du statut HTTP

Official links

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