Tobias Hoffmann

Posted on Apr 23 • Originally published at apidog.com

MetaMask API Kullanımı: dApp'inizi Ethereum Cüzdanlarına Bağlayın

MetaMask, on milyonlarca kullanıcı için Ethereum’a varsayılan geçiş noktasıdır. Bir dApp geliştiriyorsanız, MetaMask API; kullanıcı arayüzünüzle onların imzalama anahtarları arasında köprü görevi görür. “MetaMask API”, aslında iki şeydir: EIP-1193 ile tanımlanan ve tarayıcıya enjekte edilen window.ethereum sağlayıcısı ile bu arayüzü mobil uygulamalar, React Native ve Node.js arka uçlarına genişleten MetaMask SDK’sı. Sağlayıcıyı öğrendiğinizde, web üzerindeki cüzdan entegrasyonlarının %80’ini halletmiş olursunuz.

Apidog'u bugün deneyin

Bu rehberde 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/değiştirme ve MetaMask SDK’sının uzantı dışındaki kullanımına kadar tüm temel entegrasyonları bulacaksınız. Ayrıca ethers.js v6 ve viem gibi üst düzey sarmalayıcıların nasıl devreye girdiğini ve temel JSON-RPC çağrılarını frontend kodu yazmadan test etmek için Apidog’un pratik kullanımını göreceksiniz.

Cüzdan entegrasyonu geliştiriyorsanız, sağlayıcı ekosistemine kapsamlı bakış için bu rehberi ve en iyi kripto cüzdan API’leri rehberimizi de favorilerinize ekleyin.

Özet

MetaMask API, tarayıcılarda window.ethereum adresindeki EIP-1193 sağlayıcısı ve mobil/Node için MetaMask SDK’sıdır.
Kullanıcı bağlantısı için eth_requestAccounts ile başlayın, ardından accountsChanged ve chainChanged olaylarını dinleyin.
Mesaj imzalamak için personal_sign ve yapılandırılmış veri için eth_signTypedData_v4 (EIP-712) kullanılır.
Ağ değiştirmek için wallet_switchEthereumChain (EIP-3326), yeni zincir eklemek için wallet_addEthereumChain (EIP-3085) kullanılır.
ethers.js v6, viem ve wagmi gibi kütüphaneler sağlayıcıyı sarmalar; Snaps ise MetaMask’ı genişletir.
JSON-RPC uç noktalarını test etmek, işlemleri taklit etmek ve imzaları debug etmek için Apidog’dan yararlanın.

MetaMask API Nedir?

MetaMask API, web sayfalarına ve uygulamalara Ethereum/EVM zincirleriyle etkileşim için standart sağlayıcı sunar. Tarayıcıda, uzantı window.ethereum’a bir sağlayıcı objesi enjekte eder ve bu, EIP-1193 standardına uyar. EIP-1193’ü destekleyen bir dApp, MetaMask ve benzeri cüzdanlarla tek kod tabanıyla uyumludur.

Tarayıcı dışında ise MetaMask SDK ile React Native, Node.js, Electron veya sunucu tarafı betiklerde aynı sağlayıcı ara yüzünü kullanabilirsiniz. SDK, mobil cüzdanda imzalama işlemlerini derin bağlantı ve QR kod yönetimiyle halleder. Temelde yine EIP-1193 konuşur; uygulama kodunuz değişmez.

Ayrıca MetaMask, üçüncü tarafların cüzdana yeni zincirler, özel RPC metotları veya hesap türleri eklemesine izin veren Snaps eklenti sistemine de sahiptir.

Kimlik Doğrulama ve Kurulum

Sağlayıcı için API anahtarı gerekmez. Kimlik doğrulama, kullanıcının cüzdan arayüzünde isteği onaylamasıdır. İlk adım olarak sağlayıcıyı tespit etmeniz ve olay dinleyicilerini bağlamanız gerekir.

Sağlayıcı tespiti için @metamask/detect-provider paketini kullanabilirsiniz:

// 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');
}

Olay dinleyicilerini sağlayıcıya sahip olduktan hemen sonra ekleyin:

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) => {
  // Zincir değiştiğinde sayfayı yenilemek en iyi uygulamadır
  window.location.reload();
});

React için wagmi kütüphanesi, tespit ve dinleyici ekleme işlemini sizin için otomatize eder.

Temel Uç Noktalar

Tüm sağlayıcı çağrıları window.ethereum.request({ method, params }) ile yapılır. İşte en çok kullanılan çağrılar:

Hesapları İste ve Zinciri Oku

// Kullanıcıyı bağlantıya yönlendir
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Mevcut zinciri oku
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

console.log(account, chainId); // '0x...' '0x1'

Aynı işlemi doğrudan bir Ethereum node’una curl ile göndermek için:

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 şart değildir; Alchemy veya Infura gibi RPC sağlayıcılar da kullanılabilir. Detaylı bilgi için Alchemy API rehberimize bakabilirsiniz.

Basit Bir Mesaj İmzala

personal_sign ile kullanıcıdan okunabilir bir mesaj imzalamasını isteyebilirsiniz:

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

Daha karmaşık, yapılandırılmış veri için eth_signTypedData_v4 kullanın:

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

eth_sendTransaction ile işlem gönderin:

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere',
    value: '0x38d7ea4c68000', // 0.001 ETH in wei, hex formatında
  }],
});

Zincir Değiştir veya Ekle

Ağ değiştirmek ve yeni zincir eklemek için örnek kod:

// Polygon (chainId 137 = 0x89)'a geçiş
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Zincir eklenmemişse ekle
    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

MetaMask SDK, tarayıcı, mobil ve uygulama içi entegrasyonu birleştirmek için React’ta da kullanılabilir:

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 ortamında, sağlayıcıyı ethers.js v6 veya viem ile sarmak daha iyi tip desteği ve hata yönetimi sağlar. Alternatif olarak, e-posta/sosyal login gibi yedek cüzdan seçenekleri için MetaMask’ı Privy API rehberi ile entegre edebilirsiniz.

Yaygın Hatalar ve Hız Sınırları

MetaMask, standart JSON-RPC hata kodları döndürür. En sık karşılaşılanlar:

4001: Kullanıcı isteği reddetti.
4100: Yetkilendirilmemiş. Önce eth_requestAccounts çağrısı yapmalısınız.
4200: Desteklenmeyen yöntem. Vendor’a özel çağrılarda dikkatli olun.
4902: Zincir eklenmedi. Ardından wallet_addEthereumChain çağırın.
-32002: İstek beklemede. Aynı anda birden fazla isteği engellemek için debouncing uygulayın.

Sağlayıcıda hız limiti yoktur fakat kullanılan temel RPC servisinde olabilir. Okumalar için Infura/Alchemy gibi sağlayıcıların ücretli planlarına ihtiyacınız olabilir. Fiat entegrasyonları için fiat para yatırma ve çekme API’leri ile entegre olabilirsiniz.

MetaMask API Fiyatlandırması

MetaMask uzantısı ve SDK ücretsizdir; bağlantı, imza veya işlem başına ücret yoktur. MetaMask’ın geliri kullanıcı işlemlerinden gelir, geliştiriciden değil.

Tek maliyetiniz, okuma işlemleri için kullandığınız RPC uç noktasıdır. Ücretsiz Alchemy/Infura katmanları küçük projeler için yeterli olabilir; büyük projeler için aylık 49–299$ arası özel katmanlar gerekebilir.

MetaMask API’sini Apidog ile Test Etme

Tarayıcı-tabanlı imzalama ve bağlantı akışları, hata ayıklaması zor olabilir. Apidog, JSON-RPC uç noktalarınızı kolayca test etmenizi sağlar: eth_chainId ve eth_getBalance gibi yöntemleri doğrulayabilir, işlemleri taklit edebilir ve tüm testleri koleksiyon halinde saklayabilirsiniz.

Ethereum JSON-RPC spesifikasyonunu içe aktararak, düğüm URL’nizi ortam değişkeni olarak atayabilir ve farklı zincirler için koleksiyonlar oluşturabilirsiniz. Apidog, yanıtlara mock ekleyerek frontend geliştirme süreci sırasında gerçek işlemler olmadan geliştirme yapmanıza olanak sağlar. CI/CD ortamında aynı koleksiyonu komut satırından çalıştırabilir, yanıt değişirse build’i başarısız kılabilirsiniz. Postman koleksiyonlarıyla yaşadığınız senkronizasyon problemleri için Postman olmadan API testi rehberine göz atın.

Başlamak için Apidog’u İndirin.

Sıkça Sorulan Sorular

MetaMask API mobilde çalışır mı?

Evet. Mobil uygulamalarda imzalama için MetaMask SDK’sını kullanın. Sağlayıcı arayüzü tarayıcı uzantısıyla aynıdır. Farklı mobil cüzdan SDK’larını kıyaslamak için en iyi kripto cüzdan API’leri derlememize bakabilirsiniz.

eth_sign, personal_sign ve eth_signTypedData_v4 farkları nedir?

eth_sign ham baytları imzalar ve güvenli değildir; MetaMask kullanıcıyı uyarır. personal_sign insan tarafından okunabilir mesajı ön ekler. eth_signTypedData_v4, EIP-712 yapılandırılmış verisini imzalar ve alanları arayüzde görünür kılar. Son ikisini tercih edin, eth_sign’dan kaçının.

MetaMask’tan ayrı bir API anahtarı gerekir mi?

Hayır. Sağlayıcı ücretsiz ve anahtarsızdır. Sadece RPC okumaları için Alchemy/Infura gibi servislerden anahtar gerekir.

ethers.js veya viem’i MetaMask ile kullanabilir miyim?

Evet. Her ikisi de window.ethereum’u sarmalar. Ethers v6’da BrowserProvider(window.ethereum), viem’de createWalletClient({ transport: custom(window.ethereum) }) kullanılır.

Birden fazla cüzdan kuruluysa ne olur?

MetaMask, EIP-6963’ü uygular. Bu sayede dApp’ler window.ethereum üzerinden tüm kurulu cüzdanları tespit edebilir. wagmi ve RainbowKit bunu otomatik yapar.

MetaMask Snaps üretim için hazır mı?

Evet, Snaps 2024’te genel kullanıma açıldı. EVM dışı zincir desteği, özel işlem analizleri ve donanım cüzdan entegrasyonu gibi üretim senaryoları yaygındır.

DEV Community