Roobia

Posted on Apr 23 • Originally published at apidog.com

Cómo Usar la API de MetaMask: Conecta tu dApp a Carteras Ethereum

MetaMask es la puerta de entrada principal a Ethereum para millones de usuarios. Si desarrollas una dApp, la API de MetaMask es el vínculo clave entre tu frontend y las claves del usuario. La “API de MetaMask” abarca dos componentes: el proveedor window.ethereum inyectado (EIP-1193) y el SDK de MetaMask, que extiende esa interfaz a móvil, React Native y backends en Node.js. Si dominas el proveedor, tendrás resuelto el 80% de cualquier integración de wallet en web.

Prueba Apidog hoy mismo

Esta guía cubre cómo detectar el proveedor, solicitar cuentas, obtener la red activa, firmar mensajes con personal_sign y EIP-712, enviar transacciones, cambiar/añadir redes y emplear el SDK de MetaMask fuera del navegador. También verás cómo ethers.js v6 y viem funcionan como wrappers, y dónde Apidog encaja para probar llamadas JSON-RPC sin programar un frontend temporal.

Si tu proyecto interactúa con wallets, guarda esta guía y revisa también nuestra comparativa de la mejor API de cartera de criptomonedas para entender el panorama de proveedores.

En resumen

MetaMask expone el proveedor EIP-1193 en window.ethereum (navegadores) y el SDK para móvil/Node.
Empieza con eth_requestAccounts para conectar, luego escucha accountsChanged y chainChanged.
Firma mensajes con personal_sign o datos estructurados con eth_signTypedData_v4 (EIP-712).
Cambia de red con wallet_switchEthereumChain (EIP-3326) y añade nuevas con wallet_addEthereumChain (EIP-3085).
Wrappers como ethers.js v6, viem y wagmi facilitan la integración; Snaps extiende MetaMask.
Usa Apidog para probar endpoints JSON-RPC, simular transacciones y depurar firmas antes de desplegar.

¿Qué es la API de MetaMask?

La API de MetaMask es la interfaz que permite a páginas web y apps interactuar con Ethereum y cadenas EVM-compatible. En el navegador, la extensión inyecta window.ethereum siguiendo EIP-1193. Cualquier dApp que siga ese estándar funcionará con MetaMask, Coinbase Wallet, Rabby, Frame y otros sin cambios.

Fuera del navegador, el SDK de MetaMask replica esa interfaz en React Native, Node.js, Electron e incluso scripts backend. El SDK gestiona deep-linking y QR para que una wallet móvil firme transacciones generadas desde un proceso de escritorio o servidor, manteniendo compatibilidad EIP-1193.

MetaMask también soporta Snaps, un sistema de plugins para ampliar la wallet con nuevas cadenas, métodos RPC y tipos de cuenta personalizados. Snaps no se trata en esta guía, pero es clave si necesitas cadenas no EVM o flujos de firma avanzados.

Autenticación y configuración

No necesitas claves API para el proveedor. La autenticación depende de la aprobación explícita del usuario en su wallet. Debes detectar el proveedor y escuchar eventos clave.

Detección del proveedor

El paquete @metamask/detect-provider gestiona casos con múltiples wallets instaladas, pero puedes hacer una verificación simple:

// Detección básica en JS
import detectEthereumProvider from '@metamask/detect-provider';

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

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

Escucha de eventos

Conecta los listeners antes de cualquier solicitud para no perder eventos críticos.

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) => {
  // Buenas prácticas: recargar la página al cambiar de red
  window.location.reload();
});

En React, wagmi automatiza estas tareas usando su conector inyectado.

Endpoints principales

Usa window.ethereum.request({ method, params }) para todas las llamadas. El método es un string JSON-RPC; los params, un array u objeto según el método.

Solicitar cuentas y leer la red

// Solicita conexión al usuario
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Lee la red actual
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

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

Llamada JSON-RPC raw equivalente (por ejemplo, usando 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 lecturas, puedes usar cualquier proveedor RPC como Alchemy o Infura. Consulta la guía de la API de Alchemy para más detalles.

Firmar un mensaje simple

personal_sign permite firmas legibles (útil para autenticación).

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

Firmar datos estructurados (EIP-712)

Para permisos o login más seguros, usa eth_signTypedData_v4.

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 una transacción

MetaMask gestiona automáticamente gas y nonce.

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

Cambiar o añadir red

Usa EIP-3326/EIP-3085 para cambiar o agregar redes.

// Cambiar a Polygon (chainId 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Red no añadida aún
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon',
        rpcUrls: ['https://polygon-rpc.com'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
      }],
    });
  }
}

Integración en React con el SDK de MetaMask

El SDK cubre extensión de escritorio, deep-link móvil y navegador in-app con una sola integración.

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 sdkOptions={{ dappMetadata: { name: 'My dApp' } }}>
      <Connect />
    </MetaMaskProvider>
  );
}

Para producción, envuelve el proveedor en ethers.js v6 o viem para obtener contratos tipados, decodificación ABI y mejores errores. Si necesitas login con email o redes sociales como respaldo, combina MetaMask con una wallet embebida usando la API de Privy.

Errores comunes y límites de tasa

MetaMask devuelve errores estándar JSON-RPC:

4001: Usuario rechazó la solicitud. Informa al usuario y no reintentes automáticamente.
4100: No autorizado. Solicita eth_requestAccounts primero.
4200: Método no soportado. Verifica que la wallet sea MetaMask para métodos específicos.
4902: Red no añadida. Usa wallet_addEthereumChain.
-32002: Solicitud ya pendiente. Evita dobles clics implementando debounce.

El proveedor MetaMask no limita el rate, pero el RPC sí (ej: Infura, Alchemy). Para conversiones fiat (ETH a USD), combina la integración con una API de rampa fiat para que los usuarios recarguen sin salir de la dApp.

Precios de la API de MetaMask

La extensión y el SDK de MetaMask son gratuitos. No hay cargos por conexión, firma ni transacción. MetaMask genera ingresos con comisiones de swap y servicios, no por uso de la API. El coste depende del endpoint RPC (ej: Alchemy/Infura). El nivel gratuito cubre prototipos; producción suele oscilar entre $49 y $299/mes por mayor rendimiento.

Probando la API de MetaMask con Apidog

Depurar firmas en navegador es complejo por la interacción entre extensión, página y deep-link móvil. Aquí destaca Apidog: prueba endpoints JSON-RPC directamente, verifica eth_chainId y eth_getBalance, y guarda flows como tests.

Importa la spec Ethereum JSON-RPC, configura la URL del nodo como variable de entorno y tendrás una colección reutilizable para cualquier cadena EVM. Apidog permite simular respuestas (ej: eth_sendTransaction) para que el frontend avance mientras el smart contract está en auditoría. Puedes correr los tests desde CLI y fallar builds si la respuesta cambia. Si Postman no sincroniza bien tu equipo, revisa nuestra guía sobre pruebas de API sin Postman para dApps multiprotocolo.

Descarga Apidog para comenzar.

Preguntas frecuentes

¿Funciona la API de MetaMask en móvil?

Sí. Usa el SDK de MetaMask, que realiza deep-link a la app móvil para firmar. La interfaz es idéntica a la extensión, así que el código no cambia. Para comparar con otros SDK de wallets móviles, revisa nuestra comparativa de APIs de carteras.

¿Diferencias entre eth_sign, personal_sign y eth_signTypedData_v4?

eth_sign firma bytes raw (peligroso); MetaMask alerta al usuario. personal_sign añade un prefijo legible. eth_signTypedData_v4 firma datos estructurados EIP-712 y muestra los campos en la UI. Usa los dos últimos, evita eth_sign.

¿Necesito una clave API de MetaMask?

No. El proveedor es libre y sin clave. Para lecturas fuera de la wallet, sí necesitas una clave de RPC como Alchemy o Infura.

¿Puedo usar ethers.js o viem con MetaMask?

Sí. Ambos envuelven window.ethereum. Ethers v6 ofrece BrowserProvider(window.ethereum); viem usa createWalletClient({ transport: custom(window.ethereum) }). Son estándar en producción.

¿Qué pasa si el usuario tiene varias wallets instaladas?

MetaMask implementa EIP-6963: las dApps pueden detectar todas las wallets instaladas. Wagmi y RainbowKit gestionan esto automáticamente.

¿Snaps de MetaMask está listo para producción?

Sí, desde 2024. Se usa principalmente para soporte de cadenas no EVM, información personalizada en transacciones e integraciones con hardware wallets.

DEV Community