메타마스크 API 사용법: dApp을 이더리움 지갑에 연결하기

MetaMask는 수천만 사용자를 위한 이더리움의 기본 온램프이며, dApp을 운영한다면 MetaMask API는 UI와 사용자의 서명 키 사이에 있는 것입니다. "MetaMask API"는 트렌치코트 안에 두 가지가 숨어 있습니다: EIP-1193에 정의된 주입된 window.ethereum 프로바이더와, 동일한 인터페이스를 모바일 앱, React Native, Node.js 백엔드로 확장하는 MetaMask SDK입니다. 이 프로바이더를 배우면 웹상의 모든 지갑 통합의 80%를 배운 셈입니다.

오늘 Apidog을 바로 사용해보세요

이 가이드에서는 프로바이더 감지, 계정 요청, 현재 체인 읽기, personal_sign 및 EIP-712로 메시지 서명, 트랜잭션 전송, 체인 추가 또는 전환, 그리고 브라우저 확장 프로그램 외부에서 MetaMask SDK를 사용하는 방법을 다룹니다. 또한 ethers.js v6 및 viem이 상위 레벨 래퍼로서 어떻게 사용되는지, 그리고 일회성 프론트엔드 코드 없이 기본 JSON-RPC 호출을 테스트하고 싶을 때 Apidog가 워크플로우에 어떻게 통합되는지도 알 수 있을 것입니다.

지갑과 관련된 무언가를 구축하고 있다면, 더 넓은 프로바이더 환경을 파악하기 위해 이 가이드와 함께 최고의 암호화폐 지갑 API에 대한 저희 가이드를 북마크해 두세요.

TL;DR

• MetaMask API는 브라우저에서 window.ethereum으로 노출되는 EIP-1193 프로바이더와 모바일 및 Node용 MetaMask SDK입니다.
• 사용자에게 연결을 요청하려면 eth_requestAccounts로 시작한 다음, accountsChanged 및 chainChanged 이벤트를 수신하세요.
• personal_sign으로 메시지에 서명하고, eth_signTypedData_v4 (EIP-712)로 구조화된 데이터에 서명하세요.
• wallet_switchEthereumChain (EIP-3326)으로 네트워크를 전환하고, wallet_addEthereumChain (EIP-3085)으로 새로운 네트워크를 추가하세요.
• ethers.js v6, viem, wagmi와 같은 상위 레벨 라이브러리는 원시 프로바이더를 래핑하며, Snaps는 MetaMask 자체를 확장합니다.
• Apidog를 사용하여 JSON-RPC 엔드포인트를 테스트하고, 트랜잭션 응답을 모의하고, 배포 전에 서명을 디버그하세요.

MetaMask API란 무엇인가요?

MetaMask API는 MetaMask가 웹 페이지 및 앱에 이더리움 및 EVM 호환 체인과 상호 작용하도록 노출하는 인터페이스입니다. 브라우저에서 확장 프로그램은 window.ethereum에 프로바이더 객체를 주입하며, 이 객체는 EIP-1193 표준을 따릅니다. 이 표준을 목표로 하는 모든 dApp은 코드 변경 없이 MetaMask, Coinbase Wallet, Rabby, Frame 등 수십 가지 다른 지갑과 함께 작동합니다.

브라우저 외부에서는 MetaMask SDK가 React Native, 순수 Node.js, 데스크톱 Electron 앱, 심지어 서버 측 스크립트에서도 동일한 프로바이더 형태를 제공합니다. SDK는 데스크톱 또는 백엔드 프로세스에서 요청한 트랜잭션을 모바일 MetaMask 지갑이 서명할 수 있도록 딥링킹 및 QR 코드 프로세스를 처리합니다. 내부적으로는 여전히 EIP-1193을 사용하므로 앱 코드는 거의 변경되지 않습니다.

MetaMask는 또한 Snaps를 제공합니다. 이는 서드 파티가 새로운 체인, 맞춤형 RPC 메서드 및 계정 유형으로 지갑을 확장할 수 있게 하는 플러그인 시스템입니다. Snaps는 이 가이드의 범위를 벗어나지만, 비-EVM 체인이나 MetaMask 자체 내에서 맞춤형 서명 흐름을 지원하려면 알아둘 가치가 있습니다.

인증 및 설정

프로바이더 자체에는 API 키가 없습니다. 인증은 사용자가 지갑 UI에서 각 요청을 승인하는 방식입니다. 실제 구현을 위해서는 프로바이더 감지 및 이벤트 수신이 필수적입니다.

1. MetaMask 감지

@metamask/detect-provider를 사용하는 것이 가장 안전합니다.

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

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

if (!provider) {
  alert('MetaMask를 설치해주세요');
} else {
  console.log('MetaMask가 감지되었습니다');
}

2. 이벤트 리스너 연결

계정 또는 체인 변경 이벤트를 꼭 구독하세요. 계정 변경을 놓치는 것이 가장 흔한 버그입니다.

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('사용자 연결 해제됨');
  } else {
    console.log('활성 계정:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // 모범 사례: 체인 변경 시 페이지 새로 고침
  window.location.reload();
});

React에서는 wagmi가 이 과정을 자동화합니다. 직접 구현 시에도 위 패턴을 따르세요.

핵심 엔드포인트

모든 프로바이더 호출은 window.ethereum.request({ method, params })로 이루어집니다. 아래는 실제 활용도가 높은 메서드 예시입니다.

계정 요청 및 체인 읽기

// 사용자에게 연결 요청
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// 현재 체인 읽기
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});
console.log(account, chainId); // '0x...' '0x1' (Ethereum mainnet)

curl로 JSON-RPC를 직접 테스트하려면:

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}'

단순 읽기 용도라면 MetaMask 없이 Alchemy/Infura 등 RPC 엔드포인트를 바로 쓸 수 있습니다. 더 자세한 노드 선택은 Alchemy API 가이드 참고.

간단한 메시지 서명

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

EIP-712 구조화 데이터 서명

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

트랜잭션 전송

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

체인 전환 또는 추가

// Polygon(0x89)으로 전환
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // 아직 체인이 추가되지 않음
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon',
        rpcUrls: ['https://polygon-rpc.com'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
      }],
    });
  }
}

MetaMask SDK와 React

SDK는 데스크톱, 모바일 딥링크, 인앱 브라우저를 아우르는 통합 경로를 제공합니다. React에서는 아래와 같이 사용합니다.

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

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

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

프로덕션 앱에서는 ethers.js v6 또는 viem으로 원시 프로바이더를 래핑하면 타입 안전, ABI 디코딩, 더 나은 오류 메시지 등을 누릴 수 있습니다. 이메일/소셜 로그인 등과 페어링하려면 Privy API 가이드 참고.

일반적인 오류 및 속도 제한

MetaMask는 표준 JSON-RPC 오류 코드를 반환합니다. 주요 코드별 처리 방법은 다음과 같습니다:

• 4001: 사용자가 요청을 거부함. "연결 취소됨" 등 사용자 친화적 메시지를 띄우고 자동 재시도는 피하세요.
• 4100: 권한 없음. 계정 연결 필요. eth_requestAccounts 먼저 호출.
• 4200: 지원되지 않는 메서드. 공급업체별 메서드 호출 전 지갑이 MetaMask인지 확인.
• 4902: 체인 미등록. wallet_addEthereumChain으로 등록.
• -32002: 이미 요청 대기 중. 버튼 연타 방지 등 디바운스 처리 추천.

프로바이더 자체에는 속도 제한이 없으나, Infura/Alchemy 등 RPC 공급자의 요금제 기반 제한이 있습니다. 법정화폐 온/오프램프 흐름이 필요하다면 법정화폐 온/오프램프 API 가이드도 참고하세요.

MetaMask API 가격 책정

MetaMask 확장 프로그램과 SDK는 무료입니다. 연결, 서명, 트랜잭션당 요금 없음. MetaMask는 지갑 내 스왑 수수료, MetaMask 카드 등에서 수익을 얻으며 dApp 개발자에게 별도 요금이 없습니다.

RPC 엔드포인트 호출 시 발생하는 비용만 부담합니다. 무료 Alchemy/Infura 티어로 소규모 앱 운영 가능하며, 대규모/프로덕션은 월 $49~$299 수준의 요금제가 일반적입니다.

Apidog로 MetaMask API 테스트하기

브라우저 기반 서명은 요청 플로우가 확장 프로그램, 페이지, 딥링크 등으로 분산되어 있어 디버깅이 쉽지 않습니다. Apidog을 사용하면 아래처럼 실제 JSON-RPC 엔드포인트를 직접 호출해 결과를 확인하고, 테스트 스위트로 저장할 수 있습니다.

• eth_chainId, eth_getBalance 등 표준 메서드 실행
• 이더리움 JSON-RPC 사양 import 및 환경변수 기반 노드 URL 관리
• 응답 모킹으로 감사 전 프론트엔드 개발 가능
• CLI로 테스트 자동화 및 빌드 실패 조건 관리

Postman보다 다중 프로토콜 dApp에 더 최적화된 Apidog의 활용 사례는 2026년 Postman 없이 API 테스트하기에서 확인할 수 있습니다.

Apidog 다운로드를 통해 바로 시작해보세요.

FAQ

MetaMask API는 모바일에서 작동하나요? 네. 서명을 위해 모바일 앱으로 딥링크되는 MetaMask SDK를 사용하세요. 프로바이더 인터페이스는 브라우저 확장 프로그램과 동일하므로 코드가 변경되지 않습니다. 더 많은 모바일 지갑 SDK 비교는 최고의 암호화폐 지갑 API 요약 참고.

eth_sign, personal_sign, eth_signTypedData_v4의 차이점은? eth_sign은 원시 바이트에 서명(위험). MetaMask에서 경고 표시. personal_sign은 사람이 읽을 수 있는 메시지에 접두사 추가. eth_signTypedData_v4는 구조화된 EIP-712 데이터에 서명하며 UI에서 필드를 명확히 보여줌. 마지막 두 가지를 권장, eth_sign은 지양.

MetaMask와 별도의 API 키가 필요한가요? 아니요. 프로바이더는 무료이며 별도 키가 필요 없습니다. 읽기 용도 외부 RPC(Alchemy/Infura 등)만 별도 키 필요.

ethers.js 또는 viem을 MetaMask와 함께 쓸 수 있나요? 네, 둘 다 window.ethereum을 래핑합니다. ethers v6: BrowserProvider(window.ethereum), viem: createWalletClient({ transport: custom(window.ethereum) }) 형태로 사용. 대부분의 실서비스 dApp에서 채택.

사용자가 여러 지갑을 설치하면 어떻게 되나요? MetaMask는 EIP-6963을 구현해 dApp이 window.ethereum 충돌 없이 모든 설치 지갑을 감지할 수 있습니다. wagmi, RainbowKit 등은 이 과정을 자동화합니다.

MetaMask Snaps는 프로덕션 준비가 되었나요? 네, 2024년 정식 출시. 주요 사용처는 비-EVM 체인 지원, 맞춤형 트랜잭션 인사이트, 하드웨어 지갑 통합 등입니다.