MetaMask API Nutzung: dApp mit Ethereum Wallets verbinden

MetaMask ist die standardmäßige Einstiegsstelle zu Ethereum für zig Millionen von Nutzern. Wenn Sie eine dApp betreiben, ist die MetaMask API die Schnittstelle zwischen Ihrer Benutzeroberfläche und den Signierschlüsseln der Nutzer. Die MetaMask API besteht aus dem injizierten window.ethereum-Provider (definiert durch EIP-1193) sowie dem MetaMask SDK, das dieselbe Oberfläche auf mobile Apps, React Native und Node.js-Backends erweitert. Wer den Provider beherrscht, deckt damit 80 % der Wallet-Integration im Web ab.

Probiere Apidog heute aus

In diesem Leitfaden lernen Sie Schritt für Schritt: Provider erkennen, Konten anfordern, aktuelle Chain auslesen, Nachrichten mit personal_sign und EIP-712 signieren, Transaktionen senden, Chains hinzufügen oder wechseln und das MetaMask SDK außerhalb des Browsers verwenden. Sie sehen außerdem, wie ethers.js v6 und viem als Wrapper integriert werden und wie Apidog beim Testen von JSON-RPC-Aufrufen ohne aufwändigen Frontend-Code hilft.

Wenn Sie an Wallet-Integrationen arbeiten, speichern Sie diesen Leitfaden zusammen mit unserem Leitfaden zur besten Krypto-Wallet-API, um die gesamte Provider-Landschaft im Blick zu behalten.

TL;DR

• Die MetaMask API ist der EIP-1193-Provider unter window.ethereum, plus das MetaMask SDK für Mobile und Node.
• Einstieg: eth_requestAccounts verwenden und auf accountsChanged sowie chainChanged lauschen.
• Nachrichten signieren mit personal_sign, strukturierte Daten mit eth_signTypedData_v4 (EIP-712).
• Netzwerke wechseln mit wallet_switchEthereumChain (EIP-3326), neue Chains mit wallet_addEthereumChain (EIP-3085) hinzufügen.
• Bibliotheken wie ethers.js v6, viem und wagmi kapseln den Provider; Snaps erweitern MetaMask selbst.
• Mit Apidog JSON-RPC-Endpunkte testen, Transaktionsantworten simulieren und Signaturen debuggen.

Was ist die MetaMask API?

Die MetaMask API ist die Schnittstelle für Webseiten und Apps, um mit Ethereum und EVM-kompatiblen Chains zu interagieren. Im Browser injiziert die Erweiterung ein Provider-Objekt unter window.ethereum, das dem EIP-1193-Standard folgt. Jede dApp, die darauf setzt, läuft direkt mit MetaMask, Coinbase Wallet, Rabby, Frame und vielen weiteren Wallets.

Außerhalb des Browsers bietet das MetaMask SDK dieselbe Provider-Struktur in React Native, Node.js, Electron und sogar serverseitigen Skripten. Das SDK übernimmt Deep-Linking und QR-Code-Flows, damit mobile MetaMask-Wallets Transaktionen aus externen Prozessen signieren können – Ihr App-Code bleibt weitgehend identisch.

MetaMask unterstützt darüber hinaus Snaps, ein Plugin-System für Drittanbieter, um neue Chains, eigene RPC-Methoden oder Kontotypen zu integrieren. Snaps sind nicht Schwerpunkt dieses Artikels, aber relevant, falls Sie Non-EVM-Chains oder spezielle Signaturabläufe unterstützen möchten.

Authentifizierung und Einrichtung

Für den Provider gibt es keine API-Schlüssel. Die Authentifizierung erfolgt durch die explizite Zustimmung des Nutzers in der Wallet. Sie benötigen:

1. Erkennung des Providers.
2. Event-Listener für Änderungen.

Der Helper @metamask/detect-provider löst Sonderfälle (z. B. mehrere Wallets), Sie können aber auch direkt prüfen:

// Vanilla JS detection
import detectEthereumProvider from '@metamask/detect-provider';

const provider = await detectEthereumProvider({ mustBeMetaMask: true });

if (!provider) {
  alert('Please install MetaMask');
} else {
  console.log('MetaMask detected');
}

Sobald der Provider erkannt ist, Listener für Events einrichten:

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('User disconnected');
  } else {
    console.log('Active account:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // Best practice: reload the page on chain change
  window.location.reload();
});

Für React-Apps übernimmt wagmi diese Erkennung und das Event-Handling automatisch.

Kern-Endpunkte

Alle Provider-Aufrufe laufen über window.ethereum.request({ method, params }). Der Methodenname ist ein JSON-RPC-String, params ein Array oder Objekt. Die wichtigsten Methoden für die Umsetzung:

Konten anfordern und Chain auslesen

// Prompt the user to connect
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Read the current chain
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

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

Roher JSON-RPC-Aufruf (z. B. für 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}'

Für reine Lesezugriffe ist MetaMask nicht erforderlich – Node-Provider wie Alchemy oder Infura liefern dieselbe RPC. Details: Alchemy API-Leitfaden.

Eine einfache Nachricht signieren

personal_sign eignet sich für menschenlesbare Signaturen und schützt vor dem Signieren beliebiger Bytes:

const message = 'Sign in to Apidog at ' + new Date().toISOString();
const signature = await window.ethereum.request({
  method: 'personal_sign',
  params: [message, account],
});

Strukturierte Daten mit EIP-712 signieren

Für komplexe Workflows wie Login-Challenges oder Genehmigungen:

const typedData = {
  domain: { name: 'Apidog Demo', 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)],
});

Eine Transaktion senden

Transaktionen via eth_sendTransaction – Gas-Schätzung und Nonce-Management übernimmt MetaMask:

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere',
    value: '0x38d7ea4c68000', // 0.001 ETH in wei, hex
  }],
});

Eine Chain wechseln oder hinzufügen

Chains wechseln (EIP-3326) oder hinzufügen (EIP-3085):

// Switch to Polygon (chainId 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Chain not added yet
    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 mit dem MetaMask SDK

Für universelle Integration (Desktop, Mobile, In-App-Browser) bietet das SDK einen React-Hook:

import { MetaMaskProvider, useSDK } from '@metamask/sdk-react';

function Connect() {
  const { sdk, connected, account } = useSDK();
  return (
    <button onClick={() => sdk?.connect()}>
      {connected ? account : 'Connect MetaMask'}
    </button>
  );
}

export default function App() {
  return (
    <MetaMaskProvider>
      <Connect />
    </MetaMaskProvider>
  );
}

Für Produktions-Apps empfiehlt sich der Einsatz von ethers.js v6 oder viem als Wrapper um den Provider. Diese bieten typisierte Contracts, ABI-Decoder und bessere Fehlermeldungen – unter der Haube bleibt die MetaMask API erhalten. Für E-Mail-/Social-Login als Fallback: siehe Privy API-Leitfaden.

Häufige Fehler und Ratenbegrenzungen

MetaMask gibt standardisierte JSON-RPC-Fehlercodes zurück. Die häufigsten:

• 4001: Benutzer lehnt ab. Zeigen Sie eine „Verbindung abgebrochen“-Nachricht und versuchen Sie es nicht automatisch erneut.
• 4100: Nicht autorisiert. Erst eth_requestAccounts aufrufen.
• 4200: Methode nicht unterstützt. Prüfen, ob MetaMask wirklich verwendet wird.
• 4902: Chain nicht hinzugefügt. Danach wallet_addEthereumChain aufrufen.
• -32002: Anfrage bereits ausstehend. Button-Clicks auf Ihrer Seite entprellen.

Der Provider selbst hat keine Rate Limits, aber der zugrundeliegende RPC-Endpoint schon. Wer Lesezugriffe über Infura oder Alchemy routet, ist an deren Tarif gebunden. Für Fiat-Flows wie ETH-zu-USD: Kombinieren Sie dies mit einer Fiat On-Ramp-/Off-Ramp-API.

MetaMask API-Preise

Die MetaMask-Erweiterung und das SDK sind kostenlos – keine Gebühren pro Verbindung, Signatur oder Transaktion. MetaMask verdient an Swap-Gebühren und der MetaMask Card, nicht an dApp-Entwicklern.

Kosten entstehen nur durch Ihren RPC-Provider (z. B. Alchemy, Infura). Kostenlos-Tarife reichen für kleine Apps, produktive dApps liegen meist zwischen 49 und 299 US-Dollar/Monat für dedizierte Kapazität.

Testen der MetaMask API mit Apidog

Das Debuggen browserbasierten Signierens ist komplex: Es involviert Erweiterung, Webseite und oft mobiles Deep-Linking. Hier ist Apidog das perfekte Tool. Sie können den JSON-RPC-Endpoint direkt ansprechen, Methoden wie eth_chainId und eth_getBalance testen und den Ablauf als Testsuite speichern.

Importieren Sie die Ethereum JSON-RPC-Spezifikation, legen Sie Ihre Node-URL als Umgebungsvariable fest und erhalten eine wiederverwendbare Sammlung für jede EVM-Chain. Apidog simuliert auch Antworten, sodass Frontend-Entwickler gegen einen gefälschten eth_sendTransaction entwickeln können, während Smart Contracts noch geprüft werden. Die gleiche Sammlung lässt sich in der CI ausführen – Build schlägt fehl, wenn sich Antwortstrukturen ändern. Mehr zu Multi-Protokoll-dApp-Tests und dem Vergleich mit Postman: API-Testen ohne Postman im Jahr 2026.

Laden Sie Apidog herunter, um loszulegen.

FAQ

• Funktioniert die MetaMask API auf Mobilgeräten?
  
  Ja. Verwenden Sie das MetaMask SDK, das Deep-Links zur mobilen App nutzt. Die Provider-Oberfläche bleibt identisch, der Code ebenfalls. Für Vergleiche zu anderen mobilen Wallet-SDKs siehe unsere Übersicht der besten Krypto-Wallet-APIs.

• Was ist der Unterschied zwischen eth_sign, personal_sign und eth_signTypedData_v4?
  
  eth_sign signiert rohe Bytes und ist gefährlich; MetaMask warnt explizit. personal_sign präfixt menschenlesbare Nachrichten. eth_signTypedData_v4 signiert strukturierte EIP-712-Daten und zeigt Felder übersichtlich in der MetaMask-Oberfläche. Nutzen Sie bevorzugt die letzten beiden Methoden.

• Benötige ich einen separaten API-Schlüssel von MetaMask?
  
  Nein. Der Provider ist kostenlos und benötigt keinen Schlüssel. Für Lesezugriffe außerhalb der Wallet brauchen Sie allerdings einen RPC-Provider wie Alchemy oder Infura, die eigene Schlüssel verlangen.

• Kann ich ethers.js oder viem mit MetaMask nutzen?
  
  Ja, beide kapseln den window.ethereum-Provider. Ethers v6: BrowserProvider(window.ethereum), viem: createWalletClient({ transport: custom(window.ethereum) }). Die meisten Produktions-dApps nutzen einen dieser beiden Wrapper.

• Was passiert bei mehreren installierten Wallets?
  
  MetaMask unterstützt EIP-6963, sodass dApps alle installierten Wallets erkennen können, anstatt um window.ethereum zu konkurrieren. Wagmi und RainbowKit regeln dies automatisch.

• Ist MetaMask Snaps produktionsreif?
  
  Ja, Snaps ist seit 2024 allgemein verfügbar. Hauptanwendungsbereiche: Non-EVM-Chains, benutzerdefinierte Transaktionseinblicke, Hardware-Wallet-Integration.