Antoine Laurent

Posted on Apr 23 • Originally published at apidog.com

Comment utiliser l'API MetaMask : Connectez votre dApp aux portefeuilles Ethereum

MetaMask est la passerelle par défaut vers Ethereum pour des dizaines de millions d'utilisateurs. Si vous développez une dApp, l'API MetaMask fait le lien entre votre interface utilisateur et les clés de vos utilisateurs. Cette API se compose du fournisseur injecté window.ethereum (conforme à l’EIP-1193) et du SDK MetaMask pour les environnements mobiles, React Native et Node.js. Maîtriser le fournisseur, c’est couvrir l’essentiel des intégrations portefeuille côté web.

Essayez Apidog dès aujourd'hui

Ce tutoriel montre comment :

détecter le fournisseur,
demander les comptes,
lire la chaîne active,
signer des messages (personal_sign, EIP-712),
envoyer des transactions,
ajouter/changer de chaîne,
utiliser le SDK MetaMask hors navigateur.

Il explique aussi comment utiliser ethers.js v6, viem en tant que wrappers, et où Apidog s’intègre pour tester les appels JSON-RPC sans code frontend.

Si votre projet touche aux wallets, ajoutez ce guide à vos favoris, et consultez également notre comparatif des meilleures API de portefeuille crypto.

TL;DR

L'API MetaMask expose le fournisseur EIP-1193 via window.ethereum, plus le SDK pour mobile & Node.
Démarrez avec eth_requestAccounts pour connecter l'utilisateur, puis écoutez accountsChanged et chainChanged.
Signez avec personal_sign (message simple) et eth_signTypedData_v4 (EIP-712, données structurées).
Changez de réseau avec wallet_switchEthereumChain (EIP-3326), ajoutez-en un avec wallet_addEthereumChain (EIP-3085).
Utilisez ethers.js, viem, wagmi comme wrappers, Snaps pour étendre MetaMask.
Apidog facilite les tests JSON-RPC, la simulation de transactions et le debug des signatures.

Qu'est-ce que l'API MetaMask ?

MetaMask expose une API pour interagir avec Ethereum et les chaînes compatibles EVM. Dans un navigateur, l’extension injecte le fournisseur window.ethereum conforme à EIP-1193. Toute dApp sur ce standard fonctionne sans changement avec MetaMask, Coinbase Wallet, Rabby, Frame, etc.

Hors navigateur, le SDK MetaMask fournit une interface équivalente pour React Native, Node.js, Electron, scripts backend. Il gère le deep-linking mobile, les QR codes, et conserve une compatibilité EIP-1193 : le code de votre app reste pratiquement identique.

MetaMask propose aussi les Snaps, des plugins tiers pour prendre en charge de nouveaux réseaux, RPC ou comptes. Hors scope ici, mais à connaître pour supporter des chaînes non-EVM ou des signatures personnalisées.

Authentification et configuration

Aucune clé API n’est nécessaire côté fournisseur. L'utilisateur autorise chaque requête via l’UI de MetaMask. Il faut :

Détecter le fournisseur
Écouter les changements de compte/chaîne

Détection avec @metamask/detect-provider :

// 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é');
}

Branchez les listeners avant toute requête :

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 lors d'un changement de chaîne
  window.location.reload();
});

Pour React, wagmi gère ces étapes via son connecteur injecté.

Points de terminaison principaux

Toutes les requêtes passent par :

window.ethereum.request({ method, params })

method: chaîne JSON-RPC
params: tableau ou objet

Demander des comptes & lire la chaîne

// Connexion utilisateur
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Chaîne courante
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

console.log(account, chainId); // '0x...' '0x1'

Appel JSON-RPC équivalent :

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 lectures, un node provider (Alchemy, Infura…) suffit. Consultez notre guide Alchemy API.

Signer un message simple

personal_sign : signature lisible, message préfixé.

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 (EIP-712)

Pour les flux complexes (permis, challenge), utilisez eth_signTypedData_v4. L'utilisateur voit les champs structurés.

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

eth_sendTransaction gère le gaz et le 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/EIP-3085 pour changer ou ajouter une chaîne :

// Passer à Polygon (chainId 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Non ajouté : proposer l'ajout
    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 MetaMask fonctionne aussi dans React pour gérer extension, deep-link mobile et 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 la prod, utilisez ethers.js v6 ou viem autour du provider brut pour de meilleurs outils (contrats typés, décodage ABI, erreurs explicites). Pour ajouter une connexion e-mail/social fallback, consultez notre guide Privy API.

Erreurs courantes et limites de débit

Codes d’erreur standards :

4001 : Utilisateur a rejeté (affichez "connexion annulée", ne réessayez pas).
4100 : Non autorisé (compte non connecté ; appelez eth_requestAccounts).
4200 : Méthode non supportée (confirmez le wallet avant d’utiliser des méthodes spécifiques).
4902 : Chaîne non ajoutée (enchaînez avec wallet_addEthereumChain).
-32002 : Requête déjà en attente (dédupliquez côté UI).

Le fournisseur n’impose aucune limite de débit, mais le node RPC (Infura, Alchemy…) oui. Pour la gestion fiat (ex : conversion ETH-USD), intégrez une API d’on/off ramp fiat.

Tarification de l'API MetaMask

L’extension et le SDK MetaMask sont gratuits. Aucun frais par signature ou transaction côté dApp. MetaMask se rémunère sur les swaps ou la carte, pas sur les développeurs.

Le coût dépend du node RPC utilisé (Infura, Alchemy…). Un plan gratuit suffit pour protos ; la prod coûte généralement 49-299 $/mois pour un débit élevé.

Tester l'API MetaMask avec Apidog

La signature navigateur est difficile à déboguer (extension, page, mobile). Apidog s’intègre dans le workflow dev wallet :

Interrogez le JSON-RPC utilisé par votre dApp
Vérifiez que eth_chainId, eth_getBalance renvoient bien ce qui est attendu
Enregistrez tout le flux comme suite de tests
Importez la spec JSON-RPC Ethereum, définissez l’URL de node en variable d’environnement, et réutilisez la collection pour chaque chaîne EVM
Simulez les réponses pour travailler côté frontend sans backend live
Exécutez la collection en CI/CD et faites échouer la build si la forme de réponse change

Apidog gère mieux les tests dApps multiprotocoles que Postman. Consultez notre guide sur les tests d’API sans Postman en 2026.

Téléchargez Apidog pour commencer.

FAQ

L'API MetaMask fonctionne-t-elle sur mobile ?

Oui, via le SDK MetaMask qui deep-link vers l’app mobile. L’interface fournisseur est identique à l’extension. Pour la comparaison avec d’autres SDK wallets mobiles, voir notre comparatif API wallets crypto.

Différences entre eth_sign, personal_sign, eth_signTypedData_v4 ?

eth_sign : octets bruts (dangereux, à éviter)
personal_sign : message lisible, préfixé
eth_signTypedData_v4 : données structurées EIP-712, UI claire Utilisez uniquement les deux derniers.

Ai-je besoin d’une clé API MetaMask ?

Non. Le provider est sans clé, gratuit. Pour les lectures hors wallet, il vous faut une clé RPC (Alchemy, Infura…).

Puis-je utiliser ethers.js ou viem avec MetaMask ?

Oui.

Ethers v6 : BrowserProvider(window.ethereum)
Viem : createWalletClient({ transport: custom(window.ethereum) }) La plupart des dApps utilisent l’un des deux.

Que si l’utilisateur a plusieurs wallets installés ?

MetaMask implémente EIP-6963, permettant de détecter tous les wallets installés (wagmi, RainbowKit gèrent ça automatiquement).

MetaMask Snaps est-il mature pour la prod ?

Oui, disponible depuis 2024. Utilisé en prod pour : support de chaînes non-EVM, infos personnalisées sur transactions, intégration hardware wallet.

DEV Community