MetaMask, on milyonlarca kullanıcı için Ethereum'a varsayılan geçiş noktasıdır ve bir dApp çalıştırıyorsanız, MetaMask API, kullanıcı arayüzünüz ile onların imzalama anahtarları arasında yer alan şeydir. “MetaMask API”si, bir trençkot giymiş iki şeydir: EIP-1193 tarafından tanımlanan enjekte edilmiş window.ethereum sağlayıcısı ve aynı yüzeyi mobil uygulamalara, React Native'e ve Node.js arka uçlarına genişleten MetaMask SDK'sı. Sağlayıcıyı öğrenirseniz, web üzerindeki her cüzdan entegrasyonunun %80'ini öğrenmiş olursunuz.
Bu rehber; sağlayıcıyı tespit etme, hesap isteme, mevcut zinciri okuma, personal_sign ve EIP-712 ile mesaj imzalama, işlem gönderme, zincir ekleme veya değiştirme ve bir tarayıcı uzantısının dışındayken MetaMask SDK'sını kullanma konularını ele almaktadır. Ayrıca, ethers.js v6 ve viem gibi üst düzey sarmalayıcıların nerede devreye girdiğini ve tek kullanımlık ön uç kodu yazmadan temel JSON-RPC çağrılarını test etmek istediğinizde Apidog'un iş akışına nasıl dahil olduğunu göreceksiniz.
Cüzdanlarla ilgili herhangi bir şey geliştiriyorsanız, sağlayıcı ortamına daha geniş bir bakış açısı için bu rehberi ve en iyi kripto cüzdan API'si hakkındaki rehberimizi favorilerinize ekleyin.
Özet
- MetaMask API, tarayıcılarda
window.ethereumadresinde bulunan EIP-1193 sağlayıcısıdır ve mobil ve Node için MetaMask SDK'sıdır. - Kullanıcıyı bağlanmaya yönlendirmek için
eth_requestAccountsile başlayın, ardındanaccountsChangedvechainChangedolaylarını dinleyin. - Mesajları
personal_signile imzalayın ve yapılandırılmış veriyieth_signTypedData_v4(EIP-712) ile imzalayın. wallet_switchEthereumChain(EIP-3326) ile ağları değiştirin vewallet_addEthereumChain(EIP-3085) ile yenilerini ekleyin.- ethers.js v6, viem ve wagmi gibi üst düzey kütüphaneler ham sağlayıcıyı sarmalar; Snaps ise MetaMask'ı kendisini genişletir.
- JSON-RPC uç noktalarını test etmek, işlem yanıtlarını taklit etmek ve dağıtımdan önce imzaları hata ayıklamak için Apidog'u kullanın.
MetaMask API Nedir?
MetaMask API, MetaMask'ın web sayfaları ve uygulamalarına Ethereum ve EVM uyumlu zincirlerle etkileşim kurmaları için sunduğu arayüzdür. Bir tarayıcıda, uzantı window.ethereum adresine bir sağlayıcı nesnesi enjekte eder ve bu nesne EIP-1193 standardına uyar. Bu standardı hedefleyen herhangi bir dApp, sıfır kod değişikliği ile MetaMask, Coinbase Wallet, Rabby, Frame ve düzinelerce başka cüzdanla çalışır.
Tarayıcının dışında, MetaMask SDK'sı size React Native'de, saf Node.js'de, masaüstü Electron uygulamalarında ve hatta sunucu tarafı betiklerinde aynı sağlayıcı yapısını sunar. SDK, bir mobil MetaMask cüzdanının masaüstü veya arka uç işlemi tarafından istenen işlemleri imzalamasına olanak tanıyan derin bağlantı ve QR kod "dansını" yönetir. Temelinde hala EIP-1193 konuşur, bu nedenle uygulama kodunuz neredeyse hiç değişmez.
MetaMask ayrıca, üçüncü tarafların cüzdanı yeni zincirler, özel RPC yöntemleri ve hesap türleri ile genişletmelerine olanak tanıyan bir eklenti sistemi olan Snaps'i de sunar. Snaps burada kapsam dışıdır, ancak EVM dışı zincirleri veya MetaMask içinde özel imzalama akışlarını desteklemek isterseniz bilmeye değerdir.
Kimlik Doğrulama ve Kurulum
Sağlayıcının kendisi için API anahtarı yoktur. Kimlik doğrulama, kullanıcının cüzdan arayüzünde her isteği onaylamasıdır. İki şeye ihtiyacınız var: sağlayıcıyı tespit etmenin bir yolu ve değişiklikleri dinlemenin bir yolu.
Tespit ile başlayın. @metamask/detect-provider yardımcısı, birden fazla cüzdanın yüklü olması gibi uç durumları ele alır, ancak doğrudan da kontrol edebilirsiniz.
// 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');
}
Sağlayıcıya sahip olduktan sonra, herhangi bir istekte bulunmadan önce olay dinleyicilerini bağlayın. accountsChanged olayını kaçırmak, en yaygın MetaMask entegrasyon hatasıdır.
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();
});
React uygulamaları için wagmi, tüm bunları sizin için halleder ve enjekte edilmiş bağlayıcısı aracılığıyla MetaMask'ı otomatik olarak algılar.
Temel Uç Noktalar
Tüm sağlayıcı çağrıları window.ethereum.request({ method, params }) üzerinden yapılır. Metot adı bir JSON-RPC dizgesidir ve params, yönteme bağlı olarak bir dizi veya nesnedir. İşte dApp entegrasyonlarının %95'ini kapsayan çağrılar.
Hesapları İste ve Zinciri Oku
// 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)
Herhangi bir Ethereum düğümüne gönderebileceğiniz eşdeğer ham JSON-RPC çağrısı, curl ile şöyle görünür.
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}'
Salt okunur çağrılar için MetaMask'a hiç ihtiyacınız yoktur; Alchemy veya Infura gibi düğüm sağlayıcıları aynı RPC'yi sunar. Barındırılan Ethereum düğümleri hakkında tam bilgi için Alchemy API rehberimize bakın.
Basit Bir Mesaj İmzala
personal_sign, klasik insan tarafından okunabilir imzadır. Mesajı ön ekler, böylece kullanıcılar rastgele işlem baytlarını imzalamaya kandırılamazlar.
const message = 'Sign in to Apidog at ' + new Date().toISOString();
const signature = await window.ethereum.request({
method: 'personal_sign',
params: [message, account],
});
EIP-712 ile Yapılandırılmış Veri İmzala
Bir izin veya oturum açma meydan okuması gibi karmaşık her şey için eth_signTypedData_v4 kullanın. MetaMask, onay açılır penceresinde alanları düzgün bir şekilde görüntüler, bu da hem kullanıcıları korur hem de güven oluşturur.
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)],
});
Bir İşlem Gönder
İşlemler eth_sendTransaction kullanır. MetaMask, gas tahmini ve nonce yönetimini otomatik olarak halleder.
const txHash = await window.ethereum.request({
method: 'eth_sendTransaction',
params: [{
from: account,
to: '0xRecipientAddressHere',
value: '0x38d7ea4c68000', // 0.001 ETH in wei, hex
}],
});
Bir Zincir Değiştir veya Ekle
EIP-3326 ve EIP-3085, bilinen bir zincire geçiş yapmayı ve yeni bir zincir eklemeyi kapsar.
// 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 },
}],
});
}
}
MetaMask SDK ile React
SDK, masaüstü uzantısı, mobil derin bağlantı ve uygulama içi tarayıcıyı kapsayan tek bir entegrasyon yolu istediğinizde normal React'te de iyi çalışır.
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>
);
}
Üretim uygulamaları için, ham sağlayıcıyı ethers.js v6 veya viem içine sarın. Bunlar, temelinde aynı MetaMask API'siyle konuşmaya devam ederken size yazılı sözleşmeler, ABI kod çözücüler ve daha iyi hata mesajları sağlar. Yedek olarak e-posta veya sosyal girişlere de ihtiyacınız varsa, MetaMask'ı Privy API rehberimiz aracılığıyla gömülü bir cüzdanla eşleştirin.
Yaygın Hatalar ve Hız Sınırları
MetaMask standart JSON-RPC hata kodları döndürür. En sık karşılaşacaklarınız:
4001: Kullanıcı isteği reddetti. Dostça bir "bağlantı iptal edildi" uyarısı gösterin ve otomatik olarak yeniden denemeyin.4100: Yetkilendirilmemiş. Hesap bağlı değil; önceeth_requestAccountsçağrısı yapın.4200: Desteklenmeyen yöntem. Nadirdir, ancak satıcıya özel yöntemleri çağırmadan önce cüzdanın MetaMask olduğundan emin olun.4902: Zincir eklenmedi. Ardındanwallet_addEthereumChainile devam edin.-32002: İstek zaten beklemede. Kullanıcılar bazen düğmeye iki kez tıklar; kendi tarafınızda gecikme (debounce) uygulayın.
Sağlayıcının kendisinde hız sınırı yoktur, ancak temel RPC'de vardır. Okumaları Infura veya Alchemy üzerinden vekil ediyorsanız, onların katman sınırlamalarına tabisinizdir. ETH'den USD'ye dönüştürme gibi fiat akışları için çoğu ekip, bu entegrasyonu bir fiat para yatırma ve çekme API'si ile eşleştirir, böylece kullanıcılar dApp'ten ayrılmadan bakiye yükleyebilirler.
MetaMask API Fiyatlandırması
MetaMask uzantısı ve SDK ücretsizdir. Bağlantı başına, imza başına veya işlem başına ücret alınmaz. MetaMask, kullanıcılar cüzdan içinde işlem yaptığında takas ücretlerinden ve MetaMask Kart aracılığıyla gelir elde eder, dApp geliştiricilerinden değil.
Ödeyeceğiniz maliyetler, dApp'inizin okumalar için kullandığı RPC uç noktasından kaynaklanır. Ücretsiz bir Alchemy veya Infura katmanı çoğu küçük uygulamayı kaldırır; üretim dApp'leri genellikle özel iş hacmi için ayda 49 ila 299 dolar arasında maliyetlendirilir.
MetaMask API'sini Apidog ile Test Etme
Tarayıcı tabanlı imzalama, istek akışının bir uzantı, bir sayfa ve bazen mobil bir derin bağlantı arasında yayılması nedeniyle hata ayıklaması zordur. İşte burada Apidog, cüzdan geliştirici araç setinde yerini alır. dApp'inizin kullandığı ham JSON-RPC uç noktasına erişebilir, eth_chainId ve eth_getBalance'in beklediğiniz değeri döndürdüğünü doğrulayabilir ve tüm akışı bir test paketi olarak kaydedebilirsiniz.
Ethereum JSON-RPC spesifikasyonunu içe aktarın, düğüm URL'nizi bir ortam değişkeni olarak ayarlayın ve her EVM zinciri için yeniden kullanılabilir bir koleksiyona sahip olun. Apidog ayrıca yanıtları taklit eder, böylece akıllı sözleşme hala denetimdeyken ön uç geliştiricileriniz sahte bir eth_sendTransaction'a karşı geliştirme yapabilir. CI için, aynı koleksiyonu komut satırından çalıştırabilir ve bir yanıt şekli değişirse derlemeyi başarısız edebilirsiniz. Ekip genelinde asla senkronize olmayan Postman koleksiyonlarıyla mücadele ediyorsanız, 2026'da Postman olmadan API testi hakkındaki rehberimiz, Apidog'un çok protokollü dApp testini neden daha iyi ele aldığını açıklar.
Başlamak için Apidog'u İndirin.
Sıkça Sorulan Sorular
MetaMask API mobil cihazlarda çalışır mı?Evet. İmzalama için mobil uygulamaya derin bağlantı kuran MetaMask SDK'sını kullanın. Sağlayıcı yüzeyi tarayıcı uzantısıyla aynıdır, bu nedenle kodunuz değişmeden kalır. Diğer mobil cüzdan SDK'larıyla daha derin bir karşılaştırma için, en iyi kripto cüzdan API'si derlememize bakın.
eth_sign, personal_sign ve eth_signTypedData_v4 arasındaki fark nedir?eth_sign ham baytları imzalar ve tehlikelidir; MetaMask kullanıcıları agresif bir şekilde uyarır. personal_sign insan tarafından okunabilir bir mesajın önüne ekleme yapar. eth_signTypedData_v4 yapılandırılmış EIP-712 verilerini imzalar ve alanları MetaMask UI'sında düzgün bir şekilde gösterir. Son ikisini kullanın; eth_sign'dan kaçının.
MetaMask'tan ayrı bir API anahtarına ihtiyacım var mı?Hayır. Sağlayıcı ücretsiz ve anahtarsızdır. Cüzdanın dışındaki okumalar için kendi anahtarlarına sahip olan Alchemy veya Infura gibi bir RPC sağlayıcısına ihtiyacınız vardır.
ethers.js veya viem'i MetaMask ile kullanabilir miyim?Evet, her ikisi de window.ethereum sağlayıcısını sarmalar. Ethers v6, BrowserProvider(window.ethereum)'u gösterir ve viem'de createWalletClient({ transport: custom(window.ethereum) }) bulunur. Çoğu üretim dApp'i ikisinden birini kullanır.
Bir kullanıcının birden fazla cüzdanı kuruluysa ne olur?MetaMask, EIP-6963'ü uygular, böylece dApp'ler window.ethereum üzerinde çekişmek yerine kurulu tüm cüzdanları tespit edebilir. Wagmi ve RainbowKit bunu otomatik olarak halleder.
MetaMask Snaps üretim için hazır mı?Evet, Snaps 2024'te genel kullanıma sunuldu. Çoğu üretim kullanımı EVM dışı zincir desteği, özel işlem analizleri ve donanım cüzdanı entegrasyonları içindir.