Blog

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

Ashley Innocent

Ashley Innocent

23 April 2026

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

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

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

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

버튼

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

TL;DR

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에서 각 요청을 승인하는 방식입니다. 프로바이더를 감지하는 방법과 변경 사항을 수신하는 두 가지가 필요합니다.

감지부터 시작하세요. @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가 감지되었습니다');
}

프로바이더를 얻었다면, 무엇이든 요청하기 전에 이벤트 리스너를 연결하세요. accountsChanged 이벤트를 놓치는 것이 가장 흔한 MetaMask 통합 버그입니다.

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는 이 모든 것을 자동으로 처리하며 주입된 커넥터를 통해 MetaMask를 자동으로 감지합니다.

핵심 엔드포인트

모든 프로바이더 호출은 window.ethereum.request({ method, params })를 통해 이루어집니다. 메서드 이름은 JSON-RPC 문자열이며, params는 메서드에 따라 배열 또는 객체입니다. 다음은 dApp 통합의 95%를 다루는 호출들입니다.

계정 요청 및 체인 읽기

// 사용자에게 연결 요청
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)

모든 이더리움 노드에 전송할 수 있는 해당 원시 JSON-RPC 호출은 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}'

읽기 전용 호출에는 MetaMask가 전혀 필요 없습니다. Alchemy 또는 Infura와 같은 노드 프로바이더는 동일한 RPC를 제공합니다. 호스팅된 이더리움 노드에 대한 전체 그림은 Alchemy API 가이드를 참조하세요.

간단한 메시지 서명

personal_sign은 고전적인 사람이 읽을 수 있는 서명입니다. 메시지에 접두사를 붙여 사용자가 임의의 트랜잭션 바이트에 서명하도록 속지 않도록 합니다.

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

EIP-712로 구조화된 데이터 서명

허가(permit) 또는 로그인 챌린지와 같이 복잡한 작업에는 eth_signTypedData_v4를 사용하세요. MetaMask는 확인 팝업에서 필드를 깔끔하게 렌더링하여 사용자를 보호하고 신뢰를 구축합니다.

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

트랜잭션 전송

트랜잭션은 eth_sendTransaction을 사용합니다. MetaMask는 가스 예측 및 논스 관리를 자동으로 처리합니다.

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

체인 전환 또는 추가

EIP-3326 및 EIP-3085는 알려진 체인으로 전환하고 새 체인을 추가하는 것을 다룹니다.

// Polygon으로 전환 (chainId 137 = 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으로 원시 프로바이더를 래핑하세요. 이들은 동일한 MetaMask API와 통신하면서도 타입이 지정된 계약, ABI 디코더, 더 나은 오류 메시지를 제공합니다. 이메일 또는 소셜 로그인이 폴백으로 필요한 경우, Privy API 가이드를 통해 MetaMask를 임베디드 지갑과 페어링하세요.

일반적인 오류 및 속도 제한

MetaMask는 표준 JSON-RPC 오류 코드를 반환합니다. 가장 자주 접하게 될 오류 코드는 다음과 같습니다:

프로바이더 자체에는 속도 제한이 없지만, 기본 RPC에는 있습니다. Infura 또는 Alchemy를 통해 읽기를 프록시하는 경우 해당 티어에 의해 제한됩니다. ETH-USD 변환과 같은 법정화폐 흐름의 경우, 대부분의 팀은 이 통합을 법정화폐 온/오프램프 API와 함께 사용하여 사용자가 dApp을 떠나지 않고도 충전할 수 있도록 합니다.

MetaMask API 가격 책정

MetaMask 확장 프로그램과 SDK는 무료입니다. 연결당, 서명당 또는 트랜잭션당 비용이 청구되지 않습니다. MetaMask는 사용자가 지갑 내에서 거래할 때 발생하는 스왑 수수료와 MetaMask 카드를 통해 수익을 얻으며, dApp 개발자로부터는 얻지 않습니다.

지불하게 될 비용은 dApp이 읽기를 위해 호출하는 RPC 엔드포인트에서 발생합니다. 무료 Alchemy 또는 Infura 티어는 대부분의 소규모 앱을 처리하며, 프로덕션 dApp은 전용 처리량을 위해 일반적으로 월 $49에서 $299 사이의 비용이 듭니다.

Apidog로 MetaMask API 테스트하기

브라우저 기반 서명은 요청 흐름이 확장 프로그램, 페이지, 때로는 모바일 딥링크에 걸쳐 있기 때문에 디버깅하기 어렵습니다. 바로 이 지점에서 Apidog가 지갑 개발자 툴킷에서 그 역할을 합니다. dApp이 사용하는 원시 JSON-RPC 엔드포인트를 호출하여 eth_chainId 및 eth_getBalance가 예상대로 반환되는지 확인하고 전체 흐름을 테스트 스위트로 저장할 수 있습니다.

이더리움 JSON-RPC 사양을 가져오고, 노드 URL을 환경 변수로 설정하면 모든 EVM 체인에 대한 재사용 가능한 컬렉션을 갖게 됩니다. Apidog는 또한 응답을 모의하므로, 스마트 계약이 아직 감사 중인 동안에도 프론트엔드 개발자는 가짜 eth_sendTransaction에 대해 개발할 수 있습니다. CI의 경우, 명령줄에서 동일한 컬렉션을 실행하고 응답 형식이 변경되면 빌드를 실패시킬 수 있습니다. 팀 전체에 걸쳐 동기화되지 않는 Postman 컬렉션과 씨름해 왔다면, 2026년 Postman 없이 API 테스트하기에 대한 저희 가이드에서 Apidog가 다중 프로토콜 dApp 테스트를 더 잘 처리하는 이유를 설명합니다.

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 데이터에 서명하고 MetaMask UI에서 필드를 깔끔하게 보여줍니다. 마지막 두 가지를 사용하고, eth_sign은 피하세요.

MetaMask와 별도의 API 키가 필요한가요?아니요. 프로바이더는 무료이며 키가 필요 없습니다. 지갑 외부에서 읽기 작업을 위해서는 Alchemy 또는 Infura와 같은 RPC 프로바이더가 필요하며, 이들은 자체 키를 가지고 있습니다.

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는 프로덕션 준비가 되었나요?네, Snaps는 2024년에 정식 출시되었습니다. 대부분의 프로덕션 사용은 비-EVM 체인 지원, 맞춤형 트랜잭션 인사이트 및 하드웨어 지갑 통합을 위한 것입니다.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드