MetaMask adalah pintu gerbang default ke Ethereum bagi puluhan juta pengguna, dan jika Anda menjalankan dApp, MetaMask API adalah jembatan antara UI Anda dan kunci penandatanganan mereka. "MetaMask API" adalah dua hal yang menyatu: penyedia window.ethereum yang diinjeksi yang didefinisikan oleh EIP-1193, dan MetaMask SDK yang memperluas antarmuka yang sama ke aplikasi seluler, React Native, dan backend Node.js. Pelajari penyedia ini, dan Anda telah mempelajari 80% dari setiap integrasi dompet di web.
Panduan ini membahas deteksi penyedia, permintaan akun, pembacaan rantai saat ini, penandatanganan pesan dengan personal_sign dan EIP-712, pengiriman transaksi, penambahan atau penggantian rantai, dan penggunaan MetaMask SDK ketika Anda berada di luar ekstensi browser. Anda juga akan melihat di mana ethers.js v6 dan viem cocok sebagai pembungkus tingkat yang lebih tinggi, dan di mana Apidog berperan dalam alur kerja ketika Anda ingin menguji panggilan JSON-RPC yang mendasarinya tanpa menulis kode frontend yang tidak perlu.
Jika Anda membangun sesuatu yang berhubungan dengan dompet, tandai ini bersama panduan kami tentang API dompet kripto terbaik untuk pandangan yang lebih luas tentang lanskap penyedia.
TL;DR
- MetaMask API adalah penyedia EIP-1193 yang terekspos di
window.ethereumdi browser, ditambah MetaMask SDK untuk seluler dan Node. - Mulai dengan
eth_requestAccountsuntuk meminta pengguna terhubung, lalu dengarkan eventaccountsChangeddanchainChanged. - Tanda tangani pesan dengan
personal_sign, dan tanda tangani data terstruktur denganeth_signTypedData_v4(EIP-712). - Ganti jaringan dengan
wallet_switchEthereumChain(EIP-3326) dan tambahkan yang baru denganwallet_addEthereumChain(EIP-3085). - Pustaka tingkat tinggi seperti ethers.js v6, viem, dan wagmi membungkus penyedia mentah; Snaps memperluas fungsionalitas MetaMask itu sendiri.
- Gunakan Apidog untuk menguji endpoint JSON-RPC, memalsukan respons transaksi, dan men-debug tanda tangan sebelum rilis.
Apa itu MetaMask API?
MetaMask API adalah antarmuka yang diekspos MetaMask ke halaman web dan aplikasi untuk berinteraksi dengan Ethereum dan rantai yang kompatibel dengan EVM. Di browser, ekstensi menyuntikkan objek penyedia di window.ethereum, dan objek tersebut mengikuti standar EIP-1193. Setiap dApp yang menargetkan standar tersebut berfungsi dengan MetaMask, Coinbase Wallet, Rabby, Frame, dan lusinan lainnya tanpa perubahan kode.
Di luar browser, MetaMask SDK memberi Anda bentuk penyedia yang sama di React Native, Node.js murni, aplikasi Electron desktop, dan bahkan skrip sisi server. SDK menangani mekanisme deep-linking dan kode QR yang memungkinkan dompet MetaMask seluler menandatangani transaksi yang diminta oleh proses desktop atau backend. Di balik layar, ia masih berbicara EIP-1193, sehingga kode aplikasi Anda hampir tidak berubah.
MetaMask juga menyediakan Snaps, sistem plugin yang memungkinkan pihak ketiga memperluas dompet dengan rantai baru, metode RPC khusus, dan jenis akun. Snaps berada di luar cakupan bahasan ini, tetapi penting untuk diketahui jika Anda ingin mendukung rantai non-EVM atau alur penandatanganan khusus di dalam MetaMask itu sendiri.
Autentikasi dan pengaturan
Tidak ada kunci API untuk penyedia itu sendiri. Autentikasi adalah pengguna menyetujui setiap permintaan di UI dompet mereka. Anda memerlukan dua hal: cara untuk mendeteksi penyedia, dan cara untuk mendengarkan perubahan.
Mulai dengan deteksi. Pembantu `@metamask/detect-provider` menangani kasus-kasus khusus seperti beberapa dompet yang terinstal, tetapi Anda juga dapat memeriksa secara langsung.
// 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');
}
Setelah Anda memiliki penyedia, sambungkan pendengar event sebelum Anda meminta apa pun. Kehilangan event `accountsChanged` adalah bug integrasi MetaMask yang paling umum.
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();
});
Untuk aplikasi React, wagmi menangani semua ini untuk Anda dan secara otomatis mendeteksi MetaMask melalui konektor yang diinjeksikan.
Endpoint Utama
Semua panggilan penyedia dilakukan melalui window.ethereum.request({ method, params }). Nama metode adalah string JSON-RPC, dan `params` adalah array atau objek tergantung pada metode. Berikut adalah panggilan yang mencakup 95% integrasi dApp.
Minta akun dan baca rantai
// 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)
Panggilan JSON-RPC mentah yang setara, yang dapat Anda panggil pada node Ethereum mana pun, terlihat seperti ini dengan 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}'
Untuk panggilan hanya-baca, Anda sama sekali tidak memerlukan MetaMask; penyedia node seperti Alchemy atau Infura melayani RPC yang sama. Lihat panduan API Alchemy kami untuk gambaran lengkap tentang node Ethereum yang di-hosting.
Menandatangani pesan sederhana
personal_sign adalah tanda tangan klasik yang dapat dibaca manusia. Ini menambahkan awalan pada pesan sehingga pengguna tidak dapat ditipu untuk menandatangani byte transaksi yang sembarangan.
const message = 'Sign in to Apidog at ' + new Date().toISOString();
const signature = await window.ethereum.request({
method: 'personal_sign',
params: [message, account],
});
Menandatangani data terstruktur dengan EIP-712
Untuk sesuatu yang kompleks, seperti izin atau tantangan login, gunakan eth_signTypedData_v4. MetaMask menampilkan bidang-bidang dengan rapi di pop-up konfirmasi, yang melindungi pengguna dan membangun kepercayaan.
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)],
});
Mengirim transaksi
Transaksi menggunakan eth_sendTransaction. MetaMask menangani estimasi gas dan manajemen nonce secara otomatis.
const txHash = await window.ethereum.request({
method: 'eth_sendTransaction',
params: [{
from: account,
to: '0xRecipientAddressHere',
value: '0x38d7ea4c68000', // 0.001 ETH in wei, hex
}],
});
Mengganti atau menambahkan rantai
EIP-3326 dan EIP-3085 mencakup penggantian ke rantai yang dikenal dan penambahan rantai baru.
// 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 },
}],
});
}
}
Integrasi React dengan MetaMask SDK
SDK juga berfungsi dengan baik di React biasa ketika Anda menginginkan jalur integrasi tunggal yang mencakup ekstensi desktop, deep-link seluler, dan browser dalam aplikasi.
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>
);
}
Untuk aplikasi produksi, bungkus penyedia mentah di ethers.js v6 atau viem. Mereka memberi Anda kontrak yang diketik, dekoder ABI, dan pesan kesalahan yang lebih baik sementara masih berkomunikasi dengan MetaMask API yang sama di bawahnya. Jika Anda juga memerlukan login email atau sosial sebagai cadangan, pasangkan MetaMask dengan dompet tersemat melalui panduan API Privy kami.
Kesalahan Umum dan Batasan Tingkat Permintaan
MetaMask mengembalikan kode kesalahan JSON-RPC standar. Yang paling sering Anda temui adalah:
4001: Pengguna menolak permintaan. Tampilkan pesan "koneksi dibatalkan" yang ramah dan jangan coba lagi secara otomatis.4100: Tidak sah. Akun tidak terhubung; panggileth_requestAccountsterlebih dahulu.4200: Metode tidak didukung. Jarang terjadi, tetapi pastikan dompetnya adalah MetaMask sebelum memanggil metode khusus vendor.4902: Rantai belum ditambahkan. Lanjutkan denganwallet_addEthereumChain.-32002: Permintaan sudah tertunda. Pengguna terkadang mengklik tombol dua kali; gunakan debounce di sisi Anda.
Penyedia itu sendiri tidak memiliki batasan tingkat permintaan, tetapi RPC yang mendasarinya memilikinya. Jika Anda melakukan proxy pembacaan melalui Infura atau Alchemy, Anda terikat oleh tingkatan mereka. Untuk alur fiat seperti konversi ETH-ke-USD, sebagian besar tim memasangkan integrasi ini dengan API on-ramp dan off-ramp fiat sehingga pengguna dapat mengisi ulang tanpa meninggalkan dApp.
Harga MetaMask API
Ekstensi MetaMask dan SDK gratis. Tidak ada biaya per koneksi, per tanda tangan, atau per transaksi. MetaMask memperoleh pendapatan melalui biaya swap ketika pengguna berdagang di dalam dompet dan melalui Kartu MetaMask, bukan dari pengembang dApp.
Biaya yang akan Anda bayar berasal dari endpoint RPC yang diakses dApp Anda untuk pembacaan. Tingkat gratis Alchemy atau Infura menangani sebagian besar aplikasi kecil; dApp produksi biasanya menghabiskan antara $49 dan $299 per bulan untuk throughput khusus.
Menguji MetaMask API dengan Apidog
Penandatanganan berbasis browser sulit di-debug karena alur permintaan mencakup ekstensi, halaman, dan terkadang deep-link seluler. Di sinilah Apidog mendapatkan tempatnya dalam toolkit pengembang dompet. Anda dapat memanggil endpoint JSON-RPC mentah yang digunakan dApp Anda, mengonfirmasi bahwa eth_chainId dan eth_getBalance mengembalikan apa yang Anda harapkan, dan menyimpan seluruh alur sebagai rangkaian pengujian.
Impor spesifikasi Ethereum JSON-RPC, atur URL node Anda sebagai variabel lingkungan, dan Anda memiliki koleksi yang dapat digunakan kembali untuk setiap rantai EVM. Apidog juga memalsukan respons, sehingga pengembang frontend Anda dapat membangun berdasarkan `eth_sendTransaction` palsu sementara kontrak pintar masih dalam audit. Untuk CI, Anda dapat menjalankan koleksi yang sama dari baris perintah dan menggagalkan build jika bentuk respons berubah. Jika Anda kesulitan dengan koleksi Postman yang tidak pernah sinkron di seluruh tim, panduan kami tentang pengujian API tanpa Postman di tahun 2026 menjelaskan mengapa Apidog menangani pengujian dApp multi-protokol dengan lebih baik.
Untuk memulai, Unduh Apidog.
FAQ
Apakah MetaMask API berfungsi di perangkat seluler?Ya. Gunakan MetaMask SDK, yang melakukan deep-link ke aplikasi seluler untuk penandatanganan. Antarmuka penyedia identik dengan ekstensi browser, sehingga kode Anda tetap sama. Untuk perbandingan lebih dalam dengan SDK dompet seluler lainnya, lihat rangkuman API dompet kripto terbaik kami.
Apa perbedaan antara eth_sign, personal_sign, dan eth_signTypedData_v4?eth_sign menandatangani byte mentah dan berbahaya; MetaMask memperingatkan pengguna secara agresif. personal_sign menambahkan awalan pada pesan yang dapat dibaca manusia. eth_signTypedData_v4 menandatangani data EIP-712 terstruktur dan menampilkan bidang dengan rapi di UI MetaMask. Gunakan dua yang terakhir; hindari eth_sign.
Apakah saya memerlukan kunci API terpisah dari MetaMask?Tidak. Penyedia ini gratis dan tidak memerlukan kunci. Anda memerlukan penyedia RPC seperti Alchemy atau Infura untuk pembacaan di luar dompet, yang memiliki kuncinya sendiri.
Dapatkah saya menggunakan ethers.js atau viem dengan MetaMask?Ya, keduanya membungkus penyedia window.ethereum. Ethers v6 mengekspos `BrowserProvider(window.ethereum)`, dan viem memiliki `createWalletClient({ transport: custom(window.ethereum) })`. Sebagian besar dApp produksi menggunakan salah satu dari keduanya.
Apa yang terjadi jika pengguna memiliki beberapa dompet yang terinstal?MetaMask mengimplementasikan EIP-6963, sehingga dApp dapat mendeteksi semua dompet yang terinstal alih-alih berebut `window.ethereum`. Wagmi dan RainbowKit menanganinya secara otomatis.
Apakah MetaMask Snaps siap untuk produksi?Ya, Snaps telah tersedia secara umum pada tahun 2024. Sebagian besar penggunaan produksi adalah untuk dukungan rantai non-EVM, insight transaksi khusus, dan integrasi dompet perangkat keras.