Blog

Como Usar a API MetaMask: Conecte Seu dApp a Carteiras Ethereum

Ashley Innocent

Ashley Innocent

23 abril 2026

Como Usar a API MetaMask: Conecte Seu dApp a Carteiras Ethereum

MetaMask é a porta de entrada padrão para Ethereum para dezenas de milhões de usuários, e se você executa um dApp, a API do MetaMask é o que fica entre sua interface de usuário e suas chaves de assinatura. A “API do MetaMask” é duas coisas disfarçadas: o provedor window.ethereum injetado definido pelo EIP-1193, e o SDK do MetaMask que estende a mesma superfície para aplicativos móveis, React Native e backends Node.js. Entenda o provedor, e você terá aprendido 80% de todas as integrações de carteira na web.

Este guia aborda como detectar o provedor, solicitar contas, ler a cadeia atual, assinar mensagens com personal_sign e EIP-712, enviar transações, adicionar ou trocar cadeias, e usar o SDK do MetaMask quando você estiver fora de uma extensão de navegador. Você também verá onde ethers.js v6 e viem se encaixam como wrappers de nível superior, e onde Apidog se encaixa no fluxo de trabalho quando você deseja testar as chamadas JSON-RPC subjacentes sem escrever código frontend descartável.

botão

Se você está construindo algo que envolve carteiras, marque isto junto com nosso guia sobre a melhor API de carteira de criptomoedas para uma visão mais ampla do cenário de provedores.

TL;DR

O que é a API do MetaMask?

A API do MetaMask é a interface que o MetaMask expõe a páginas web e aplicativos para interagir com Ethereum e cadeias compatíveis com EVM. Em um navegador, a extensão injeta um objeto provedor em window.ethereum, e esse objeto segue o padrão EIP-1193. Qualquer dApp que vise esse padrão funciona com MetaMask, Coinbase Wallet, Rabby, Frame e dezenas de outros com zero alterações no código.

Fora do navegador, o SDK do MetaMask oferece a mesma estrutura de provedor em React Native, Node.js puro, aplicativos desktop Electron e até scripts do lado do servidor. O SDK lida com o deep-linking e a dança do QR-code que permite que uma carteira MetaMask móvel assine transações solicitadas por um processo desktop ou backend. Por baixo dos panos, ele ainda se comunica via EIP-1193, então o código do seu aplicativo mal muda.

O MetaMask também oferece Snaps, um sistema de plugins que permite que terceiros estendam a carteira com novas cadeias, métodos RPC personalizados e tipos de conta. Snaps estão fora do escopo aqui, mas vale a pena conhecer se você quiser suportar cadeias não-EVM ou fluxos de assinatura personalizados dentro do próprio MetaMask.

Autenticação e configuração

Não há chaves de API para o próprio provedor. A autenticação é o usuário aprovando cada solicitação em sua interface de carteira. Você precisa de duas coisas: uma maneira de detectar o provedor e uma maneira de ouvir as mudanças.

Comece com a detecção. O helper @metamask/detect-provider lida com casos extremos como múltiplas carteiras instaladas, mas você também pode verificar diretamente.

// Detecção com Vanilla JS
import detectEthereumProvider from '@metamask/detect-provider';

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

if (!provider) {
  alert('Por favor, instale o MetaMask');
} else {
  console.log('MetaMask detectado');
}

Depois de ter o provedor, configure os listeners de eventos antes de solicitar qualquer coisa. Perder o evento accountsChanged é o bug de integração do MetaMask mais comum.

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('Usuário desconectado');
  } else {
    console.log('Conta ativa:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // Boa prática: recarregar a página na mudança de cadeia
  window.location.reload();
});

Para aplicativos React, o wagmi lida com tudo isso para você e detecta o MetaMask automaticamente através de seu conector injetado.

Endpoints principais

Todas as chamadas do provedor passam por window.ethereum.request({ method, params }). O nome do método é uma string JSON-RPC, e params é um array ou objeto dependendo do método. Aqui estão as chamadas que cobrem 95% das integrações de dApps.

Solicitar contas e ler a cadeia

// Solicita ao usuário para conectar
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Lê a cadeia atual
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

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

A chamada JSON-RPC bruta equivalente, que você pode disparar em qualquer nó Ethereum, se parece com isto com 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}'

Para chamadas somente leitura, você não precisa do MetaMask; provedores de nós como Alchemy ou Infura servem o mesmo RPC. Veja nosso [guia da API da Alchemy](http://apidog.com/blog/how-to-use-alchemy-api) para ter a visão completa sobre nós Ethereum hospedados.

Assinar uma mensagem simples

personal_sign é a assinatura clássica legível por humanos. Ela prefixa a mensagem para que os usuários não possam ser enganados a assinar bytes de transação arbitrários.

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

Assinar dados estruturados com EIP-712

Para qualquer coisa complexa, como uma permissão ou um desafio de login, use eth_signTypedData_v4. O MetaMask renderiza os campos de forma clara no popup de confirmação, o que protege os usuários e constrói confiança.

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)],
});

Enviar uma transação

Transações usam eth_sendTransaction. O MetaMask lida com a estimativa de gás e o gerenciamento de nonce automaticamente.

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

Trocar ou adicionar uma cadeia

EIP-3326 e EIP-3085 cobrem a troca para uma cadeia conhecida e a adição de uma nova.

// Trocar para Polygon (chainId 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Cadeia ainda não adicionada
    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 com o SDK do MetaMask

O SDK também funciona bem no React comum quando você deseja um único caminho de integração que cubra extensão desktop, deep-link móvel e navegador in-app.

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

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

export default function App() {
  return (
    <MetaMaskProvider sdkOptions={{ dappMetadata: { name: 'My dApp' } }}>
      <Connect />
    </MetaMaskProvider>
  );
}

Para aplicativos de produção, envolva o provedor bruto em ethers.js v6 ou viem. Eles oferecem contratos tipados, decodificadores ABI e melhores mensagens de erro, enquanto ainda se comunicam com a mesma API do MetaMask por baixo. Se você também precisar de login por e-mail ou social como fallback, combine o MetaMask com uma carteira embutida através do nosso [guia da API Privy](http://apidog.com/blog/how-to-use-privy-api).

Erros comuns e limites de taxa

MetaMask retorna códigos de erro JSON-RPC padrão. Os que você encontrará com mais frequência:

O provedor em si não tem limite de taxa, mas o RPC subjacente tem. Se você está fazendo proxy de leituras através de Infura ou Alchemy, você está vinculado ao seu nível de serviço. Para fluxos fiduciários como conversão de ETH para USD, a maioria das equipes combina esta integração com uma API de on-ramp e off-ramp fiduciário para que os usuários possam recarregar sem sair do dApp.

Preços da API do MetaMask

A extensão MetaMask e o SDK são gratuitos. Não há cobrança por conexão, por assinatura ou por transação. O MetaMask gera receita através de taxas de swap quando os usuários negociam dentro da carteira e através do MetaMask Card, não de desenvolvedores de dApps.

Os custos que você pagará vêm do endpoint RPC que seu dApp acessa para leituras. Uma camada gratuita da Alchemy ou Infura atende à maioria dos aplicativos pequenos; dApps de produção geralmente custam entre $49 e $299 por mês para um throughput dedicado.

Testando a API do MetaMask com Apidog

A assinatura baseada em navegador é difícil de depurar porque o fluxo de solicitação abrange uma extensão, uma página e, às vezes, um deep-link móvel. É aí que o Apidog ganha seu lugar no kit de ferramentas de desenvolvimento de carteiras. Você pode acessar o endpoint JSON-RPC bruto que seu dApp usa, confirmar que eth_chainId e eth_getBalance retornam o que você espera, e salvar todo o fluxo como uma suíte de testes.

Importe a especificação JSON-RPC do Ethereum, defina a URL do seu nó como uma variável de ambiente, e você terá uma coleção reutilizável para cada cadeia EVM. O Apidog também simula respostas, para que seus desenvolvedores frontend possam construir contra um eth_sendTransaction falso enquanto o contrato inteligente ainda está em auditoria. Para CI, você pode executar a mesma coleção da linha de comando e falhar a build se o formato da resposta mudar. Se você tem lutado com coleções do Postman que nunca sincronizam entre a equipe, nosso guia sobre teste de API sem Postman em 2026 explica por que o Apidog lida melhor com o teste de dApps multi-protocolo.

Baixe o Apidog para começar.

FAQ

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar