MetaMask es la rampa de acceso por defecto a Ethereum para decenas de millones de usuarios, y si ejecutas una dApp, la API de MetaMask es lo que se interpone entre tu interfaz de usuario y sus claves de firma. La "API de MetaMask" son dos cosas en una gabardina: el proveedor window.ethereum inyectado definido por EIP-1193, y el SDK de MetaMask que extiende esa misma superficie a aplicaciones móviles, React Native y backends de Node.js. Aprende el proveedor, y habrás aprendido el 80% de cada integración de cartera en la web.
Esta guía explica cómo detectar el proveedor, solicitar cuentas, leer la cadena actual, firmar mensajes con personal_sign y EIP-712, enviar transacciones, añadir o cambiar cadenas, y usar el SDK de MetaMask cuando estás fuera de una extensión de navegador. También verás dónde encajan ethers.js v6 y viem como wrappers de nivel superior, y dónde Apidog se integra en el flujo de trabajo cuando quieres probar las llamadas JSON-RPC subyacentes sin escribir código frontend desechable.
Si estás construyendo algo que interactúa con carteras, marca esta guía junto con nuestra guía sobre la mejor API de cartera de criptomonedas para tener una visión más amplia del panorama de proveedores.
En resumen
- La API de MetaMask es el proveedor EIP-1193 expuesto en
window.ethereumen navegadores, más el SDK de MetaMask para móvil y Node. - Comienza con
eth_requestAccountspara pedir al usuario que se conecte, luego escucha los eventosaccountsChangedychainChanged. - Firma mensajes con
personal_sign, y firma datos estructurados coneth_signTypedData_v4(EIP-712). - Cambia de red con
wallet_switchEthereumChain(EIP-3326) y añade nuevas conwallet_addEthereumChain(EIP-3085). - Bibliotecas de nivel superior como ethers.js v6, viem y wagmi envuelven el proveedor raw; Snaps extiende el propio MetaMask.
- Usa Apidog para probar los endpoints JSON-RPC, simular respuestas de transacciones y depurar firmas antes de la implementación.
¿Qué es la API de MetaMask?
La API de MetaMask es la interfaz que MetaMask expone a las páginas web y aplicaciones para interactuar con Ethereum y las cadenas compatibles con EVM. En un navegador, la extensión inyecta un objeto proveedor en window.ethereum, y ese objeto sigue el estándar EIP-1193. Cualquier dApp que apunte a ese estándar funciona con MetaMask, Coinbase Wallet, Rabby, Frame y docenas de otros sin cambios de código.
Fuera del navegador, el SDK de MetaMask te proporciona la misma forma de proveedor en React Native, Node.js puro, aplicaciones de escritorio Electron e incluso scripts del lado del servidor. El SDK gestiona el deep-linking y la "danza" del código QR que permite que una cartera móvil de MetaMask firme transacciones solicitadas por un proceso de escritorio o backend. Bajo el capó, sigue hablando EIP-1193, por lo que el código de tu aplicación apenas cambia.
MetaMask también incluye Snaps, un sistema de plugins que permite a terceros extender la cartera con nuevas cadenas, métodos RPC personalizados y tipos de cuenta. Snaps está fuera del alcance de esta guía, pero vale la pena conocerlo si quieres soportar cadenas no EVM o flujos de firma personalizados dentro del propio MetaMask.
Autenticación y configuración
No hay claves API para el proveedor en sí. La autenticación consiste en que el usuario apruebe cada solicitud en la interfaz de su cartera. Necesitas dos cosas: una forma de detectar el proveedor y una forma de escuchar los cambios.
Comienza con la detección. El ayudante @metamask/detect-provider maneja casos límite como la instalación de múltiples carteras, pero también puedes verificarlo directamente.
// 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');
}
Una vez que tengas el proveedor, conecta los oyentes de eventos antes de solicitar cualquier cosa. Perder el evento accountsChanged es el error de integración de MetaMask más común.
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();
});
Para las aplicaciones React, wagmi se encarga de todo esto por ti y detecta MetaMask automáticamente a través de su conector inyectado.
Endpoints principales
Todas las llamadas al proveedor se realizan a través de window.ethereum.request({ method, params }). El nombre del método es una cadena JSON-RPC, y params es un array u objeto dependiendo del método. Aquí están las llamadas que cubren el 95% de las integraciones de dApps.
Solicitar cuentas y leer la cadena
// 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)
La llamada JSON-RPC raw equivalente, que puedes enviar a cualquier nodo de Ethereum, se ve así con 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 las llamadas de solo lectura no necesitas MetaMask en absoluto; los proveedores de nodos como Alchemy o Infura sirven el mismo RPC. Consulta nuestra guía de la API de Alchemy para obtener una visión completa sobre los nodos de Ethereum alojados.
Firmar un mensaje simple
personal_sign es la firma clásica legible por humanos. Prefija el mensaje para que los usuarios no puedan ser engañados para firmar bytes de transacción arbitrarios.
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 con EIP-712
Para cualquier cosa compleja, como un permiso o un desafío de inicio de sesión, usa eth_signTypedData_v4. MetaMask renderiza los campos de forma clara en la ventana emergente de confirmación, lo que protege a los usuarios y genera confianza.
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
Las transacciones utilizan eth_sendTransaction. MetaMask maneja la estimación del gas y la gestión del nonce automáticamente.
const txHash = await window.ethereum.request({
method: 'eth_sendTransaction',
params: [{
from: account,
to: '0xRecipientAddressHere',
value: '0x38d7ea4c68000', // 0.001 ETH in wei, hex
}],
});
Cambiar o añadir una cadena
EIP-3326 y EIP-3085 cubren el cambio a una cadena conocida y la adición de una nueva.
// 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 },
}],
});
}
}
Reaccionar con el SDK de MetaMask
El SDK también funciona bien en React normal cuando quieres una única ruta de integración que cubra la extensión de escritorio, el deep-link móvil y el navegador dentro de la aplicació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 aplicaciones de producción, envuelve el proveedor raw en ethers.js v6 o viem. Te proporcionan contratos tipados, decodificadores ABI y mejores mensajes de error mientras siguen comunicándose con la misma API de MetaMask subyacente. Si también necesitas iniciar sesión con correo electrónico o redes sociales como respaldo, empareja MetaMask con una cartera embebida a través de nuestra guía de la API de Privy.
Errores comunes y límites de tasa
MetaMask devuelve códigos de error JSON-RPC estándar. Los que encontrarás con mayor frecuencia son:
4001: El usuario rechazó la solicitud. Muestra una notificación amigable de "conexión cancelada" y no intentes de nuevo automáticamente.4100: No autorizado. La cuenta no está conectada; llama aeth_requestAccountsprimero.4200: Método no soportado. Poco frecuente, pero confirma que la cartera es MetaMask antes de llamar a métodos específicos del proveedor.4902: Cadena no añadida. Continúa conwallet_addEthereumChain.-32002: Solicitud ya pendiente. Los usuarios a veces hacen clic en el botón dos veces; implementa un "debounce" por tu parte.
El proveedor en sí no tiene límite de tasa, pero el RPC subyacente sí. Si estás haciendo proxy de lecturas a través de Infura o Alchemy, estás limitado por su nivel. Para flujos fiat como la conversión de ETH a USD, la mayoría de los equipos combinan esta integración con una API de rampa de entrada y salida fiat para que los usuarios puedan recargar sin salir de la dApp.
Precios de la API de MetaMask
La extensión de MetaMask y el SDK son gratuitos. No hay cargos por conexión, por firma o por transacción. MetaMask obtiene ingresos a través de las comisiones de intercambio cuando los usuarios comercian dentro de la cartera y a través de la tarjeta MetaMask, no de los desarrolladores de dApps.
Los costos que pagarás provienen del endpoint RPC al que tu dApp accede para las lecturas. Un nivel gratuito de Alchemy o Infura maneja la mayoría de las aplicaciones pequeñas; las dApps de producción generalmente oscilan entre $49 y $299 al mes para un rendimiento dedicado.
Probando la API de MetaMask con Apidog
La firma basada en navegador es difícil de depurar porque el flujo de solicitud abarca una extensión, una página y, a veces, un deep-link móvil. Ahí es donde Apidog se gana su lugar en el kit de herramientas para desarrolladores de carteras. Puedes acceder al endpoint JSON-RPC raw que usa tu dApp, confirmar que eth_chainId y eth_getBalance devuelven lo que esperas, y guardar todo el flujo como un conjunto de pruebas.
Importa la especificación Ethereum JSON-RPC, establece la URL de tu nodo como una variable de entorno y tendrás una colección reutilizable para cada cadena EVM. Apidog también simula respuestas, para que tus desarrolladores frontend puedan construir contra un eth_sendTransaction falso mientras el contrato inteligente aún está en auditoría. Para CI, puedes ejecutar la misma colección desde la línea de comandos y hacer que la compilación falle si la forma de una respuesta cambia. Si has estado luchando con colecciones de Postman que nunca se sincronizan en todo el equipo, nuestra guía sobre pruebas de API sin Postman en 2026 explica por qué Apidog maneja mejor las pruebas de dApps multiprotocolo.
Descarga Apidog para empezar.
Preguntas frecuentes
¿Funciona la API de MetaMask en móvil?Sí. Usa el SDK de MetaMask, que hace deep-linking a la aplicación móvil para firmar. La superficie del proveedor es idéntica a la extensión del navegador, por lo que tu código se mantiene igual. Para una comparación más profunda con otros SDK de carteras móviles, consulta nuestro resumen de las mejores API de carteras de criptomonedas.
¿Cuál es la diferencia entre eth_sign, personal_sign y eth_signTypedData_v4?eth_sign firma bytes raw y es peligroso; MetaMask advierte a los usuarios de forma agresiva. personal_sign prefija un mensaje legible por humanos. eth_signTypedData_v4 firma datos estructurados EIP-712 y muestra los campos de forma clara en la interfaz de usuario de MetaMask. Usa los dos últimos; evita eth_sign.
¿Necesito una clave API separada de MetaMask?No. El proveedor es gratuito y sin clave. Sí necesitas un proveedor de RPC como Alchemy o Infura para lecturas fuera de la cartera, los cuales tienen sus propias claves.
¿Puedo usar ethers.js o viem con MetaMask?Sí, ambos envuelven el proveedor window.ethereum. Ethers v6 expone BrowserProvider(window.ethereum), y viem tiene createWalletClient({ transport: custom(window.ethereum) }). La mayoría de las dApps de producción usan uno de los dos.
¿Qué pasa si un usuario tiene varias carteras instaladas?MetaMask implementa EIP-6963, por lo que las dApps pueden detectar todas las carteras instaladas en lugar de "pelear" por window.ethereum. Wagmi y RainbowKit manejan esto automáticamente.
¿Está MetaMask Snaps listo para producción?Sí, Snaps estuvo disponible de forma general en 2024. La mayoría de los usos en producción son para soporte de cadenas no EVM, información personalizada de transacciones e integraciones de carteras de hardware.