MetaMask Integration: Complete Developer Guide

Introduction to MetaMask Integration

MetaMask is the most popular Ethereum wallet with over 30 million users. Integrating MetaMask into your dApp is essential for user onboarding and transaction signing.

This comprehensive guide covers everything from basic connection to advanced features like custom networks and transaction handling.

Detecting and Connecting MetaMask

First, detect if MetaMask is installed by checking for the ethereum object in the window. Modern MetaMask injects window.ethereum as the provider.

Request account access using eth_requestAccounts method. This prompts users to connect their wallet and grant permission to your dApp.

Handle the connection flow:
Check if MetaMask is installed
Request account access
Handle user rejection gracefully
Store connected account in state
Listen for account changes

Always provide clear instructions for users without MetaMask installed. Link to MetaMask download page and explain why they need a wallet.

Never auto-connect without user action. Users should explicitly choose to connect their wallet for security and privacy.

Handling Account and Network Changes

Users can switch accounts or networks at any time. Your dApp must handle these changes properly.

Listen for accountsChanged event to detect when users switch accounts. Update your UI and clear any account-specific data.

Listen for chainChanged event to detect network switches. Reload the page or update your provider to match the new network.

Implement proper error handling:
User rejects connection request
MetaMask is locked
Wrong network selected
Transaction fails or is rejected

Provide clear feedback for each scenario. Show loading states during transactions and clear error messages when things go wrong.

Consider implementing automatic network switching to guide users to the correct network for your dApp.

Sending Transactions

Use eth_sendTransaction to send transactions through MetaMask. Users review and sign transactions in the MetaMask popup.

Transaction parameters:
from: sender address (must be connected account)
to: recipient address
value: amount in wei (for ETH transfers)
data: encoded function call (for contract interactions)
gas: gas limit (optional, MetaMask estimates)
gasPrice: gas price (optional, MetaMask suggests)

For contract interactions, encode function calls using ethers.js or web3.js. Pass the encoded data in the transaction.

Handle transaction lifecycle:
User reviews transaction in MetaMask
User confirms or rejects
Transaction is broadcast to network
Wait for transaction confirmation
Handle success or failure

Always show transaction status to users. Provide transaction hash for tracking on block explorers.

Best Practices and Security

Security considerations:

Never request private keys. MetaMask handles key management securely.

Validate all user inputs before sending transactions. Prevent injection attacks and invalid data.

Use proper error handling and user feedback. Clear messages help users understand what's happening.

Implement transaction simulation when possible. Show users what will happen before they sign.

Test on testnets thoroughly before mainnet deployment. Use Goerli or Sepolia for testing.

Consider implementing wallet connection libraries like RainbowKit or Web3Modal. These provide better UX and support multiple wallets.

Keep your integration updated with latest MetaMask features and best practices. The wallet ecosystem evolves rapidly.

MetaMask integration is the gateway to your dApp. A smooth connection experience encourages user adoption and engagement.