MetaMask est la passerelle par défaut vers Ethereum pour des dizaines de millions d'utilisateurs, et si vous gérez une dApp, l'API MetaMask est ce qui se trouve entre votre interface utilisateur et leurs clés de signature. L'« API MetaMask » est deux choses dans un seul paquet : le fournisseur injecté window.ethereum défini par EIP-1193, et le SDK MetaMask qui étend cette même surface aux applications mobiles, à React Native et aux backends Node.js. Apprenez à connaître le fournisseur, et vous aurez appris 80 % de chaque intégration de portefeuille sur le web.
Ce guide explique comment détecter le fournisseur, demander des comptes, lire la chaîne actuelle, signer des messages avec personal_sign et EIP-712, envoyer des transactions, ajouter ou changer de chaîne, et utiliser le SDK MetaMask lorsque vous êtes en dehors d'une extension de navigateur. Vous verrez également où ethers.js v6 et viem s'intègrent en tant que wrappers de niveau supérieur, et où Apidog s'intègre au flux de travail lorsque vous souhaitez tester les appels JSON-RPC sous-jacents sans écrire de code frontend jetable.
Si vous construisez quoi que ce soit qui touche aux portefeuilles, mettez ceci en signet en plus de notre guide sur les meilleures API de portefeuille crypto pour une vue plus large du paysage des fournisseurs.
TL;DR
- L'API MetaMask est le fournisseur EIP-1193 exposé à
window.ethereumdans les navigateurs, plus le SDK MetaMask pour mobile et Node. - Commencez par
eth_requestAccountspour inviter l'utilisateur à se connecter, puis écoutez les événementsaccountsChangedetchainChanged. - Signez les messages avec
personal_sign, et signez les données structurées aveceth_signTypedData_v4(EIP-712). - Changez de réseau avec
wallet_switchEthereumChain(EIP-3326) et ajoutez de nouveaux réseaux avecwallet_addEthereumChain(EIP-3085). - Les bibliothèques de niveau supérieur comme ethers.js v6, viem et wagmi enveloppent le fournisseur brut ; les Snaps étendent MetaMask lui-même.
- Utilisez Apidog pour tester les points de terminaison JSON-RPC, simuler les réponses de transaction et déboguer les signatures avant le déploiement.
Qu'est-ce que l'API MetaMask ?
L'API MetaMask est l'interface que MetaMask expose aux pages web et aux applications pour interagir avec Ethereum et les chaînes compatibles EVM. Dans un navigateur, l'extension injecte un objet fournisseur à window.ethereum, et cet objet suit la norme EIP-1193. Toute dApp qui cible cette norme fonctionne avec MetaMask, Coinbase Wallet, Rabby, Frame et des dizaines d'autres sans aucune modification de code.
En dehors du navigateur, le SDK MetaMask vous donne la même forme de fournisseur dans React Native, Node.js pur, les applications de bureau Electron, et même les scripts côté serveur. Le SDK gère la danse du deep-linking et du code QR qui permet à un portefeuille MetaMask mobile de signer des transactions demandées par un processus de bureau ou de backend. En coulisses, il utilise toujours EIP-1193, de sorte que le code de votre application change à peine.
MetaMask propose également des Snaps, un système de plugins qui permet à des tiers d'étendre le portefeuille avec de nouvelles chaînes, des méthodes RPC personnalisées et des types de compte. Les Snaps ne sont pas abordés ici, mais il est bon de les connaître si vous souhaitez prendre en charge des chaînes non-EVM ou des flux de signature personnalisés au sein de MetaMask lui-même.
Authentification et configuration
Il n'y a pas de clés API pour le fournisseur lui-même. L'authentification consiste pour l'utilisateur à approuver chaque requête dans l'interface utilisateur de son portefeuille. Vous avez besoin de deux choses : un moyen de détecter le fournisseur, et un moyen d'écouter les changements.
Commencez par la détection. L'aide @metamask/detect-provider gère les cas particuliers comme l'installation de plusieurs portefeuilles, mais vous pouvez également vérifier directement.
// Détection Vanilla JS
import detectEthereumProvider from '@metamask/detect-provider';
const provider = await detectEthereumProvider({ mustBeMetaMask: true });
if (!provider) {
alert('Veuillez installer MetaMask');
} else {
console.log('MetaMask détecté');
}
Une fois que vous avez le fournisseur, branchez les écouteurs d'événements avant de faire toute demande. Perdre l'événement accountsChanged est le bug d'intégration MetaMask le plus courant.
window.ethereum.on('accountsChanged', (accounts) => {
if (accounts.length === 0) {
console.log('Utilisateur déconnecté');
} else {
console.log('Compte actif :', accounts[0]);
}
});
window.ethereum.on('chainChanged', (chainId) => {
// Bonne pratique : recharger la page lors d'un changement de chaîne
window.location.reload();
});
Pour les applications React, wagmi gère tout cela pour vous et détecte MetaMask automatiquement via son connecteur injecté.
Points de terminaison principaux
Tous les appels de fournisseur passent par window.ethereum.request({ method, params }). Le nom de la méthode est une chaîne JSON-RPC, et les paramètres sont un tableau ou un objet selon la méthode. Voici les appels qui couvrent 95 % des intégrations de dApp.
Demander des comptes et lire la chaîne
// Inviter l'utilisateur à se connecter
const accounts = await window.ethereum.request({
method: 'eth_requestAccounts',
});
const account = accounts[0];
// Lire la chaîne actuelle
const chainId = await window.ethereum.request({
method: 'eth_chainId',
});
console.log(account, chainId); // '0x...' '0x1' (Ethereum mainnet)
L'appel JSON-RPC brut équivalent, que vous pouvez déclencher sur n'importe quel nœud Ethereum, ressemble à ceci avec curl.
curl https://mainnet.infura.io/v3/YOUR_KEY \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
Pour les appels en lecture seule, vous n'avez pas du tout besoin de MetaMask ; les fournisseurs de nœuds comme Alchemy ou Infura servent le même RPC. Consultez notre guide de l'API Alchemy pour une vue complète des nœuds Ethereum hébergés.
Signer un message simple
personal_sign est la signature classique lisible par l'homme. Il préfixe le message afin que les utilisateurs ne puissent pas être trompés et signer des octets de transaction arbitraires.
const message = 'Se connecter à Apidog le ' + new Date().toISOString();
const signature = await window.ethereum.request({
method: 'personal_sign',
params: [message, account],
});
Signer des données structurées avec EIP-712
Pour tout ce qui est complexe, comme un permis ou un défi de connexion, utilisez eth_signTypedData_v4. MetaMask affiche les champs proprement dans la fenêtre contextuelle de confirmation, ce qui protège les utilisateurs et renforce la confiance.
const typedData = {
domain: { name: 'Démo Apidog', version: '1', chainId: 1 },
types: {
EIP712Domain: [
{ name: 'name', type: 'string' },
{ name: 'version', type: 'string' },
{ name: 'chainId', type: 'uint256' },
],
Login: [
{ name: 'wallet', type: 'address' },
{ name: 'nonce', type: 'uint256' },
],
},
primaryType: 'Login',
message: { wallet: account, nonce: 42 },
};
const sig = await window.ethereum.request({
method: 'eth_signTypedData_v4',
params: [account, JSON.stringify(typedData)],
});
Envoyer une transaction
Les transactions utilisent eth_sendTransaction. MetaMask gère automatiquement l'estimation du gaz et la gestion du nonce.
const txHash = await window.ethereum.request({
method: 'eth_sendTransaction',
params: [{
from: account,
to: '0xAdresseDestinataireIci',
value: '0x38d7ea4c68000', // 0.001 ETH en wei, hex
}],
});
Changer ou ajouter une chaîne
EIP-3326 et EIP-3085 couvrent le passage à une chaîne connue et l'ajout d'une nouvelle.
// Passer à Polygon (chainId 137 = 0x89)
try {
await window.ethereum.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: '0x89' }],
});
} catch (err) {
if (err.code === 4902) {
// Chaîne pas encore ajoutée
await window.ethereum.request({
method: 'wallet_addEthereumChain',
params: [{
chainId: '0x89',
chainName: 'Polygon',
rpcUrls: ['https://polygon-rpc.com'],
nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
}],
});
}
}
React avec le SDK MetaMask
Le SDK fonctionne également bien dans React standard lorsque vous souhaitez un chemin d'intégration unique qui couvre l'extension de bureau, le deep-link mobile et le navigateur in-app.
import { MetaMaskProvider, useSDK } from '@metamask/sdk-react';
function Connect() {
const { sdk, connected, account } = useSDK();
return (
<button onClick={() => sdk?.connect()}>
{connected ? account : 'Connecter MetaMask'}
</button>
);
}
export default function App() {
return (
<MetaMaskProvider sdkOptions={{ dappMetadata: { name: 'Ma dApp' } }}>
<Connect />
</MetaMaskProvider>
);
}
Pour les applications de production, enveloppez le fournisseur brut dans ethers.js v6 ou viem. Ils vous donnent des contrats typés, des décodeurs ABI et de meilleurs messages d'erreur tout en parlant toujours à la même API MetaMask sous-jacente. Si vous avez également besoin d'une connexion par e-mail ou via les réseaux sociaux comme solution de secours, associez MetaMask à un portefeuille intégré via notre guide de l'API Privy.
Erreurs courantes et limites de débit
MetaMask renvoie des codes d'erreur JSON-RPC standard. Ceux que vous rencontrerez le plus souvent :
4001: L'utilisateur a rejeté la requête. Affichez un message "connexion annulée" convivial et ne réessayez pas automatiquement.4100: Non autorisé. Le compte n'est pas connecté ; appelez d'abordeth_requestAccounts.4200: Méthode non prise en charge. Rare, mais confirmez que le portefeuille est MetaMask avant d'appeler des méthodes spécifiques au fournisseur.4902: Chaîne non ajoutée. Enchaînez avecwallet_addEthereumChain.-32002: Requête déjà en attente. Les utilisateurs cliquent parfois deux fois sur le bouton ; dédupliquez de votre côté.
Le fournisseur lui-même n'a pas de limite de débit, mais le RPC sous-jacent en a. Si vous proxyfiez les lectures via Infura ou Alchemy, vous êtes lié par leur niveau de service. Pour les flux fiat comme la conversion ETH-USD, la plupart des équipes associent cette intégration à une API d'on-ramp et d'off-ramp fiat afin que les utilisateurs puissent recharger sans quitter la dApp.
Tarification de l'API MetaMask
L'extension MetaMask et le SDK sont gratuits. Il n'y a pas de frais par connexion, par signature ou par transaction. MetaMask tire ses revenus des frais de swap lorsque les utilisateurs échangent à l'intérieur du portefeuille et via la carte MetaMask, et non des développeurs de dApps.
Les coûts que vous paierez proviennent du point de terminaison RPC que votre dApp utilise pour les lectures. Un niveau gratuit Alchemy ou Infura suffit pour la plupart des petites applications ; les dApps de production se situent généralement entre 49 $ et 299 $ par mois pour un débit dédié.
Tester l'API MetaMask avec Apidog
La signature basée sur le navigateur est difficile à déboguer car le flux de requête s'étend sur une extension, une page et parfois un deep-link mobile. C'est là qu'Apidog gagne sa place dans la boîte à outils des développeurs de portefeuilles. Vous pouvez interroger le point de terminaison JSON-RPC brut utilisé par votre dApp, confirmer que eth_chainId et eth_getBalance renvoient ce que vous attendez, et enregistrer l'ensemble du flux comme une suite de tests.
Importez la spécification JSON-RPC Ethereum, définissez l'URL de votre nœud comme variable d'environnement, et vous disposez d'une collection réutilisable pour chaque chaîne EVM. Apidog simule également les réponses, de sorte que vos développeurs frontend peuvent travailler sur un faux eth_sendTransaction pendant que le contrat intelligent est encore en audit. Pour l'intégration continue (CI), vous pouvez exécuter la même collection depuis la ligne de commande et faire échouer la build si la forme d'une réponse change. Si vous avez eu des difficultés avec des collections Postman qui ne se synchronisent jamais au sein de l'équipe, notre guide sur les tests d'API sans Postman en 2026 explique pourquoi Apidog gère mieux les tests de dApps multiprotocoles.
Téléchargez Apidog pour commencer.
FAQ
L'API MetaMask fonctionne-t-elle sur mobile ?Oui. Utilisez le SDK MetaMask, qui effectue un deep-link vers l'application mobile pour la signature. L'interface du fournisseur est identique à celle de l'extension de navigateur, donc votre code reste le même. Pour une comparaison plus approfondie avec d'autres SDK de portefeuilles mobiles, consultez notre aperçu des meilleures API de portefeuilles crypto.
Quelle est la différence entre eth_sign, personal_sign et eth_signTypedData_v4 ?eth_sign signe des octets bruts et est dangereux ; MetaMask avertit agressivement les utilisateurs. personal_sign préfixe un message lisible par l'homme. eth_signTypedData_v4 signe des données structurées EIP-712 et affiche les champs clairement dans l'interface utilisateur de MetaMask. Utilisez les deux derniers ; évitez eth_sign.
Ai-je besoin d'une clé API distincte de MetaMask ?Non. Le fournisseur est gratuit et sans clé. Vous avez besoin d'un fournisseur RPC comme Alchemy ou Infura pour les lectures en dehors du portefeuille, qui ont leurs propres clés.
Puis-je utiliser ethers.js ou viem avec MetaMask ?Oui, les deux enveloppent le fournisseur window.ethereum. Ethers v6 expose BrowserProvider(window.ethereum), et viem a createWalletClient({ transport: custom(window.ethereum) }). La plupart des dApps de production utilisent l'un des deux.
Que se passe-t-il si un utilisateur a plusieurs portefeuilles installés ?MetaMask implémente EIP-6963, de sorte que les dApps peuvent détecter tous les portefeuilles installés au lieu de se disputer window.ethereum. Wagmi et RainbowKit gèrent cela automatiquement.
MetaMask Snaps est-il prêt pour la production ?Oui, Snaps est devenu généralement disponible en 2024. La plupart des utilisations en production concernent la prise en charge des chaînes non-EVM, des informations personnalisées sur les transactions et des intégrations de portefeuilles matériels.